MethodCache.HttpCaching
1.0.0-rc.8
See the version list below for details.
dotnet add package MethodCache.HttpCaching --version 1.0.0-rc.8
NuGet\Install-Package MethodCache.HttpCaching -Version 1.0.0-rc.8
<PackageReference Include="MethodCache.HttpCaching" Version="1.0.0-rc.8" />
<PackageVersion Include="MethodCache.HttpCaching" Version="1.0.0-rc.8" />
<PackageReference Include="MethodCache.HttpCaching" />
paket add MethodCache.HttpCaching --version 1.0.0-rc.8
#r "nuget: MethodCache.HttpCaching, 1.0.0-rc.8"
#:package MethodCache.HttpCaching@1.0.0-rc.8
#addin nuget:?package=MethodCache.HttpCaching&version=1.0.0-rc.8&prerelease
#tool nuget:?package=MethodCache.HttpCaching&version=1.0.0-rc.8&prerelease
MethodCache.HttpCaching
HTTP caching for HttpClient, the way a browser does it: responses are cached according to Cache-Control,
revalidated with ETag / Last-Modified, and a 304 Not Modified comes back to your code as the full cached
response. It follows RFC 9111.
Install it at the same version as MethodCache.
Run the console tour's HttpClient chapter to see cache hits, ETag validation, no-store
and PUT invalidation against a real local HTTP server.
builder.Services.AddMethodCache();
builder.Services.AddHttpClient<IGitHubClient, GitHubClient>()
.AddHttpCaching();
That is all. Your typed client keeps calling GetAsync as before.
What it does
| The server sends | What happens on the next request |
|---|---|
Cache-Control: max-age=60 |
Served from cache for 60 seconds, no network call |
ETag: "abc" (or Last-Modified) |
Sent with If-None-Match: "abc"; a 304 is answered from the cache |
| both | Served from cache while fresh, then revalidated with the ETag |
Vary: Accept-Language |
One cached response per language |
no-store |
Never cached |
- A successful
POST,PUT,PATCHorDELETEremoves the cached responses for that URL (and for same-originLocation/Content-Location) for every caller, language and key header value, so nobody reads stale data after a write. - Cached responses carry an
Ageheader, as the standard requires. Set-Cookieis never stored: the caller the server answered gets it, nobody served from the cache does.- Each HttpClient has its own settings and its own entries, also when caching is added to every client with
ConfigureHttpClientDefaults. - Redirects the transport follows are not stored under the URL you asked for, and a retry of the same request gets a
full response, not the cache's own 304. A
GETwith a body goes to the origin. - Request directives are honored:
no-cache(revalidates and stores the answer),no-store,max-age,max-stale,min-freshandonly-if-cached. Rangerequests go to the origin, and206 Partial Contentis never stored.- Requests that carry their own
If-None-MatchorIf-Modified-Sincego to the origin, so your304reaches you. - Statuses that are cacheable by default (
200,203,204,301,404, ...) are stored; other2xxresponses only when they say how long they stay fresh (max-ageorExpires).
Settings
Settings are per HttpClient:
builder.Services.AddHttpClient<IWeatherClient, WeatherClient>()
.AddHttpCaching(options =>
{
options.EnableStaleIfError = true; // serve the last response when the API is down
options.EnableStaleWhileRevalidate = true; // when the server sends stale-while-revalidate
options.AddDiagnosticHeaders = true; // Cache-Status: MethodCache; hit; ttl=42
});
| Option | Default | |
|---|---|---|
IsSharedCache |
false |
false: a private cache; Authorization and Cookie are part of the key so callers never see each other's responses. true: a shared cache; private and authorized responses are not stored, s-maxage applies, and a response stored for an anonymous request is served to every caller (see Security) |
DefaultMaxAge |
null |
Freshness for a response with only an ETag/Last-Modified. null revalidates every time |
AllowHeuristicFreshness |
true |
A response with only Last-Modified stays fresh for 10% of the time since then, at most MaxHeuristicFreshness |
MaxHeuristicFreshness |
1 hour | Upper limit for heuristic freshness |
StaleRetention |
24 hours | How long a stale entry is kept for revalidation and the stale options below |
EnableStaleWhileRevalidate |
false |
Serve stale at once and refresh in the background, within the server's stale-while-revalidate |
BackgroundRevalidationTimeout |
10 seconds | Limit for a stale-while-revalidate refresh |
EnableStaleIfError |
false |
Serve stale when the request fails or returns 5xx, within stale-if-error or MaxStaleIfError |
MaxStaleIfError |
24 hours | How long a response may be stale and still be served on error, when the server sends no stale-if-error |
MaxResponseBytes |
10 MiB | Larger responses are not cached. A body without Content-Length is read up to this size, then streamed to the caller uncached; dispose the response to release it. Must be positive; long.MaxValue means no limit |
KeyHeaders |
empty | Request headers that are always part of the key, for APIs that vary on a header without sending Vary |
AddDiagnosticHeaders |
false |
Adds a MethodCache member to the RFC 9211 Cache-Status header, after any the origin's caches added: MethodCache; hit; ttl=42 from the cache, or MethodCache; fwd=uri-miss; fwd-status=200; stored from the origin (fwd is uri-miss, vary-miss, stale, request, method or bypass). A stale response adds detail=stale-while-revalidate or detail=stale-if-error. Age is set either way |
KeepCookies |
false |
Keep the transport's automatic cookies and turn response caching off for this client; only-if-cached returns 504. Successful writes still invalidate |
Tags |
empty | Extra tags on this client's responses, next to its own http: tag, for invalidating several clients together |
AllowUnverifiedTransport |
false |
Cache through a transport other than SocketsHttpHandler or HttpClientHandler. Only when it sends no automatic cookies or hidden caller identity |
Only GET and HEAD responses are cached. OPTIONS and TRACE go to the origin and change nothing; any other method,
including one the cache doesn't know, invalidates the URL's cached responses when it succeeds. no-cache (from the
server or in the request) always requires a successful revalidation, even with the stale options on. If reading a response body fails, the request fails; you never get a partly read body.
See HTTP caching for the freshness and revalidation rules, how
writes invalidate, and how AddHttpCaching() handles cookies and transports.
Storage
Responses are kept in memory, in a budget of their own next to method results (your app's IMemoryCache is not
touched). The total size, headers included, is shared by all clients; a larger response is streamed and not stored:
builder.Services.AddMethodCache(cache => cache.Memory(o => o.MaxHttpBytes = 50 * 1024 * 1024)); // default 100 MB
Sharing responses between instances
With Redis, SQL Server or PostgreSQL configured in AddMethodCache, responses are stored there instead, so every
instance shares them: an ETag one instance fetched is revalidated by another, and a successful write invalidates the
URL for all of them, even when backplane messages are lost. Your application's own IDistributedCache is never used.
builder.Services.AddMethodCache(cache => cache.UseRedis("localhost:6379"));
If a write's invalidation can't be confirmed, the call throws HttpCacheInvalidationException. The write may have
succeeded at the origin, so don't repeat it automatically.
Administration
ICacheAdministrator and the admin endpoints list and remove cached responses, without bodies, credentials, cookies
or query strings. Each client's responses carry the tag http: followed by MethodCacheKeys.Part(clientName), plus
the tags in HttpCacheOptions.Tags (at most 125, each at most 1024 characters). The
HTTP caching reference has the
details.
Time
Freshness, eviction from the memory store and the background revalidation timeout all read the time from the
TimeProvider registered in the container, if there is one. Register a fake TimeProvider, for example from
Microsoft.Extensions.TimeProvider.Testing, to test expiry without waiting.
Metrics
Every request is counted on the MethodCache meter, so AddMethodCacheInstrumentation() from
MethodCache.OpenTelemetry (or AddMeter("MethodCache")) picks them up:
| Instrument | Tags |
|---|---|
methodcache.requests |
methodcache.kind=http, methodcache.http.client (the static client name), methodcache.result (hit, miss, revalidated, stale, bypass, error) |
methodcache.load.duration (s) |
methodcache.kind=http, methodcache.http.client for actual origin work, including background refresh |
methodcache.http.size (By) |
Bytes the cached responses take in memory |
Invalid settings fail when the host starts: MaxResponseBytes must be positive (long.MaxValue for no limit),
durations can't be negative, and BackgroundRevalidationTimeout must be positive and at most about 49 days.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- MethodCache (= 1.0.0-rc.8)
- Microsoft.Extensions.Http (>= 9.0.9)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.9)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.0-rc.20 | 51 | 11/12/2026 |
| 1.0.0-rc.19 | 56 | 11/10/2026 |
| 1.0.0-rc.18 | 57 | 11/10/2026 |
| 1.0.0-rc.17 | 53 | 11/10/2026 |
| 1.0.0-rc.16 | 52 | 11/8/2026 |
| 1.0.0-rc.15 | 51 | 11/8/2026 |
| 1.0.0-rc.14 | 55 | 11/8/2026 |
| 1.0.0-rc.13 | 56 | 11/7/2026 |
| 1.0.0-rc.12 | 55 | 11/7/2026 |
| 1.0.0-rc.11 | 53 | 11/7/2026 |
| 1.0.0-rc.10 | 53 | 11/6/2026 |
| 1.0.0-rc.9 | 55 | 11/5/2026 |
| 1.0.0-rc.8 | 64 | 11/5/2026 |
| 1.0.0-rc.7 | 58 | 11/5/2026 |
| 1.0.0-rc.6 | 58 | 11/5/2026 |
| 1.0.0-rc.5 | 61 | 11/4/2026 |
| 1.0.0-rc.4 | 55 | 11/4/2026 |
| 1.0.0-rc.3 | 56 | 11/4/2026 |
| 1.0.0-rc.2 | 72 | 10/20/2026 |
| 1.0.0-rc.1 | 69 | 10/19/2026 |