ASP.NET Core Caching: Output Cache, Redis & Invalidation Strategies That Actually Work

dotnet new webapi -n CachingCatalogApi --use-minimal-apis
cd CachingCatalogApi
dotnet run

# Output Cache Redis backing store dotnet add package Microsoft.AspNetCore.OutputCaching.StackExchangeRedis # IDistributedCache Redis implementation dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis # EF Core + SQLite for the data layer (not the focus here) dotnet add package Microsoft.EntityFrameworkCore.Sqlite dotnet add package Microsoft.EntityFrameworkCore.Design # Metrics dotnet add package System.Diagnostics.DiagnosticSource

public class Category
{
    public int    Id   { get; set; }
    public string Name { get; set; } = "";
    public ICollection<Product> Products { get; set; } = [];
}

public class Product
{
    public int     Id          { get; set; }
    public string  Name        { get; set; } = "";
    public string  Description { get; set; } = "";
    public decimal Price       { get; set; }
    public bool    IsActive    { get; set; } = true;
    public int     CategoryId  { get; set; }
    public Category Category   { get; set; } = null!;

    // Changes on every update — useful as a vary key and for ETag generation
    public DateTimeOffset UpdatedAt { get; set; } = DateTimeOffset.UtcNow;
}

// DTOs — cache the response shape, never the domain entity
public record ProductSummary(int Id, string Name, decimal Price, int CategoryId);
public record ProductDetail(int Id, string Name, string Description,
                            decimal Price, bool IsActive, int CategoryId,
                            string CategoryName, DateTimeOffset UpdatedAt);

GOOD CACHING CANDIDATES
  GET /products              — list, changes infrequently, same for all users
  GET /products/{id}         — single product detail, stable between edits
  GET /categories            — reference data, changes very rarely
  GET /products?category=3   — filtered list, stable until category data changes

CACHE WITH CARE — vary rules required
  GET /products?page=2&sort=price  — vary by all query params, or cache serves wrong data
  GET /search?q=laptop             — vary by query, watch for key cardinality explosion
  GET /products (Accept: text/csv) — vary by Accept header if multiple formats served

DO NOT CACHE
  POST /products             — mutating — never cache write operations
  PUT  /products/{id}        — mutating
  DELETE /products/{id}      — mutating
  GET /cart                  — user-specific, personalised
  GET /orders                — user-specific, security-sensitive
  Any endpoint returning Set-Cookie — Output Cache skips these by default
  Any response with Cache-Control: no-store from downstream — honour it

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOutputCache(options =>
{
    // Base policy: no caching by default — endpoints opt in explicitly
    options.AddBasePolicy(policy => policy.NoCache());

    // Products list: 5-minute TTL, vary by all relevant query params
    options.AddPolicy("ProductList", policy =>
        policy
            .Expire(TimeSpan.FromMinutes(5))
            .SetVaryByQuery("category", "sort", "page", "pageSize", "search")
            .Tag("products")
            .SetCacheKeyPrefix("catalog:products:list:"));

    // Product detail: 10-minute TTL, vary by route id only
    options.AddPolicy("ProductDetail", policy =>
        policy
            .Expire(TimeSpan.FromMinutes(10))
            .SetVaryByRouteValue("id")
            .Tag("products")
            .Tag("product-{id}")       // per-product tag for surgical eviction
            .SetCacheKeyPrefix("catalog:products:detail:"));

    // Categories: 30-minute TTL — changes very rarely
    options.AddPolicy("CategoryList", policy =>
        policy
            .Expire(TimeSpan.FromMinutes(30))
            .Tag("categories")
            .SetCacheKeyPrefix("catalog:categories:"));
});

var app = builder.Build();

app.UseHttpsRedirection();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

// Output Cache: AFTER auth middleware (so it can see identity for vary rules)
//              BEFORE endpoint execution (so it can short-circuit before handlers run)
app.UseOutputCache();

app.MapProductEndpoints();
app.MapCategoryEndpoints();

app.Run();

public static class ProductEndpoints
{
    public static void MapProductEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/products").WithTags("Products");

        // List — vary rules applied by the "ProductList" policy
        group.MapGet("/", async (
            [FromQuery] int?    category,
            [FromQuery] string? sort,
            [FromQuery] int     page     = 1,
            [FromQuery] int     pageSize = 20,
            CatalogDbContext    db       = null!) =>
        {
            var query = db.Products.Where(p => p.IsActive).AsQueryable();

            if (category.HasValue)
                query = query.Where(p => p.CategoryId == category.Value);

            query = sort switch
            {
                "price"      => query.OrderBy(p => p.Price),
                "price_desc" => query.OrderByDescending(p => p.Price),
                "name"       => query.OrderBy(p => p.Name),
                _            => query.OrderBy(p => p.Id)
            };

            var items = await query
                .Skip((page - 1) * pageSize).Take(pageSize)
                .Select(p => new ProductSummary(p.Id, p.Name, p.Price, p.CategoryId))
                .ToListAsync();

            return Results.Ok(items);
        })
        .CacheOutput("ProductList");   // apply the named policy

        // Detail — varies by route {id}, tags with "product-{id}"
        group.MapGet("/{id:int}", async (int id, CatalogDbContext db) =>
        {
            var product = await db.Products
                .Include(p => p.Category)
                .Where(p => p.Id == id && p.IsActive)
                .Select(p => new ProductDetail(
                    p.Id, p.Name, p.Description, p.Price,
                    p.IsActive, p.CategoryId, p.Category.Name, p.UpdatedAt))
                .FirstOrDefaultAsync();

            return product is null ? Results.NotFound() : Results.Ok(product);
        })
        .CacheOutput("ProductDetail");

        // Write endpoints — covered in Section 9
        group.MapPost("/",           CreateProduct);
        group.MapPut("/{id:int}",    UpdateProduct);
        group.MapDelete("/{id:int}", DeleteProduct);
    }
}

# Three-instance deployment, load balancer round-robins requests

Request 1  → Instance A → MISS → DB query → cache FILL on A only
Request 2  → Instance B → MISS → DB query → cache FILL on B only
Request 3  → Instance C → MISS → DB query → cache FILL on C only

# Product 42 is updated — PUT /products/42 routed to Instance B
# Tag eviction fires on Instance B only — A and C still hold the stale entry

Request 4  → Instance A → cache HIT  → STALE data served  ← BUG
Request 5  → Instance B → cache MISS → FRESH data served (evicted)
Request 6  → Instance C → cache HIT  → STALE data served  ← BUG

# With Redis as the backing store:
# All instances share one Redis store
# Fills are immediately visible to every instance
# Tag eviction on Instance B removes entries from Redis — all instances see it

var redisConn = builder.Configuration.GetConnectionString("Redis") ?? "localhost:6379";

// Redis as the Output Cache backing store — replaces the default in-memory store
builder.Services.AddStackExchangeRedisOutputCache(options =>
{
    options.Configuration = redisConn;
    options.InstanceName  = "CatalogApi:OutputCache:"; // key namespace prefix
});

// Redis IDistributedCache — used for manual key/version patterns in Sections 7-8
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = redisConn;
    options.InstanceName  = "CatalogApi:DistCache:";
});

services:
  catalog-api:
    build: .
    ports: ["5000:8080"]
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__Redis=redis:6379
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7.2-alpine
    ports: ["6379:6379"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    command: redis-server --save "" --appendonly no

# Tag taxonomy for the Catalog API
#
# Tag "products"
#   Applied to: ProductList policy, ProductDetail policy
#   Evict when: ANY product changes, is created, or deleted
#   Effect: clears all list pages and all detail entries
#
# Tag "product-{id}"  (e.g. "product-42")
#   Applied to: ProductDetail policy, per product
#   Evict when: the specific product with that ID changes
#   Effect: clears only the detail for product 42 — lists stay warm
#
# Tag "categories"
#   Applied to: CategoryList policy
#   Evict when: any category is created, renamed, or deleted
#
# Design rule: tag granularity should match your invalidation granularity.
# If you always evict all products together, one "products" tag is sufficient.
# If you need per-product precision, add "product-{id}" alongside "products".

public static async Task<IResult> UpdateProduct(
    int                  id,
    UpdateProductRequest request,
    CatalogDbContext     db,
    IOutputCacheStore    cacheStore,
    CancellationToken    ct)
{
    var product = await db.Products.FindAsync([id], ct);
    if (product is null) return Results.NotFound();

    product.Name        = request.Name;
    product.Price       = request.Price;
    product.Description = request.Description;
    product.UpdatedAt   = DateTimeOffset.UtcNow;
    await db.SaveChangesAsync(ct);

    // Surgical eviction: only this product's detail cache entry
    await cacheStore.EvictByTagAsync($"product-{id}", ct);

    // Also evict product lists — they contain this product's summary
    await cacheStore.EvictByTagAsync("products", ct);

    return Results.NoContent();
}

// Centralise all cache key construction — prevents typos, aids invalidation auditing
public static class CacheKeys
{
    public static string ProductDetail(int id)       => $"catalog:product:{id}:detail";
    public static string ProductsByCategory(int id)  => $"catalog:category:{id}:products";
    public static string CategoryAll()               => "catalog:category:all";
    public static string CategoryDetail(int id)      => $"catalog:category:{id}:detail";
    public static string ProductVersion()            => "catalog:version:products";
    public static string CategoryVersion()           => "catalog:version:categories";
}

public class VersionedCacheService(IDistributedCache cache)
{
    // Read the current version for a namespace
    public async Task<long> GetVersionAsync(string versionKey, CancellationToken ct)
    {
        var bytes = await cache.GetAsync(versionKey, ct);
        return bytes is null ? 0 : BitConverter.ToInt64(bytes);
    }

    // Build a versioned cache key — embeds the version number
    // "catalog:product:42:detail:v7" is only valid when version is 7
    public async Task<string> BuildVersionedKeyAsync(
        string baseKey, string versionKey, CancellationToken ct)
    {
        var version = await GetVersionAsync(versionKey, ct);
        return $"{baseKey}:v{version}";
    }

    // Invalidate an entire namespace by incrementing the version counter
    // Old keys with the previous version number are never requested again
    // They expire naturally via their TTL — no explicit bulk delete needed
    public async Task InvalidateNamespaceAsync(string versionKey, CancellationToken ct)
    {
        var current    = await GetVersionAsync(versionKey, ct);
        var newVersion = BitConverter.GetBytes(current + 1);
        await cache.SetAsync(versionKey, newVersion,
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromDays(30)
            }, ct);
    }
}

// On product update: increment the product namespace version
// All keys of the form "catalog:product:*:v{old}" are now effectively stale
await versionedCache.InvalidateNamespaceAsync(CacheKeys.ProductVersion(), ct);

public record ProductChangedEvent(
    int               ProductId,
    ProductChangeType ChangeType,
    DateTimeOffset    OccurredAt);

public enum ProductChangeType { Created, Updated, Deleted, PriceChanged }

// Abstraction over the invalidation mechanism — keeps domain code ignorant of
// whether invalidation uses Output Cache tags, version tokens, or pub/sub
public interface ICacheInvalidator
{
    Task InvalidateProductAsync(int productId, CancellationToken ct = default);
    Task InvalidateAllProductsAsync(CancellationToken ct = default);
    Task InvalidateCategoriesAsync(CancellationToken ct = default);
}

public class OutputCacheInvalidator(IOutputCacheStore store) : ICacheInvalidator
{
    public async Task InvalidateProductAsync(int productId, CancellationToken ct = default)
    {
        await store.EvictByTagAsync($"product-{productId}", ct);
        await store.EvictByTagAsync("products", ct);
    }
    public Task InvalidateAllProductsAsync(CancellationToken ct = default) =>
        store.EvictByTagAsync("products", ct);
    public Task InvalidateCategoriesAsync(CancellationToken ct = default) =>
        store.EvictByTagAsync("categories", ct);
}

// Background service — listens on an in-process channel
// For cross-service events, replace the channel with Redis pub/sub or a message bus
public class CacheInvalidationWorker(
    ChannelReader<ProductChangedEvent> events,
    ICacheInvalidator                  invalidator,
    ILogger<CacheInvalidationWorker>  logger)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await foreach (var evt in events.ReadAllAsync(ct))
        {
            try
            {
                switch (evt.ChangeType)
                {
                    case ProductChangeType.PriceChanged:
                    case ProductChangeType.Updated:
                        await invalidator.InvalidateProductAsync(evt.ProductId, ct);
                        break;
                    case ProductChangeType.Created:
                    case ProductChangeType.Deleted:
                        await invalidator.InvalidateAllProductsAsync(ct);
                        break;
                }
                logger.LogDebug("Cache invalidated: product {Id} ({Type})", evt.ProductId, evt.ChangeType);
            }
            catch (Exception ex)
            {
                // Log but do NOT rethrow — invalidation failure must not crash the worker
                // The cache entry expires naturally at TTL; this is an acceptable degradation
                logger.LogError(ex, "Cache invalidation failed for product {Id}", evt.ProductId);
            }
        }
    }
}

// POST /products — new product appears in list pages; no detail entry yet
private static async Task<IResult> CreateProduct(
    CreateProductRequest req, CatalogDbContext db,
    ICacheInvalidator cache, CancellationToken ct)
{
    var product = new Product
    {
        Name = req.Name, Price = req.Price,
        CategoryId = req.CategoryId, UpdatedAt = DateTimeOffset.UtcNow
    };
    db.Products.Add(product);
    await db.SaveChangesAsync(ct);

    // New product affects ALL list pages (could appear on any page/sort combination)
    // Does NOT affect any existing product's detail entry
    await cache.InvalidateAllProductsAsync(ct);

    return Results.Created($"/products/{product.Id}", product);
}

// PUT /products/{id} — existing product changes
private static async Task<IResult> UpdateProduct(
    int id, UpdateProductRequest req,
    CatalogDbContext db, ICacheInvalidator cache, CancellationToken ct)
{
    var product = await db.Products.FindAsync([id], ct);
    if (product is null) return Results.NotFound();

    var categoryChanged = product.CategoryId != req.CategoryId;
    product.Name = req.Name; product.Price = req.Price;
    product.Description = req.Description; product.CategoryId = req.CategoryId;
    product.UpdatedAt = DateTimeOffset.UtcNow;
    await db.SaveChangesAsync(ct);

    // Always evict this product's detail
    await cache.InvalidateProductAsync(id, ct);

    // Category change also affects category-filtered list pages
    if (categoryChanged) await cache.InvalidateAllProductsAsync(ct);

    return Results.NoContent();
}

// DELETE /products/{id} — product no longer exists in any list or detail
private static async Task<IResult> DeleteProduct(
    int id, CatalogDbContext db,
    ICacheInvalidator cache, CancellationToken ct)
{
    var product = await db.Products.FindAsync([id], ct);
    if (product is null) return Results.NotFound();

    db.Products.Remove(product);
    await db.SaveChangesAsync(ct);

    // Evict this product's detail entry (tag: product-{id})
// AND all product list pages (tag: products) — deleted product must not appear in any list
await cache.InvalidateProductAsync(id, ct);      // evicts product-{id} + products tag
await cache.InvalidateAllProductsAsync(ct);       // belt-and-suspenders: explicitly evict lists
return Results.NoContent();
}

// Output Cache coalesces concurrent requests with the same cache key automatically.
// When 200 requests arrive simultaneously for GET /products?sort=price:
//   Request 1   → cache MISS → proceeds to the handler
//   Requests 2-200 → find a "pending" state → wait for Request 1 to complete
//   When Request 1 stores the response → all waiting requests receive it immediately
//   Result: 1 database query instead of 200

// No code changes needed — coalescing is the default Output Cache behaviour.

// Disable coalescing only if you have strict per-request isolation requirements
// (rarely needed and not recommended for high-traffic endpoints)
options.AddPolicy("NoCoalesce", policy =>
    policy
        .Expire(TimeSpan.FromMinutes(5))
        .AllowLocking(false));   // disables coalescing

// Coalescing is per cache key — high-cardinality endpoints like GET /products/{id}
// have independent locks per product ID, so no contention between different products.

public static class CacheExtensions
{
    private static readonly Random _rng = Random.Shared;

    // Add ±jitterPercent randomisation to the base TTL
    // Base: 10 minutes, jitter: 20% → actual TTL: 8–12 minutes
    // Prevents thousands of simultaneously cached entries from expiring together
    public static TimeSpan WithJitter(this TimeSpan baseTtl, double jitterPercent = 0.2)
    {
        var jitterRange   = baseTtl.TotalSeconds * jitterPercent;
        var jitterOffset  = (_rng.NextDouble() * 2 - 1) * jitterRange; // ±jitterRange
        var jitteredSecs  = baseTtl.TotalSeconds + jitterOffset;
        return TimeSpan.FromSeconds(Math.Max(jitteredSecs, 1)); // minimum 1 second
    }

    public static Task SetWithJitterAsync(
        this IDistributedCache cache,
        string key, byte[] value, TimeSpan baseTtl,
        CancellationToken ct = default)
    {
        var options = new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = baseTtl.WithJitter()
        };
        return cache.SetAsync(key, value, options, ct);
    }
}

// Usage — product detail with jittered 10-minute TTL
await cache.SetWithJitterAsync(
    CacheKeys.ProductDetail(id), serialized,
    TimeSpan.FromMinutes(10), ct);
// Actual TTL: 8–12 minutes — expirations spread, stampede risk eliminated

public class MeteredOutputCacheStore : IOutputCacheStore
{
    private readonly IOutputCacheStore                _inner;
    private readonly ILogger _logger;
    private readonly Counter                    _hits;
    private readonly Counter                    _misses;

    public MeteredOutputCacheStore(
        IOutputCacheStore                inner,
        IMeterFactory                    meterFactory,
        ILogger logger)
    {
        _inner  = inner;
        _logger = logger;
        var meter = meterFactory.Create("CatalogApi");
        _hits   = meter.CreateCounter("cache.hits");
        _misses = meter.CreateCounter("cache.misses");
    }
}

    public async ValueTask<ReadOnlyMemory<byte>?> GetAsync(
        string key, CancellationToken ct)
    {
        var result = await inner.GetAsync(key, ct);
        if (result.HasValue)
        {
            _hits.Add(1, new KeyValuePair<string, object?>("store", "output"));
            logger.LogDebug("Cache HIT: {Key}", key);
        }
        else
        {
            _misses.Add(1, new KeyValuePair<string, object?>("store", "output"));
            logger.LogDebug("Cache MISS: {Key}", key);
        }
        return result;
    }

    public ValueTask SetAsync(string key, ReadOnlyMemory<byte> value,
        string[]? tags, TimeSpan validFor, DateTimeOffset createdAt, CancellationToken ct) =>
        inner.SetAsync(key, value, tags, validFor, createdAt, ct);

    public ValueTask EvictByTagAsync(string tag, CancellationToken ct) =>
        inner.EvictByTagAsync(tag, ct);
}

// Register the wrapper — decorates the Redis store transparently
// Option A: using Scrutor (dotnet add package Scrutor)
builder.Services.AddStackExchangeRedisOutputCache(/* ... */);
builder.Services.Decorate();

// Option B: without Scrutor — register manually
builder.Services.AddStackExchangeRedisOutputCache(/* ... */);
builder.Services.AddSingleton(sp =>
{
    // Resolve the Redis store registered by AddStackExchangeRedisOutputCache
    // Note: use a keyed service or factory pattern to avoid circular resolution
    var inner   = sp.GetRequiredKeyedService("redis"); // if keyed
    var factory = sp.GetRequiredService();
    var logger  = sp.GetRequiredService>();
    return new MeteredOutputCacheStore(inner, factory, logger);
});

// Adds Cache-Status header to every response for debugging without a profiler
// Example headers:
//   Cache-Status: hit; age=42    ← served from cache, 42 seconds old
//   Cache-Status: miss           ← cache miss, response came from origin
//   Cache-Status: bypass         ← caching skipped (write method, authenticated, etc.)

public class CacheStatusHeaderMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context)
    {
        context.Response.OnStarting(() =>
        {
            if (context.Response.Headers.ContainsKey("Age"))
            {
                var age = context.Response.Headers["Age"];
                context.Response.Headers["Cache-Status"] = $"hit; age={age}";
            }
            else if (HttpMethods.IsGet(context.Request.Method) ||
                     HttpMethods.IsHead(context.Request.Method))
            {
                context.Response.Headers["Cache-Status"] = "miss";
            }
            else
            {
                context.Response.Headers["Cache-Status"] = "bypass";
            }
            return Task.CompletedTask;
        });

        await next(context);
    }
}

// Register BEFORE UseOutputCache so it can observe the Age header Output Cache sets
app.UseMiddleware<CacheStatusHeaderMiddleware>();
app.UseOutputCache();