2. Owning Service Setup (3 lines in Program.cs)

// UserManagement service — owns UserEntity, RoleEntity, etc.
services.AddRepletoryRepositories<AppDbContext>(configuration);                         // auto-register ALL repos
services.AddRepletryCacheKeyProviders(typeof(UserCacheKeyProvider).Assembly);           // scan key providers
services.AddRepletryCaching(configuration);                                            // wrap matching repos

That's it — whether you have 5 or 50 entities, it's always 3 lines. Every DbSet<T> on AppDbContext gets an IRepository<T> (for BaseEntity types) or ICompositeKeyRepository<T>, and every entity with a matching ICacheKeyProvider<T> is automatically wrapped with CachedRepository<T>.

3. Consuming Service (reads from shared cache — NO entity registration)

// CourseEnrollment service — only registers entities it OWNS
services.AddRepletoryRepositories<CourseDbContext>(configuration);
services.AddRepletryCacheKeyProviders(typeof(CourseCacheKeyProvider).Assembly);
services.AddRepletryCaching(configuration);

public class CourseEnrollmentService(
    IRepository<CourseEnrollmentEntity> enrollmentRepo,  // cached — owns this entity
    ICacheService cache)                                  // already registered
{
    public async Task<CourseEnrollmentView> GetAsync(Guid id)
    {
        var enrollment = await enrollmentRepo.GetByIdAsync(id);

        // Read User directly from shared cache using static key helper
        var user = await cache.GetAsync<UserEntity>(UserCacheKeys.ById(enrollment!.UserId));

        return new CourseEnrollmentView
        {
            EnrollmentId = enrollment.Id,
            CourseName = enrollment.CourseName,
            UserName = user?.FullName,      // enriched from shared cache
            UserEmail = user?.Email          // no HTTP call to UserManagement
        };
    }
}

Features

Cache Key Providers

Guid-Keyed Entities (ICacheKeyProvider<T>)

For entities inheriting from BaseEntity with a Guid primary key:

public interface ICacheKeyProvider<T> where T : BaseEntity
{
    string EntityPrefix { get; }          // e.g. "user"
    string GetEntityKey(Guid id);         // e.g. "user:{id}"
    string GetIndexKey();                 // e.g. "user:ids"
    TimeSpan? Expiry { get; }            // null = use DefaultExpiryMinutes from options
}

Composite-Keyed Entities (ICompositeKeyCacheKeyProvider<T>)

For entities with composite primary keys:

public interface ICompositeKeyCacheKeyProvider<T> where T : class
{
    string EntityPrefix { get; }
    string GetEntityKey(object[] keyValues);
    string GetIndexKey();
    string SerializeKeyValues(object[] keyValues);     // for index storage
    object[] DeserializeKeyValues(string serialized);  // for index retrieval
    TimeSpan? Expiry { get; }
}

Example implementation:

public class OrderItemCacheKeyProvider : ICompositeKeyCacheKeyProvider<OrderItemEntity>
{
    public string EntityPrefix => "order_item";
    public string GetEntityKey(object[] keyValues) => $"order_item:{keyValues[0]}:{keyValues[1]}";
    public string GetIndexKey() => "order_item:ids";
    public string SerializeKeyValues(object[] keyValues) => $"{keyValues[0]}:{keyValues[1]}";
    public object[] DeserializeKeyValues(string serialized)
    {
        var parts = serialized.Split(':');
        return [Guid.Parse(parts[0]), Guid.Parse(parts[1])];
    }
    public TimeSpan? Expiry => TimeSpan.FromMinutes(15);
}

ID Index Pattern

Each cached entity type maintains an ID index — a single cache key storing all entity IDs for that type:

Cache Key: "user:ids"
Value:     [guid1, guid2, guid3, ...]

Cache Key: "user:{guid1}"
Value:     { Id: guid1, FullName: "Alice", Email: "alice@example.com", ... }

Cache Key: "user:{guid2}"
Value:     { Id: guid2, FullName: "Bob", Email: "bob@example.com", ... }

The index enables GetAllAsync, FindAsync, pagination, and streaming without hitting the database.

Extension Methods on ICacheService

These methods are available to any service that has ICacheService registered — no per-entity registration needed:

Get All Entities

var users = await cache.GetAllFromIndexAsync<UserEntity>(
    UserCacheKeys.IndexKey, UserCacheKeys.ById);

Find with Filter

var activeUsers = await cache.FindFromIndexAsync<UserEntity>(
    UserCacheKeys.IndexKey, UserCacheKeys.ById,
    u => u.IsActive);

Pagination

var page = await cache.GetPagedFromIndexAsync<UserEntity>(
    UserCacheKeys.IndexKey, UserCacheKeys.ById,
    page: 2, pageSize: 20);

// page.Items          — entities on this page
// page.TotalCount     — total entities in index
// page.TotalPages     — computed total pages
// page.HasNextPage    — true if more pages after this one
// page.HasPreviousPage — true if pages before this one

Paginated + Filtered

var activePage = await cache.FindPagedFromIndexAsync<UserEntity>(
    UserCacheKeys.IndexKey, UserCacheKeys.ById,
    u => u.IsActive,
    page: 1, pageSize: 50);

Streaming in Batches

await foreach (var batch in cache.StreamFromIndexAsync<UserEntity>(
    UserCacheKeys.IndexKey, UserCacheKeys.ById, batchSize: 100))
{
    foreach (var user in batch.Items)
        ProcessUser(user);

    Console.WriteLine(
        $"Batch {batch.BatchNumber}/{batch.TotalBatches}, " +
        $"processed {batch.ProcessedCount}/{batch.TotalCount}, " +
        $"has more: {batch.HasMore}");
}

Check Entity Existence

var exists = await cache.EntityExistsAsync(UserCacheKeys.ById(userId));

Composite Key Extensions

All the above methods have composite-key equivalents:

// Get all composite-keyed entities
var items = await cache.GetAllFromCompositeIndexAsync<OrderItemEntity>(
    OrderItemCacheKeys.IndexKey, OrderItemCacheKeys.BySerializedKey);

// Paginated
var page = await cache.GetPagedFromCompositeIndexAsync<OrderItemEntity>(
    OrderItemCacheKeys.IndexKey, OrderItemCacheKeys.BySerializedKey,
    page: 1, pageSize: 50);

// Stream
await foreach (var batch in cache.StreamFromCompositeIndexAsync<OrderItemEntity>(
    OrderItemCacheKeys.IndexKey, OrderItemCacheKeys.BySerializedKey,
    batchSize: 100))
{
    // process batch.Items
}

CachedRepository Method Strategies

The CachedRepository<T> decorator wraps IRepository<T> transparently:

Distributed Locking

When IDistributedLockService is registered (e.g., via RepletoryLib.Caching.Redis), index mutations are protected with a distributed lock to prevent race conditions across multiple instances:

AddToIndex:    lock("lock:user:ids") → read index → add ID → write → release
RemoveFromIndex: lock("lock:user:ids") → read index → remove ID → write → release

When IDistributedLockService is not registered, index updates use simple read-modify-write without locking.

Configuration

{
  "Caching": {
    "Repository": {
      "DefaultExpiryMinutes": 60,
      "EnableIndexKey": true,
      "MaxEntitiesForInMemoryFilter": 10000,
      "FallbackToDbForFind": true
    }
  }
}

DI Registration

Auto-Discovery (Recommended)

// 1. Auto-register all repositories from DbContext
services.AddRepletoryRepositories<AppDbContext>(configuration);

// 2. Scan assembly for ICacheKeyProvider<T> implementations
services.AddRepletryCacheKeyProviders(typeof(UserCacheKeyProvider).Assembly);

// 3. Auto-wrap all matching repos with cached decorators
services.AddRepletryCaching(configuration);

Explicit Per-Entity Registration

// Register a specific entity's cached repository
services.AddRepletryCachedRepository<UserEntity>(configuration);

// Register a composite-key entity's cached repository
services.AddRepletryCachedCompositeKeyRepository<OrderItemEntity>(configuration);

Models

PagedCacheResult<T>

public class PagedCacheResult<T>
{
    public IReadOnlyList<T> Items { get; set; }
    public int TotalCount { get; set; }
    public int Page { get; set; }
    public int PageSize { get; set; }
    public int TotalPages { get; }          // computed
    public bool HasNextPage { get; }        // computed
    public bool HasPreviousPage { get; }    // computed
}

StreamBatch<T>

public class StreamBatch<T>
{
    public IReadOnlyList<T> Items { get; set; }
    public int BatchNumber { get; set; }
    public int TotalBatches { get; set; }
    public int TotalCount { get; set; }
    public int ProcessedCount { get; set; }  // cumulative items yielded so far
    public bool HasMore { get; }             // computed
}

Dependencies

Cross-Service Usage Summary