Skip to content

🌐 HTTP Response Caching¢

CoreSystem.Cache provides declarative HTTP response caching for ASP.NET Core applications.

Instead of implementing cache management logic inside controllers or Minimal APIs, the framework handles cache lookup, storage, expiration, and invalidation through middleware.


πŸ“‹ OverviewΒΆ

When an endpoint is associated with the Cacheable attribute, the framework automatically:

  • Generates a cache key
  • Checks whether a cached response already exists
  • Returns cached responses immediately
  • Executes the endpoint on cache misses
  • Captures the response
  • Stores cacheable responses using the configured cache provider
  • Applies expiration policies
  • Supports tag-based invalidation

No additional cache-management code is required inside your endpoints.


πŸ—οΈ ArchitectureΒΆ

flowchart TD Client["HTTP Client"] Client --> Middleware["Cache Middleware"] Middleware --> Handler["HttpCacheHandler"] Handler --> Lookup["Lookup Cache"] Lookup --> Hit{"Cache Hit?"} Hit -->|Yes| Response["Return Cached Response"] Hit -->|No| Endpoint["Execute Endpoint"] Endpoint --> Capture["Capture Response"] Capture --> Store["Store Response"] Store --> Response Response --> Client

πŸ”Œ Enable the MiddlewareΒΆ

Register the middleware.

var app = builder.Build();

app.UseCoreCache();

app.Run();

πŸ’‘ Basic UsageΒΆ

Decorate an endpoint.

[HttpGet("{id}")]
[Cacheable(expirationSeconds:300)]
public async Task<IActionResult> Get(Guid id)
{
    return Ok(await service.GetAsync(id));
}

The response will be cached for five minutes when it satisfies the default request and response cache policies.


🧩 Minimal API Example¢

app.MapGet("/products/{id}",
    async (Guid id, IProductService service) =>
    {
        return Results.Ok(await service.GetAsync(id));
    })
.WithMetadata(new CacheableAttribute(300));

⏳ Cache Expiration¢

Specify the cache lifetime.

[Cacheable(expirationSeconds:600)]

or

[Cacheable(expirationSeconds:60)]

When no expiration is specified, the cache uses CacheOptions.DefaultExpiration.


🏷️ Using Cache Tags¢

Tags allow multiple cached responses to be invalidated together.

[Cacheable(
    expirationSeconds:300,
    tag:"Products")]

Later:

await cache.InvalidateByTagAsync("Products");

πŸ”‘ Cache Key GenerationΒΆ

HTTP cache keys are generated automatically using:

  • Request path
  • Query string

Query parameters are ordered by name before the key is generated.

Example:

/products/15?page=2

This allows different paths and query-string combinations to be cached independently.


βœ… Cache HitΒΆ

Request
      β”‚
      β–Ό
Cached Response Exists?
      β”‚
     Yes
      β”‚
      β–Ό
Return Cached Response

No endpoint execution occurs.


❌ Cache Miss¢

Request
      β”‚
      β–Ό
Cache Miss
      β”‚
      β–Ό
Execute Endpoint
      β”‚
      β–Ό
Capture Response
      β”‚
      β–Ό
Store Response
      β”‚
      β–Ό
Return Response

Responses are stored only when the default response policy allows caching.


πŸ”Œ Provider IndependenceΒΆ

HTTP response caching uses the ICoreCache abstraction, so it is independent of the concrete storage implementation.

The supplied implementation includes:

  • Memory
  • External cache storage such as Redis

Changing the configured cache storage does not require changes to controllers.


πŸ”§ Pipeline IntegrationΒΆ

HTTP response cache operations use the cache pipeline through ICoreCache.

When the corresponding behaviors are registered, the pipeline order is:

Logging

↓

Metrics

↓

Fallback

↓

Resilience

↓

Storage

Fallback is included when an external primary storage with a memory fallback is configured, while Resilience is included when the Redis provider registers a Redis resilience pipeline.

HTTP response caching therefore participates in the cache pipeline's configured:

  • Logging
  • Metrics
  • Fallback
  • Resilience

βœ… Best PracticesΒΆ

βœ… Cache GET and HEAD endpoints only.

βœ… Avoid caching endpoints with user-specific responses.

βœ… Use cache tags for related resources.

βœ… Choose expiration based on data volatility.


⚠️ Limitations¢

The default request policy does not cache:

  • Methods other than GET and HEAD
  • Requests containing an Authorization header

The default response policy does not cache:

  • Responses other than HTTP 200
  • Responses containing Set-Cookie
  • Responses marked private
  • Responses marked no-store