caching

Caching Patterns

Reference for caching in .NET APIs. Covers HybridCache (L1+L2), output caching, cache-aside, and IMemoryCache. Used by dnp-planner and dnp-tdd-developer-hard.

Caching Options at a Glance

Option	Best For	Notes
HybridCache	Application-level data (entities, computed results)	.NET 9+; L1 in-process + L2 distributed; stampede protection
IOutputCache	HTTP response caching (full responses)	Middleware-level; [OutputCache] attribute or .CacheOutput()
IMemoryCache	Single-node, simple key-value, no distributed requirement	No stampede protection; use GetOrCreateAsync
IDistributedCache	Distributed session, custom serialization	Low-level; HybridCache wraps it

HybridCache (.NET 9+)

HybridCache combines an in-process L1 cache (fast) with an optional L2 distributed cache (Redis, SQL). Built-in stampede protection: concurrent requests for the same key share one factory call.

Package

<PackageReference Include="Microsoft.Extensions.Caching.Hybrid" Version="9.*" />
<!-- Optional Redis L2: -->
<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.*" />

Registration

builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        // How long entries live in both L1 and L2
        Expiration = TimeSpan.FromMinutes(5),
        // L1 can expire sooner to reduce stale reads across instances
        LocalCacheExpiration = TimeSpan.FromMinutes(1)
    };
    // Cap serialized value size (protects against runaway entries)
    options.MaximumPayloadBytes = 1024 * 1024; // 1 MB
});

// Optional Redis L2 — add BEFORE AddHybridCache so it's picked up automatically
builder.Services.AddStackExchangeRedisCache(options =>
    options.Configuration = builder.Configuration.GetConnectionString("Redis"));

Usage

public class ProductService(HybridCache cache, AppDbContext db)
{
    public async Task<Product?> GetByIdAsync(int id, CancellationToken ct)
        => await cache.GetOrCreateAsync(
            $"product:{id}",
            async token => await db.Products
                .AsNoTracking()
                .FirstOrDefaultAsync(p => p.Id == id, token),
            cancellationToken: ct);

    public async Task<IReadOnlyList<Product>> GetByCategoryAsync(
        string category, CancellationToken ct)
        => await cache.GetOrCreateAsync(
            $"products:category:{category}",
            async token => await db.Products
                .AsNoTracking()
                .Where(p => p.Category == category)
                .ToListAsync(token),
            options: new HybridCacheEntryOptions { Expiration = TimeSpan.FromMinutes(2) },
            cancellationToken: ct) ?? [];
}