HybridCache — L1 + L2 Caching With Stampede Protection

// IMemoryCache — fast, in-process, no distributed support
cache.GetOrCreate(key, entry => { ... });

// IDistributedCache — distributed but slow (serialization + network), no stampede protection
var bytes = await distributedCache.GetAsync(key);
var value = JsonSerializer.Deserialize<T>(bytes);

Request
   │
   ▼
L1: IMemoryCache (in-process)
   │ miss
   ▼
L2: IDistributedCache (Redis / SQL / etc.)
   │ miss
   ▼
Factory function (database / API call)
   │
   ▼ (result stored in both L2 and L1)
Response

dotnet add package Microsoft.Extensions.Caching.Hybrid

// Program.cs

// L2 backing store — Redis
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
    options.InstanceName = "myapp:";
});

// HybridCache — wraps both layers
builder.Services.AddHybridCache(options =>
{
    options.MaximumPayloadBytes = 1024 * 1024;  // 1MB max per entry
    options.MaximumKeyLength = 512;

    // Default TTLs (overridable per-entry)
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),          // L2 TTL
        LocalCacheExpiration = TimeSpan.FromMinutes(1) // L1 TTL (shorter)
    };
});

public class ProductService(HybridCache cache, IProductRepository repo)
{
    public async Task<Product?> GetProductAsync(int id, CancellationToken ct = default)
    {
        return await cache.GetOrCreateAsync(
            key: $"product:{id}",
            factory: async (token) => await repo.FindByIdAsync(id, token),
            cancellationToken: ct);
    }
}

public async Task<IReadOnlyList<Category>> GetCategoriesAsync(CancellationToken ct = default)
{
    return await cache.GetOrCreateAsync(
        key: "categories:all",
        factory: async (token) => await repo.GetAllCategoriesAsync(token),
        options: new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromHours(1),           // Redis TTL
            LocalCacheExpiration = TimeSpan.FromMinutes(5) // Memory TTL
        },
        tags: ["categories"],  // for tag-based invalidation
        cancellationToken: ct);
}

// 1000 concurrent requests for "product:42" — only one DB call
var tasks = Enumerable.Range(0, 1000)
    .Select(_ => cache.GetOrCreateAsync("product:42", async _ =>
        await repo.FindByIdAsync(42, ct)));

var results = await Task.WhenAll(tasks); // all get the same value, one DB hit

// Store with tags
await cache.GetOrCreateAsync(
    "product:1",
    async _ => await repo.FindByIdAsync(1, ct),
    tags: ["products", "catalogue"],
    cancellationToken: ct);

await cache.GetOrCreateAsync(
    "product:2",
    async _ => await repo.FindByIdAsync(2, ct),
    tags: ["products", "catalogue"],
    cancellationToken: ct);

// Invalidate all entries tagged "products" — across all instances
await cache.RemoveByTagAsync("products", ct);

public class ProductsController(HybridCache cache, IProductService svc) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(CreateProductRequest request, CancellationToken ct)
    {
        var product = await svc.CreateProductAsync(request, ct);
        await cache.RemoveByTagAsync("products", ct);
        return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
    }

    [HttpDelete("{id:int}")]
    public async Task<IActionResult> Delete(int id, CancellationToken ct)
    {
        await svc.DeleteProductAsync(id, ct);
        // Remove specific entry AND invalidate list caches
        await cache.RemoveAsync($"product:{id}", ct);
        await cache.RemoveByTagAsync("products", ct);
        return NoContent();
    }
}

builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),
        LocalCacheExpiration = TimeSpan.FromMinutes(1)
    };

    // These apply to all entries — override at call site for specific needs
    options.MaximumPayloadBytes = 512 * 1024; // 512KB
});

builder.Services.AddHybridCache()
    .AddSerializer<Product, ProductSerializer>(); // custom IHybridCacheSerializer<T>

// Or register a default serializer factory for all types
builder.Services.AddHybridCache()
    .AddSerializerFactory<MessagePackSerializerFactory>();