Options

edit

HttpCachingOptions configures a HttpCachingDelegateHandler. Pass it as the last argument of the constructor:

var options = new HttpCachingOptions
{
    // Do not store the responses larger than 1 MB. The default is 5 MB, and null removes the limit.
    MaximumResponseSize = 1024 * 1024,

    // Only store the successful responses, even when the server allows storing the others
    ShouldCacheResponse = response => response.IsSuccessStatusCode,
};
OptionDefaultWhat it does
MaximumResponseSize5 MB (5,242,880 bytes)The largest response stored, in bytes. null removes the limit
ShouldCacheResponsenullA predicate that can prevent storing a response
IsSharedCachefalseFollow the rules of a shared cache, which serves several users
CoalesceRequestsfalseSend a single request to the server for concurrent requests for the same URL
TimeProviderTimeProvider.SystemThe clock used to compute the age and the freshness of the responses
OnStoreErrornullA callback invoked when the store fails

Limit the size of the stored responses

The cache reads the body of a response to store it, so a large response costs memory and space in the store. MaximumResponseSize bounds that:

  • A response whose Content-Length is larger than the limit is not read by the cache at all.
  • A response without Content-Length is read up to the limit, then left unstored.
  • The limit applies to the stored entry, which holds the headers and an encoded copy of the body: a body slightly smaller than the limit can still be too large.

In every case, the caller receives the full response. Only the storage is skipped.

This limit applies to each response. To bound the number of entries or their total size, give limits to the store. See Bounding the size of a store.

Choose which responses to store

ShouldCacheResponse is called for each response the HTTP caching rules allow to store. When it returns false, the response is not stored. It cannot make the cache store a response that the rules do not allow, such as one with Cache-Control: no-store.

Share the cache between users

By default, the cache is private: it belongs to a single user. Set IsSharedCache when one cache serves several users, for instance in a proxy or in a service that forwards the requests of its own clients:

var options = new HttpCachingOptions
{
    // Follow the rules of a shared cache: the cache serves several users
    IsSharedCache = true,
};

A shared cache follows the rules of RFC 9111 for shared caches:

  • A response with Cache-Control: private is not stored. With private="<field>", the response is stored without the listed header fields.
  • The response to a request with an Authorization header is only stored when the response has public, s-maxage or must-revalidate.
  • s-maxage gives the freshness lifetime, before max-age and Expires, and makes the response storable on its own.
  • proxy-revalidate and s-maxage mean the same as must-revalidate: a stale response is never served without a successful revalidation, even for max-stale or stale-if-error.

The stores keep an entry until it is stale for both kinds of cache, so they do not need to know which one wrote it.

Coalesce concurrent requests

When a popular response expires, every concurrent request for it goes to the server, multiplying the load on the server when the cache should protect it. Set CoalesceRequests to send a single request instead:

var options = new HttpCachingOptions
{
    // Concurrent requests for the same URL share a single request to the server
    CoalesceRequests = true,
};

using var cachingHandler = new HttpCachingDelegateHandler(new SocketsHttpHandler(), new InMemoryHttpCacheStore(), options);
using var httpClient = new HttpClient(cachingHandler);

// Only one of these requests goes to the server. The others wait for it, then are served from the cache.
var responses = await Task.WhenAll(Enumerable.Range(0, 10).Select(_ => httpClient.GetStringAsync("https://example.com/data")));
  • When a request must go to the server (nothing stored, or a stale response to revalidate), the concurrent requests with the same method and URL wait for it, then look up the cache again. A stale response is revalidated once, with a single conditional request.
  • A waiting request that the stored response cannot answer, because the response could not be stored or varies on a header the request sends differently, goes to the server itself. It does not wait a second time, so requests whose responses are never stored are not queued behind each other.
  • Fresh responses are served from the cache without waiting, and requests with a Range header are not coalesced.
  • Coalescing happens within one HttpCachingDelegateHandler. Handlers that share a store, in other processes or with IHttpClientFactory, which creates a handler per HttpClient lifetime, still send their own requests.

Control the clock

The cache computes the age and the freshness of the responses with TimeProvider. Replace it with a FakeTimeProvider to test how your application behaves when responses become stale, without waiting:

// FakeTimeProvider comes from the Microsoft.Extensions.TimeProvider.Testing package
var timeProvider = new FakeTimeProvider();
var options = new HttpCachingOptions
{
    TimeProvider = timeProvider,
};

using var cachingHandler = new HttpCachingDelegateHandler(originHandler, new InMemoryHttpCacheStore(), options);
using var httpClient = new HttpClient(cachingHandler);

// The server answers with Cache-Control: max-age=300
Assert.Equal("v1", await httpClient.GetStringAsync("https://example.com/data"));

// Five minutes later, the stored response is stale, so the cache asks the server again
timeProvider.Advance(TimeSpan.FromMinutes(5));
Assert.Equal("v2", await httpClient.GetStringAsync("https://example.com/data"));

PruneObsoleteEntriesAsync does not use this clock: pass the time to the overload that takes one, PruneObsoleteEntriesAsync(timeProvider.GetUtcNow()). See Cache stores.

Observe store failures

A failing IHttpCacheStore never fails the request. A lookup that throws is treated as a cache miss, and a write that throws is skipped, so a Redis outage or a locked SQLite file degrades to no caching rather than to a broken HttpClient. Set OnStoreError to log these failures:

var options = new HttpCachingOptions
{
    OnStoreError = ex => logger.LogWarning(ex, "HTTP cache store failure"),
};

Without it, the failures are silent. A cancellation requested by the caller is not a store failure: it still cancels the request.