In ASP.NET Core, one of the most powerful and underused caching tools is the Output Cache middleware.

Though so many developers still don't know about it or how to use it effectively.

Output Cache is not the same as storing objects in IMemoryCache or IDistributedCache. It operates at the HTTP response level, caching the full serialized response and serving it directly — without touching your handlers, your database, or your business logic.

The result is dramatically lower latency and reduced load on your infrastructure.

In this post, we will explore:

• What Output Cache is and how it differs from IMemoryCache and IDistributedCache
• How to set up Output Cache in ASP.NET Core
• How to customize cache behavior with policies and options
• How to evict cached responses using tags, keys, and full cache clearing
• How to use Redis as the Output Cache store for distributed scenarios
• How to handle caching safely in authenticated APIs to avoid leaking data between users

Let's dive in.

IMemoryCache is an in-process, key-value store that lives in the memory of your application.

You use it to cache any .NET object — a list, a domain model, a computed value. You control what gets stored, how it is serialized, and when it expires.

It is fast because there is no network hop. But it is local to a single instance of your app, so it does not work across multiple servers without extra coordination.

csharp
1public class OrderService(IMemoryCache cache, OrdersDbContext db)
2{
3    public async Task<List<OrderSummary>> GetOrdersAsync(CancellationToken ct)
4    {
5        return await cache.GetOrCreateAsync("orders:all", async entry =>
6        {
7            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5);
8            
9            return await db.Orders
10                .Select(o => new OrderSummary(o.Id, o.Status, o.TotalAmount))
11                .ToListAsync(ct);
12        });
13    }
14}

IDistributedCache is an abstraction over an external cache store, usually Redis. It stores byte arrays, so you serialize and deserialize your objects manually (or with a wrapper).

It works across multiple app instances because all instances share the same external store. The downside is the added latency of a network call to the cache server.

Both IMemoryCache and IDistributedCache require you to write caching logic inside your service or handler.

You have to call the cache before your database query, check for a hit, store the result after a miss, and handle expiration yourself. This adds boilerplate to every method you want to cache.

Output Cache works differently.

Instead of caching objects inside your application code, Output Cache intercepts the HTTP response at the middleware level. It stores the full serialized response — the status code, headers, and body — and replays it on subsequent matching requests.

Your endpoint handler, database query, and business logic are never called when a cached response is available. The middleware short-circuits the pipeline and writes the stored response directly.

This means you can add caching to existing endpoints with almost no changes to your application code. You decorate an endpoint or controller with an attribute or a policy name, and the middleware handles the rest.

The built-in cache lock feature in Output Cache is particularly useful. When multiple requests arrive for the same uncached resource at the same time, only one request is allowed through to execute the handler.

The others wait for the first response and then receive the cached copy. This prevents the "thundering herd" problem, where a cache miss causes a spike of concurrent database queries.

Output Cache was introduced in .NET 7 and has been improved in further .NET versions.

To get started with Output Cache, install the following NuGet package:

bash
1dotnet add package Microsoft.AspNetCore.OutputCaching

Register Output Cache services in Program.cs:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3// Register OutputCache in DI
4builder.Services.AddOutputCache();
5
6var app = builder.Build();
7
8// Add OutputCache Middleware
9app.UseOutputCache();
10
11app.MapControllers();
12
13app.Run();

The middleware must be placed after UseRouting (if you call it explicitly) and before MapControllers or any Minimal API endpoints like MapGet.

Now, let's define a simple Orders API example:

csharp
1[ApiController]
2[Route("api/orders")]
3public class OrdersController(OrdersDbContext db) : ControllerBase
4{
5    [HttpGet]
6    [OutputCache]
7    public async Task<IActionResult> GetOrders(CancellationToken ct)
8    {
9        var orders = await db.Orders.ToListAsync(ct);
10        return Ok(orders);
11    }
12
13    [HttpGet("{id:guid}")]
14    public async Task<IActionResult> GetOrder(Guid id, CancellationToken ct)
15    {
16        var order = await db.Orders.FindAsync([id], ct);
17        if (order is null) return NotFound();
18        return Ok(order);
19    }
20}

To cache the GetOrders endpoint, we add the [OutputCache] attribute.

With this one attribute, the first request to GET /api/orders will execute the handler, call the database and store the response. Every subsequent request within the default expiration window (60 seconds) will receive the cached response without hitting the database.

You can also cache endpoints in Minimal APIs by calling .CacheOutput() on the RouteHandlerBuilder:

csharp
1app.MapGet("/api/orders", async (OrdersDbContext db, CancellationToken ct) =>
2{
3    var orders = await db.Orders.ToListAsync(ct);
4    return Results.Ok(orders);
5}).CacheOutput();

The default Output Cache behavior uses a 60-second expiration and caches based on the full request URL. In most real applications, you need more control.

You can set a custom expiration time directly on the attribute:

csharp
1[HttpGet]
2[OutputCache(Duration = 120)] // cache for 2 minutes
3public async Task<IActionResult> GetOrders(CancellationToken ct)
4{
5    var orders = await db.Orders.ToListAsync(ct);
6    return Ok(orders);
7}

Or in Minimal APIs:

csharp
1app.MapGet("/api/orders", async (OrdersDbContext db, CancellationToken ct) =>
2{
3    var orders = await db.Orders.ToListAsync(ct);
4    return Results.Ok(orders);
5}).CacheOutput(x => x.Expire(TimeSpan.FromMinutes(2)));

Hard-coding cache options on every endpoint gets messy fast. A better approach is to define named policies during service registration and reference them by name on your endpoints.

This gives you a single place to change cache behavior across multiple endpoints.

csharp
1builder.Services.AddOutputCache(options =>
2{
3    options.AddPolicy("OrdersPolicy", policy =>
4        policy
5            .Expire(TimeSpan.FromMinutes(5))
6            .SetVaryByHeader("Accept-Language")
7            .Tag("orders")
8    );
9
10    options.AddPolicy("OrderDetailPolicy", policy =>
11        policy
12            .Expire(TimeSpan.FromMinutes(2))
13            .SetVaryByRouteValue("id")
14            .Tag("orders")
15    );
16});

Reference the policy by name in your controller:

csharp
1[HttpGet]
2[OutputCache(PolicyName = "OrdersPolicy")]
3public async Task<IActionResult> GetOrders(CancellationToken ct)
4{
5    var orders = await db.Orders.ToListAsync(ct);
6    return Ok(orders);
7}
8
9[HttpGet("{id:guid}")]
10[OutputCache(PolicyName = "OrderDetailPolicy")]
11public async Task<IActionResult> GetOrder(Guid id, CancellationToken ct)
12{
13    var order = await db.Orders.FindAsync([id], ct);
14    if (order is null) return NotFound();
15    return Ok(order);
16}

Or in Minimal APIs:

csharp
1app.MapGet("/api/orders", async (OrdersDbContext db, CancellationToken ct) =>
2{
3    return Results.Ok(await db.Orders.ToListAsync(ct));
4}).CacheOutput("OrdersPolicy");
5
6app.MapGet("/api/orders/{id:guid}", async (Guid id, OrdersDbContext db, CancellationToken ct) =>
7{
8    var order = await db.Orders.FindAsync([id], ct);
9    return order is null ? Results.NotFound() : Results.Ok(order);
10}).CacheOutput("OrderDetailPolicy");

By default, Output Cache stores one version of a response per unique URL. But sometimes the same URL can return different content depending on request properties.

Output Cache supports several VaryBy options:

VaryByHeader — cache a separate response for each value of a given header. Useful for multi-language APIs where the Accept-Language header changes the response content:

csharp
1options.AddPolicy("LocalizedOrdersPolicy", policy =>
2    policy
3        .Expire(TimeSpan.FromMinutes(5))
4        .SetVaryByHeader("Accept-Language")
5        .Tag("orders")
6);

VaryByQuery — cache a separate response for each unique value of a query string parameter. Useful for paginated or filtered endpoints:

csharp
1options.AddPolicy("PagedOrdersPolicy", policy =>
2    policy
3        .Expire(TimeSpan.FromMinutes(5))
4        .SetVaryByQuery("page", "pageSize", "status")
5        .Tag("orders")
6);

With this policy, GET /api/orders?page=1&pageSize=10 and GET /api/orders?page=2&pageSize=10 are stored as two separate cache entries.

VaryByRouteValue — cache a separate response for each unique route segment value. This is the right choice for GET /api/orders/{id} endpoints:

csharp
1options.AddPolicy("OrderDetailPolicy", policy =>
2    policy
3        .Expire(TimeSpan.FromMinutes(2))
4        .SetVaryByRouteValue("id")
5        .Tag("orders")
6);

VaryByValue — cache a separate response for each unique computed value. This is the most flexible option, and we will cover it in depth in the Authentication section below.

Sometimes you want a policy in place, but need to disable caching for certain conditions. You can use NoStore() to skip caching entirely:

csharp
1options.AddPolicy("ConditionalOrdersPolicy", policy =>
2    policy
3        .Expire(TimeSpan.FromMinutes(5))
4        .Tag("orders")
5        .With(ctx =>
6        {
7            // Do not cache if the request includes a "no-cache" header
8            if (ctx.HttpContext.Request.Headers.CacheControl.Contains("no-cache"))
9            {
10                ctx.EnableOutputCaching = false;
11            }
12            
13            return default;
14        })
15);

Caching data that never changes is straightforward. The hard part is knowing when to remove cached data because the underlying data changed.

Output Cache supports eviction by tag, eviction by key (using VaryByValue), and clearing all entries.

Tags are labels you attach to cache entries during policy registration. When data changes, you can evict all cache entries that share a tag in a single call.

You attach tags to your policy:

csharp
1builder.Services.AddOutputCache(options =>
2{
3    options.AddPolicy("OrdersPolicy", policy =>
4        policy
5            .Expire(TimeSpan.FromMinutes(5))
6            .Tag("orders")
7    );
8
9    options.AddPolicy("OrderDetailPolicy", policy =>
10        policy
11            .Expire(TimeSpan.FromMinutes(2))
12            .SetVaryByRouteValue("id")
13            .Tag("orders")
14            .Tag("order-detail")
15    );
16});

Notice that both OrdersPolicy and OrderDetailPolicy share the "orders" tag.

When an order is created, updated, or deleted, you want to evict both the orders list and any individual order detail that may be stale.

Inject IOutputCacheStore and call EvictByTagAsync:

csharp
1public async Task<IActionResult> CreateOrder(
2    [FromBody] CreateOrderRequest request,
3    CancellationToken ct)
4{
5    var order = new Order(Guid.NewGuid(), request.CustomerName, request.TotalAmount, "Pending");
6    db.Orders.Add(order);
7    await db.SaveChangesAsync(ct);
8
9    // Evict all cache entries tagged with "orders"
10    await cache.EvictByTagAsync("orders", ct);
11
12    return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
13}
14
15// Do the same for PUT and DELETE

One EvictByTagAsync("orders", ct) call removes every stored response that was tagged with "orders". This means the list endpoint and any cached order detail pages are all cleared at once.

Sometimes you want to evict the cached response for a specific order, rather than all orders.

VaryByValue (and other Vary methods) lets you define a custom key fragment that is appended to the cache key. You provide a delegate that extracts a value from the request context, and Output Cache uses that value to distinguish cache entries.

When you want to evict only a specific order, use a tag that includes the order ID:

csharp
1builder.Services.AddOutputCache(options =>
2{
3    options.AddPolicy("OrderDetailPolicy", policy =>
4        policy
5            .Expire(TimeSpan.FromMinutes(2))
6            .SetVaryByRouteValue("id")
7            .WithVaryByTagFromRouteValue(ctx =>
8            {
9                var id = ctx.Request.RouteValues["id"]?.ToString() ?? string.Empty;
10                return [$"order-{id}"];
11            })
12    );
13});

Then, in your write endpoint, after updating a specific order, evict only that order's cache entry:

csharp
1[HttpPut("{id:guid}")]
2public async Task<IActionResult> UpdateOrder(
3    Guid id,
4    [FromBody] UpdateOrderRequest request,
5    CancellationToken ct)
6{
7    var order = await db.Orders.FindAsync([id], ct);
8    if (order is null) return NotFound();
9
10    db.Orders.Entry(order).CurrentValues.SetValues(request);
11    await db.SaveChangesAsync(ct);
12
13    // Evict only the cache entry for this specific order
14    await cache.EvictByTagAsync($"order-{id}", ct);
15
16    return NoContent();
17}

This is more efficient than evicting all orders when only one changed.

Sometimes you need a clean slate — for example, after a bulk import, a data migration, or a major configuration change.

You can evict all cache entries by creating a policy named "all" and tag every entry with it:

csharp
1builder.Services.AddOutputCache(options =>
2{
3    options.AddBasePolicy(policy => policy.Tag("all"));
4
5    options.AddPolicy("OrdersPolicy", policy =>
6        policy
7            .Expire(TimeSpan.FromMinutes(5))
8            .Tag("orders")
9    );
10
11    options.AddPolicy("OrderDetailPolicy", policy =>
12        policy
13            .Expire(TimeSpan.FromMinutes(2))
14            .SetVaryByRouteValue("id")
15            .Tag("orders")
16    );
17});

AddBasePolicy applies to all endpoints that use Output Cache, regardless of which named policy they use. So every cache entry automatically gets the "all" tag.

To clear everything:

csharp
1[HttpPost("admin/cache/clear")]
2public async Task<IActionResult> ClearAllCache(CancellationToken ct)
3{
4    await cache.EvictByTagAsync("all", ct);
5    return NoContent();
6}

A single call evicts every Output Cache entry in your application.

The default Output Cache store is in-memory, which means:

• Cache is lost when the application restarts
• Cache is not shared between multiple application instances

In production, when you have multiple instances of your API behind a load balancer, each instance has its own local cache.

A request routed to instance A may hit the cache, while the same request routed to instance B hits the database. This is inconsistent and wastes resources.

The solution is to use Redis as a shared, distributed Output Cache store.

ASP .NET Core includes a Redis Output Cache provider, installed as a separate NuGet package:

bash
1dotnet add package Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

All you need to do is configure Redis in Program.cs:

csharp
1var redisConnectionString = builder.Configuration.GetConnectionString("Redis")!;
2
3builder.Services.AddStackExchangeRedisOutputCache(options =>
4{
5    options.Configuration = redisConnectionString;
6    options.InstanceName = "OrdersApi:";
7});
8
9builder.Services.AddOutputCache(options =>
10{
11    // ...
12});

When you replace the default in-memory store with Redis, everything else stays the same.

Your [OutputCache] attributes, .CacheOutput() calls, named policies, tag-based eviction — all of it works exactly as before. The only difference is where the serialized responses are stored.

Redis adds a network round-trip to every cache lookup. For very fast endpoints (a few milliseconds), adding a Redis cache read might not significantly improve latency.

Output Cache with Redis shines when:

• Your endpoint is slow due to a complex database query (100ms or more)
• Your endpoint is under high load and database connections are a bottleneck
• You run multiple application instances and want consistent cache behavior

Caching authenticated API responses requires extra care.

If you cache the response for User A and User B later sends the same request, they could receive User A's data. That is a serious data leakage bug.

By default, Output Cache does not cache responses for authenticated requests. The Authorization header presence causes the middleware to skip caching.

But you may want to explicitly enable caching for authenticated endpoints and ensure the responses are properly scoped to each user.

Imagine a GET /api/orders/my endpoint that returns orders belonging to the currently logged-in user.

User A (userId = user-a-id) calls the endpoint. The response — User A's orders — is cached.

User B (userId = user-b-id) calls the same endpoint. They receive User A's orders from the cache.

User B should not have access to User A's data. But the cache has no idea these are two different users.

This is a real security bug!

The Solution: VaryByValue with ClaimsPrincipal

The correct fix is to use SetVaryByValue to include the current user's identity in the cache key. This ensures each user's response is stored and retrieved independently.

csharp
1builder.Services.AddOutputCache(options =>
2{
3    options.AddPolicy("UserOrdersPolicy", policy =>
4        policy
5            .Expire(TimeSpan.FromMinutes(2))
6            .Tag("orders")
7            .SetVaryByValue(ctx =>
8            {
9                // Extract the user ID from the JWT claims
10                var userId = ctx.HttpContext.User.FindFirstValue(ClaimTypes.NameIdentifier)
11                             ?? "anonymous";
12
13                return new KeyValuePair<string, string>("userId", userId);
14            })
15    );
16});

Now the cache key includes the user ID. User A's response is stored under a key that includes "userId:user-a-id". User B's response is stored under a separate key that includes "userId:user-b-id".

They never share a cache entry.

Apply the policy to your user-scoped endpoint:

csharp
1[Authorize]
2[HttpGet("my")]
3[OutputCache(PolicyName = "UserOrdersPolicy")]
4public async Task<IActionResult> GetMyOrders(CancellationToken ct)
5{
6    var userId = User.FindFirstValue(ClaimTypes.NameIdentifier)!;
7
8    var orders = await db.Orders
9        .Where(o => o.UserId == userId)
10        .ToListAsync(ct);
11
12    return Ok(orders);
13}

Output Cache is one of the most effective ways to reduce database load and improve API response times in ASP.NET Core.

Unlike IMemoryCache and IDistributedCache, Output Cache works at the HTTP middleware level and caches full serialized responses. Your handlers, services, and database queries are never called when a cached response is available.

This requires minimal changes to your existing code.

Named policies in Output Cache give you a clean, centralized place to define cache behavior — expiration, vary-by rules, and tags — without scattering options across every endpoint.

Tag-based eviction lets you invalidate groups of related cache entries in a single call. Combined with VaryByRouteValue, you can also evict the cache entry for a specific resource, like a single order.

Using AddBasePolicy with a universal "all" tag makes it easy to clear the entire Output Cache when needed.

Redis replaces the default in-memory store with a distributed, persistent cache shared across all application instances. The only code change needed is calling AddStackExchangeRedisOutputCache during service registration.

For authenticated APIs, SetVaryByValue with the user ID from ClaimsPrincipal is essential. It ensures each user's cached response is stored under a unique cache key, preventing data from one user from being served to another.

Hope you find this newsletter useful. See you next time.