Mastering Output Caching & HybridCache in ASP.NET Core

In modern web applications, performance is paramount. Users expect pages to load in milliseconds, and servers must handle thousands of concurrent requests without breaking a sweat. One of the most effective ways to achieve this is through caching. ASP.NET Core offers powerful caching mechanisms, and with the release of .NET 8, a new player entered the scene: HybridCache. This article dives deep into output caching and HybridCache, showing you how to implement them in production-ready applications. You'll learn the differences between traditional output caching and the new HybridCache, when to use each, and how to avoid common pitfalls. We'll explore real-world scenarios, such as caching a dashboard that displays frequently updated data, and walk through debugging techniques for when things go wrong. By the end, you'll be equipped to boost your app's performance significantly while maintaining data freshness.

What is Output Caching?

Output caching is a technique that stores the entire HTTP response generated by an endpoint (controller action, Razor Page, or Minimal API) and serves it for subsequent identical requests. This avoids re-executing the server-side logic, reducing CPU load and improving response times. In ASP.NET Core, output caching is implemented via middleware and attributes. It supports vary-by rules (e.g., by query string, header, or user) to cache different versions of the same endpoint. The cache can be stored in-memory or in a distributed cache like Redis. Output caching is ideal for endpoints that produce the same response for many users, such as a list of products or a static homepage.

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.DefaultExpirationTimeSpan = TimeSpan.FromMinutes(10);
    options.AddPolicy("VaryByQuery", policy =>
    {
        policy.VaryByQuery("category");
    });
});

var app = builder.Build();
app.UseOutputCache();

app.MapGet("/products", () =>
{
    return Results.Ok(new[] { "Product1", "Product2" });
}).CacheOutput(policy => policy.Expire(TimeSpan.FromMinutes(5)));

app.Run();

Introducing HybridCache

HybridCache is a new caching abstraction introduced in .NET 8 that combines an in-memory cache (L1) with a distributed cache (L2) like Redis. It provides a unified API for caching data, automatically managing the two tiers. The in-memory cache offers low latency, while the distributed cache provides durability and scalability across multiple servers. HybridCache supports cache tags, which allow you to invalidate groups of cache entries together. It also handles serialization and deserialization of cached objects. This is particularly useful for caching complex objects like database query results or computed data. HybridCache is not a replacement for output caching; rather, it's a lower-level caching mechanism that you can use in your services and middleware.

// Install-Package Microsoft.Extensions.Caching.Hybrid
// Program.cs
using Microsoft.Extensions.Caching.Hybrid;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),
        LocalCacheExpiration = TimeSpan.FromMinutes(1)
    };
});
// Add distributed cache (e.g., Redis)
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = "localhost:6379";
});

var app = builder.Build();

app.MapGet("/data", async (HybridCache cache) =>
{
    var data = await cache.GetOrCreateAsync("mykey", async cancel =>
    {
        // Simulate expensive operation
        await Task.Delay(1000, cancel);
        return new { Timestamp = DateTime.UtcNow, Value = 42 };
    });
    return Results.Ok(data);
});

app.Run();

Configuring Output Caching Policies

Output caching policies define how responses are cached and vary. You can create named policies in the AddOutputCache call and apply them to endpoints using the [OutputCache] attribute or the CacheOutput extension method. Policies can specify expiration, vary-by rules (query, header, route, user), and whether to cache authenticated responses. For example, you might want to cache a product listing but vary by the 'category' query parameter. You can also lock cache entries to prevent multiple requests from triggering the same expensive operation simultaneously (cache stampede protection).

// Program.cs
builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("ProductPolicy", policy =>
    {
        policy.Expire(TimeSpan.FromMinutes(5));
        policy.VaryByQuery("category");
        policy.VaryByHeader("Accept-Language");
        policy.Tag("products");
    });
});

// Controller
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [OutputCache(PolicyName = "ProductPolicy")]
    public IActionResult GetProducts([FromQuery] string category)
    {
        // Simulate database call
        return Ok(new[] { $"Product in {category}" });
    }
}

Cache Invalidation Strategies

Cache invalidation is the process of removing or updating cached data when the underlying source changes. Without proper invalidation, users see stale data. In ASP.NET Core output caching, you can invalidate entries by tag using the IOutputCacheStore interface. For HybridCache, you can use the RemoveByTagAsync method. Common strategies include: time-based expiration (TTL), event-driven invalidation (e.g., when a product is updated, invalidate its cache), and dependency-based invalidation (e.g., cache depends on a database row version). For output caching, you can also use the [InvalidateOutputCache] attribute to invalidate caches when a write operation occurs.

// Invalidation using IOutputCacheStore
public class ProductService
{
    private readonly IOutputCacheStore _cacheStore;
    public ProductService(IOutputCacheStore cacheStore)
    {
        _cacheStore = cacheStore;
    }

    public async Task UpdateProduct(int id)
    {
        // Update database
        await _cacheStore.EvictByTagAsync("products", CancellationToken.None);
    }
}

// HybridCache invalidation
public class OrderService
{
    private readonly HybridCache _cache;
    public OrderService(HybridCache cache)
    {
        _cache = cache;
    }

    public async Task PlaceOrder()
    {
        // Process order
        await _cache.RemoveByTagAsync("orders");
    }
}

HybridCache with Redis in Production

In production, HybridCache typically uses Redis as the distributed cache backend. Redis provides high availability and persistence. To configure HybridCache with Redis, you need to add the Microsoft.Extensions.Caching.StackExchangeRedis package and register the Redis cache service. HybridCache automatically uses it as the L2 cache. You can also configure serialization (e.g., JSON or protobuf) for cached objects. It's important to set appropriate timeouts and connection limits to avoid bottlenecks. Additionally, consider using Redis Cluster for large-scale deployments.

// Program.cs
using Microsoft.Extensions.Caching.Hybrid;
using Microsoft.Extensions.Caching.StackExchangeRedis;

var builder = WebApplication.CreateBuilder(args);

// Add Redis distributed cache
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
    options.InstanceName = "MyApp";
});

// Add HybridCache
builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(10),
        LocalCacheExpiration = TimeSpan.FromMinutes(2)
    };
});

var app = builder.Build();

app.MapGet("/user/{id}", async (int id, HybridCache cache) =>
{
    var user = await cache.GetOrCreateAsync($"user-{id}", async cancel =>
    {
        // Fetch from database
        await Task.Delay(500, cancel);
        return new { Id = id, Name = "John Doe" };
    });
    return Results.Ok(user);
});

app.Run();

Security Considerations for Caching

Caching can introduce security vulnerabilities if not handled carefully. Never cache responses that contain sensitive user data (e.g., personal information, authentication tokens). Use vary-by-user or disable caching for authenticated endpoints. Be cautious with caching responses that depend on user roles or permissions. Additionally, ensure that cache keys are not predictable to prevent cache poisoning attacks. For output caching, use the [OutputCache(NoStore = true)] attribute on actions that should never be cached. For HybridCache, avoid caching sensitive data altogether, or encrypt the cached values.

// Disable caching for authenticated endpoints
[Authorize]
[OutputCache(NoStore = true)]
public IActionResult MyProfile()
{
    return Ok(new { User = User.Identity.Name });
}

// HybridCache with encryption (conceptual)
// Use a custom serializer that encrypts data before caching
public class EncryptedCacheSerializer : IHybridCacheSerializer<MyData>
{
    public MyData Deserialize(ReadOnlySpan<byte> source)
    {
        var decrypted = Decrypt(source);
        return JsonSerializer.Deserialize<MyData>(decrypted);
    }

    public void Serialize(MyData value, IBufferWriter<byte> target)
    {
        var json = JsonSerializer.SerializeToUtf8Bytes(value);
        var encrypted = Encrypt(json);
        target.Write(encrypted);
    }
}

Performance Monitoring and Optimization

To ensure your caching strategy is effective, monitor cache hit ratios, memory usage, and latency. ASP.NET Core provides metrics for output caching via the Microsoft.AspNetCore.OutputCaching counters. For HybridCache, you can use the IDistributedCache metrics. Use Application Insights or Prometheus to collect and visualize these metrics. Optimize by adjusting cache sizes, expiration times, and eviction policies. For in-memory cache, set a size limit to prevent memory exhaustion. For distributed cache, ensure network latency is low. Also, consider using cache warming to pre-populate caches after a deployment.

// Enable metrics in Program.cs
builder.Services.AddOutputCache(options =>
{
    options.EnableMetrics = true;
});

// Access metrics via IMetricsCollector
public class CacheMetricsMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IMetricsCollector _metrics;

    public CacheMetricsMiddleware(RequestDelegate next, IMetricsCollector metrics)
    {
        _next = next;
        _metrics = metrics;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Custom metric collection
        await _next(context);
    }
}