Caching

Caching is keeping the result of work so the work does not have to happen again. It is the cheapest large performance improvement available, and it is also where the most confusing bugs come from, because a cached system can be correct for every request except the one that matters.

The easy part is storing a value. The hard part is knowing when the stored value stopped being true. That problem is called invalidation, and no amount of configuration removes it — you either expire things on a timer, or you actively remove them when the underlying data changes, or you accept staleness on purpose.

Decide which of those three you are doing before you add a cache. A cache added without that decision is a source of wrong answers that nobody can reproduce.

builder.Services.AddOutputCache(options =>
{
    // Nothing is cached unless an endpoint opts in.
    options.AddBasePolicy(policy => policy.NoCache());

    options.AddPolicy("DepartmentList", policy => policy
        .Expire(TimeSpan.FromMinutes(5))
        .SetVaryByQuery("page", "pageSize")
        .Tag("departments"));
});

WebApplication app = builder.Build();

app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseOutputCache();      // after authentication and authorization
app.MapControllers();

// ---

[HttpGet]
[OutputCache(PolicyName = "DepartmentList")]
public async Task<ActionResult<IReadOnlyList<DepartmentSummary>>> List(
    int page = 1,
    int pageSize = 25,
    CancellationToken cancellationToken = default)
{
    return Ok(await departments.ListAsync(page, pageSize, cancellationToken));
}

// ---

[HttpPost]
public async Task<IActionResult> Create(
    CreateDepartmentRequest request,
    [FromServices] IOutputCacheStore cacheStore,
    CancellationToken cancellationToken)
{
    DepartmentSummary created = await departments.CreateAsync(request, cancellationToken);

    // The list is now wrong. Remove every entry carrying this tag.
    await cacheStore.EvictByTagAsync("departments", cancellationToken);

    return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);
}

• A base policy of NoCache means caching is opt-in per endpoint. The opposite default makes it too easy for an endpoint to be cached by accident, which is the failure mode later in this lesson.
• Expire sets how long an entry stays usable. SetVaryByQuery adds the named query values to the cache key, so page 2 does not serve page 1's rows. Anything that changes the response and is not in the key is a bug waiting for traffic.
• Tag groups related entries so they can be removed together.
• EvictByTagAsync after a write is the active invalidation half. Without it, a newly created department is missing from the list for up to five minutes, and somebody will report that as a save failure.
• UseOutputCache is registered after authentication and authorization. Put it earlier and the cache can serve a stored response before the framework has established who is asking.

public sealed class DepartmentLookup(
    HrDbContext db,
    IMemoryCache cache,
    ILogger<DepartmentLookup> logger) : IDepartmentLookup
{
    private const string AllDepartmentsKey = "departments:all";

    public async Task<IReadOnlyList<DepartmentSummary>> GetAllAsync(
        CancellationToken cancellationToken)
    {
        IReadOnlyList<DepartmentSummary>? cached = await cache.GetOrCreateAsync(
            AllDepartmentsKey,
            async entry =>
            {
                entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10);

                logger.LogInformation("Department list cache miss, loading from database");

                return (IReadOnlyList<DepartmentSummary>)await db.Departments
                    .AsNoTracking()
                    .OrderBy(d => d.Name)
                    .Select(d => new DepartmentSummary(d.Id, d.Name, d.Code))
                    .ToListAsync(cancellationToken);
            });

        return cached ?? [];
    }

    // Called by the write path, not on a timer.
    public void Invalidate() => cache.Remove(AllDepartmentsKey);
}

• GetOrCreateAsync either returns the stored value or runs the factory and stores what it produced. One method, so there is no gap between checking and setting.
• AbsoluteExpirationRelativeToNow is the safety net: even if invalidation is missed somewhere, the entry is wrong for at most ten minutes. Prefer absolute expiry over sliding expiry for reference data, because a sliding window on a constantly read key never expires at all.
• The cache miss is logged. Without that line you cannot tell whether the cache is working, and a cache that misses every time is pure overhead.
• Invalidate is deliberate and called from wherever departments are written. A cache with only a timer is a decision to be wrong for up to that long, which is sometimes fine — say it out loud rather than discovering it.
• This cache is per process. Two instances behind a load balancer will disagree for up to ten minutes after a change. If that is not acceptable, this needs to be IDistributedCache instead.