# MethodCache documentation All user documentation in one file, generated from the repository. Source: https://github.com/eoniclabs/MethodCache/blob/main/docs/README.md --- # MethodCache: instructions for coding agents Copy this file into your project as agent instructions, for example as `.github/copilot-instructions.md`, a Cursor rule, a Claude Code skill or a section of `AGENTS.md`. It tells a coding agent how to add caching with MethodCache correctly. Full docs: https://github.com/eoniclabs/MethodCache/blob/main/docs/README.md. The `MethodCache` package carries the same docs in its `docs` folder (`~/.nuget/packages/methodcache//docs/`): `how-to.md` answers common questions, `reference/` has the exact rules and `CHANGELOG.md` says what changed in each version and what to do when upgrading. Read the page for the task at hand, listed under [Guides](#guides); `llms-full.txt` holds every page in one file, which is too large to read whole, so search it instead. ## Adding caching to a service 1. The `MethodCache` package contains the library, the source generator and the analyzers. Nothing else is needed for in-memory caching. All packages target .NET 10; install add-ons at the same version as `MethodCache`. 2. Put `[Cache]` on the **interface** method, never on the class. Put `[CacheInvalidate(Tags = [...])]` on the interface methods that change the data. Don't change the implementation. 3. Register services as usual, then call `builder.Services.AddMethodCache()` **after** them. Later cacheable registrations fail at host startup. A cached interface without a registration needs `AutoRegister(lifetime)` and exactly one class that implements it. 4. Use `MethodCacheBuilder` for startup, in one `AddMethodCache(mc => mc...)` call: `Defaults`, `Group`, typed `Method`, `Memory`, `Distributed`, `Telemetry`, `FromConfiguration`, `FromAssemblyOf()` and the integrations' `UseRedis` / `UseSqlServer` / `UsePostgreSql` (one of them) / `UseMessagePack`. Don't use `services.Configure<...>` for MethodCache options. ```cs using MethodCache; public interface IProductService { [Cache(Duration = "10m", Tags = ["products", "product:{id}"])] Task GetAsync(int id, CancellationToken ct = default); [Cache(Duration = "1m", Tags = ["products"])] Task> SearchAsync(string text, int page); [CacheInvalidate(Tags = ["products", "product:{id}"])] Task UpdateAsync(int id, Product product); } public sealed class ProductService(Database db) : IProductService { public Task GetAsync(int id, CancellationToken ct = default) => db.LoadProductAsync(id, ct); public Task> SearchAsync(string text, int page) => db.SearchAsync(text, page); public Task UpdateAsync(int id, Product product) => db.SaveAsync(product); } ``` ```cs builder.Services.AddSingleton(); builder.Services.AddScoped(); // any lifetime builder.Services.AddMethodCache(); // after your registrations ``` ## Rules - Only interface methods that return a value can be cached: sync, `Task` or `ValueTask`. Return a list, never a lazy `IEnumerable` or `IQueryable`. - Callers must use the interface. Calling the method from inside the class (MC0031), creating the class with `new` (MC0032), or resolving the class itself, bypasses the cache. Several instances of one class are keyed registrations. A program with cached services must call `AddMethodCache()`, itself or through a setup method of a referenced project (MC0030). - Keys are generated from the method and its arguments; don't write keys for `[Cache]` methods. A `CancellationToken` is not part of the key. Every value that changes the result must be a parameter. Sets and dictionaries are written sorted; lists and arrays keep their order, so pass ids whose order doesn't matter as a set. - Tags take templates with a **parameter name** only: `"product:{id}"`. `"{product.Id}"` is not a template, stays literal and gives warning MC0016; add an `id` parameter instead. Use the same tags on the cached method and on its `[CacheInvalidate]`. - Tag values are formatted like `MethodCacheKeys.Part`: `:` and `\` in strings are escaped, a `Guid` is written without hyphens, an enum as its number, `bool` as `true`/`false`, numbers and dates in the invariant culture. Build a tag by hand only with `MethodCacheKeys.Tag($"price:{provider}:{model}")` or `IMethodCacheKeys.Tag`, never plain interpolation (MC0024). Prefer ids (`int`, `Guid`) and never pass passwords or tokens as arguments of cached methods. - `[CacheInvalidate]` runs after the method, or its task, succeeds; never when it throws. - Synchronous `[Cache]` methods use the memory cache only, also with Redis, SQL Server or PostgreSQL. Make a method async to share its results between instances. - Durations are a number and a unit: `"30s"`, `"10m"`, `"1.5h"`, `"7d"`. A `TimeSpan` such as `"00:10:00"` is an error (MC0004). Other settings: `SlidingExpiration` (or `"off"`), `RefreshAhead` (shorter than `Duration` and `SlidingExpiration`, or `"off"`; MC0023 otherwise), `FailSafe` (or `"off"`), `FailSafeTimeout`, `FailSafeRetryAfter`, `Version`, `Tags`, `Enabled`, `Distributed` and the named `Group` setting. In code each has one builder method with the same name: `WithFailSafe(d)`, `WithFailSafeTimeout(t)`, `WithFailSafeRetryAfter(t)` and so on. - Cached objects are shared between callers: return immutable types such as records. Never cache `JsonNode`, `JsonObject`, `DataTable` or a `Stream` (MC0025); return a record, a string or a `JsonElement`. - The key holds only the method's arguments. A cached implementation must not read the current user or request (`IHttpContextAccessor`, `ClaimsPrincipal`, row-level security on the connection; MC0026), directly or through a `DbContext` set up for the signed-in user: pass the user or tenant id as an argument instead. With row-level security, give cached reads a context of their own from `IDbContextFactory` that sets what the policies read from the method's arguments, and check in the endpoint that the user may read it. - Invalidate after a transaction commits, with `CancellationToken.None`, never before or inside it. - Every tag on a `[Cache]` method needs an invalidation that names it; MC0028 reports one that nothing in the project invalidates. When another application invalidates it, such as a worker, list it in `[Cache(Tags = [...], InvalidatedElsewhere = ["tag"])]` instead of suppressing the warning; when only an operator clears it by hand, such as through `MapMethodCacheAdmin`, list it in `InvalidatedManually = ["tag"]`. - Keep `SlidingExpiration` shorter than `Duration`: an entry never lives past its `Duration`, so a longer window never extends anything (warning MC0038 on `[Cache]`, and a warning when the host starts for settings combined from `Defaults`, code or `appsettings.json`). - For a type with only private state used as an argument or inside one (a property, a list element), implement `ICacheKeyProvider`. - For library modules and Native AOT, select the containing assembly with `MethodCacheBuilder.FromAssemblyOf()`. If multiple modules generate the same interface, the selected one wins; the other modules' services stay cached, and calling/entry assemblies have no special priority. - In `appsettings.json`, the `MethodCache` section holds `Defaults`, `FailSafe`, `Groups` (by group name) and `Methods` (by method id, such as `[MyApp]MyApp.IProductService.GetAsync`; not `Services`). Write durations as a number and a unit, `"5m"` (a bare number is rejected), `Tags` as a list, and only known setting names. Anything else, an empty value, an unknown method id and a method listed twice fail startup. There is no `Notes` or `Metadata` setting: write notes as a `//` comment next to the entry. - `WithName` belongs on one method or manual call; in `Defaults`, a group or `mc.Method(...).Configure(...)` it fails startup. `ClearTags` in `Defaults` fails startup too; a group may clear the tags its methods get from `Defaults`. - To change caching while the app runs, use `IRuntimeCacheConfigurator`: `UpsertAsync(methodId, ...)` for one method, `UpsertGroupAsync("pricing", ...)` for every method in a group, `UpsertAllAsync(...)` for every cached method, and `RemoveAsync`, `RemoveGroupAsync` or `ClearAsync` to undo. An override that sets nothing, uses `WithName`, has an `ExpiresAt` already passed, refreshes as soon as it is stored or doesn't fit one method of the group throws `ArgumentException` and changes no method. Group names are case-sensitive. To switch all caching off during an incident: `UpsertAllAsync(o => o.WithEnabled(false), new RuntimeOverrideMetadata { Reason = "...", ExpiresAt = ... })`, and `ClearAsync()` to switch it on again. - Over HTTP, `MapMethodCacheAdmin` adds `GET`, `PUT` and `DELETE` on `/overrides`; the `PUT` body is a JSON object with the same settings as a `Methods` entry in `appsettings.json` plus one of `MethodId`, `Group` or `"All": true`. Its `audit` function gets a `MethodCacheAdminAction` with `User`, `Kind`, `Targets`, `Time` and, for an override, `OverrideMetadata`; tests build one with `new MethodCacheAdminAction(kind, targets, httpContext, time)`. - `CacheWhen` is set for one method in code (`mc.Method(...).CacheWhen(...)`); in `Defaults` or a group it fails startup, and so does a `CacheWhen` for a type the method can't return. The same goes for `DurationFor`, which gives each result its own duration (zero or less doesn't cache it), `SlidingFor`, which gives each result its own sliding window (zero turns sliding off for it), and `TagsFor`, which adds tags read from the result, such as `TagsFor(order => [MethodCacheKeys.Tag($"customer:{order.CustomerId}")])`. - A `Duration` may be at most `MethodCacheMemoryOptions.MaxExpiration` (7 days by default, at most 365); a longer one fails startup. Raise it with `mc.Memory(o => o.MaxExpiration = ...)`. - For a client from a NuGet package with an interface, use `[assembly: CacheInterface(typeof(IClient), nameof(IClient.Method), Duration = "...")]` instead of a wrapper. - Without an attribute, use `ICacheManager.GetOrCreateAsync(key, factory, o => o.WithDuration(...))` with an explicit, prefixed key such as `$"order:{id}"`. - Fix MethodCache's `MC` build diagnostics; each links to its explanation, and many have a code fix. - In tests, register `NoOpCacheManager` (namespace `MethodCache`) after `AddMethodCache()` to turn method caching off. When a test writes to the database directly, call `ICacheAdministrator.ClearAsync()` after the write. - To test the caching itself, use the `MethodCache.Testing` package: `services.AddMethodCacheTesting()` registers a `FakeTimeProvider` and a `CacheRecorder`. `recorder.Loads(s => s.GetAsync(42))` counts the runs of that call (prove a read is cached with it, not with a write that invalidates), `recorder.InvalidatedTags` lists what was invalidated, and `Assert.Empty(TagCoverage.Uninvalidated(provider))` checks that every tag has an invalidation. It counts `[CacheInvalidate]`, the EF Core mapping and the invalidations in the projects the test project references; a tag marked `InvalidatedElsewhere` counts only when one of them invalidates it, and one marked `InvalidatedManually` always counts. Pass tags invalidated outside the solution in `alsoInvalidatedBy`. `Assert.Empty(await CachedServices.ProblemsAsync(provider))` checks that every service with cached methods resolves to its caching decorator; `CachedServices.RegistrationProblems(provider)` checks the registrations only, without resolving. Both, and `TagCoverage.Uninvalidated`, throw when the provider has no cached service. `CachedServices.Registered(provider)` lists the registered cached services, to compare with the expected list and catch one that is never registered; `CachedServices.Declared(typeof(IOrders).Assembly)` gives that list from the project's own interfaces. `Assert.Empty(CachedServices.Warnings(provider))` fails on the warnings the host logs at startup, such as a `RefreshAhead` not shorter than the `Duration` from another layer or a group with settings but no cached method. - `Defaults` and groups apply to cached methods only. A `GetOrCreateAsync` call has only its own options: without `WithDuration` it lives five minutes. - Use one version of every MethodCache package; NuGet warns with NU1608 when they differ. - To invalidate a `GetOrCreateAsync` entry that has a version, pass the key and the version: `InvalidateKeyAsync(key, 2)`. Never pass a stored key (`MethodCacheKeys.StoredKey`) to `ICacheManager`. - To invalidate one call of a `[Cache]` method, get its key from `IMethodCacheKeys`: `cache.InvalidateKeyAsync(keys.For(s => s.GetAsync(42)))`. For every entry of one method, use `ICacheAdministrator.InvalidateMethodAsync(keys.MethodId(s => s.GetAsync(0)))`. - When data changes outside the cached interface (an endpoint or command writing to the database, or after a transaction commits), invalidate after the write with a tag from `IMethodCacheKeys.Tag`: `cache.InvalidateTagAsync(keys.Tag(s => s.GetRateAsync(provider, model), IPriceSource.RateTag))`. Never build a tag with string interpolation (`$"price:{model}"`): tags escape `:` and `\` in strings and write a `Guid` without hyphens and an enum as its number, so a hand-built tag can silently match nothing (MC0024). - With Entity Framework Core, add package `MethodCache.EntityFrameworkCore` and map each entity type to the tags of the cached methods that read it: `mc.UseEntityFrameworkCore(ef => ef.Entity("product:{Id}", "products"))`. A name in braces is an entity property. `SaveChanges` then invalidates them after the commit, and a rollback drops them, also for rows updated or deleted without loading them, `OwnsOne`/`OwnsMany` types and many-to-many links; don't add invalidation code to those writes. For rows the database deletes by cascade or trigger when a row is deleted, map the parent with `ef.Entity(user => user.WhenDeleted("posts"))`: those tags are invalidated only on delete, so a parent saved often doesn't clear them. For `ExecuteUpdate`, `ExecuteDelete` and `ExecuteSql…` (MC0027, on mapped types only, also in a project that references the mapping project such as its tests, and on raw SQL that names a mapped table, runs a procedure or can't be read), call `db.InvalidateAfterCommit(tag)` inside the transaction, or `cache.InvalidateTagAsync(tag)` after a write without one. Mark the app's own invalidation helpers `[InvalidatesCache]` so MC0027 counts a call to them. - Several registrations of one interface with different implementation types each cache their own results. - For a distributed cache use `UseRedis`, `UseSqlServer` or `UsePostgreSql`; MethodCache never uses the app's `IDistributedCache`. When processes should keep their own values and share only invalidations (a worker that changes data an API caches, or several API instances), add `.Distributed(o => o.StoreValuesByDefault = false)` in every process (not `Defaults(o => o.WithDistributed(false))`, which manual calls ignore): values stay in memory unless a method or call sets `Distributed = true`/`WithDistributed(true)`, and invalidations reach all of them (PostgreSQL `LISTEN`/`NOTIFY`, Redis pub/sub, SQL Server polling). Values are JSON; use `UseJson(context)` for Native AOT and `UseJson(options)` for your own settings. A result type that doesn't read back unchanged (private setters, `object`) stays in memory, with a warning: return records with public properties. A `Dog` in a `List` comes back as a `Dog` (the generator registers derived types; under Native AOT add them to the context, MC0040). Never change a cached result in place (MC0043): the memory cache hands the same instance to later callers, so change a copy. A renamed property or enum member needs no `Version` bump: entries are kept apart by the result's shape. - `AddHttpCaching()` needs `AddMethodCache()` in the same container, in either order. It turns off automatic cookies; send cookies as a `Cookie` header, or set `KeepCookies = true`, which turns response caching off. - Generated keys and method ids start with the service assembly's name in brackets. Never write a key or method id by hand: get keys from `IMethodCacheKeys.For`, tags from `IMethodCacheKeys.Tag` and ids from `IMethodCacheKeys.MethodId`. - Telemetry: `MethodCacheTelemetryOptions` (`mc.Telemetry(...)`) records keys and tags on spans only when you turn it on, hashed by default. `AddMethodCacheInstrumentation()` (package `MethodCache.OpenTelemetry`) subscribes OpenTelemetry to the `MethodCache` meter and activity source. ## Guides Each guide is in the package's `docs/features/` folder and at https://github.com/eoniclabs/MethodCache/tree/main/docs/features. Read the one for the task before writing code: - `expiration.md`: durations, sliding expiration, refresh-ahead. - `invalidation.md`: tags, `[CacheInvalidate]`, invalidating from code, after a transaction, with several instances. - `entity-framework-core.md`: entity tags after `SaveChanges`, writes past the change tracker, row-level security. - `keys.md`: how arguments become keys, `ICacheKeyProvider`. - `configuration.md`: `appsettings.json`, groups, startup code, runtime changes. - `distributed-cache.md`: Redis, SQL Server and PostgreSQL, sharing only invalidations, serialization. - `memory-cache.md`: size limits, eviction, shared cached objects. - `fail-safe.md`: serving the last good value when the method fails. - `conditional-caching.md`: results that are returned but not cached. - `manual-caching.md`: `ICacheManager.GetOrCreateAsync` with your own keys. - `third-party.md`: caching clients you don't own, `[assembly: CacheInterface]`. - `http-caching.md`: caching `HttpClient` responses. - `monitoring.md`: metrics, activities, the admin endpoints. - `testing.md`: tests with and without caching, `MethodCache.Testing` (recorder, fake clock, `CachedServices`, `TagCoverage`), time. - `native-aot.md`: trimming and Native AOT. - `source-generator.md`: what the generated decorator does. ## Namespaces - `MethodCache`: `[Cache]`, `[CacheInvalidate]`, `[CacheInterface]`, `ICacheManager`, `ICacheAdministrator`, `IRuntimeCacheConfigurator`, `IMethodCacheKeys`, `MethodCacheKeys`, `MethodCacheMemoryOptions`, `Any`, `ICacheKeyProvider`. - `MethodCache`: also `NoOpCacheManager` (sealed). - `Microsoft.Extensions.DependencyInjection`: `AddMethodCache`. Everything else is a method on its builder: `FromConfiguration`, `Distributed(...)`, `Telemetry(...)`, `UseRedis` (package `MethodCache.Redis`), `UseSqlServer` (package `MethodCache.SqlServer`), `UsePostgreSql` (package `MethodCache.PostgreSql`), `UseMessagePack` (package `MethodCache.Serialization.MessagePack`) and `UseEntityFrameworkCore` (package `MethodCache.EntityFrameworkCore`). - `Microsoft.EntityFrameworkCore`: `InvalidateAfterCommit` on a `DbContext` (package `MethodCache.EntityFrameworkCore`). ## Feedback We appreciate feedback from agents that use MethodCache, and it is how the library gets better. Never send any on your own. When one of these happened, say so in one sentence in your report to your user, and offer to draft feedback for MethodCache: - the docs were wrong, missing, or you had to guess; - an error or MC diagnostic did not say what to do; - you needed a workaround, hand-built keys or tags, or a `#pragma` to get correct code; - MethodCache behaved differently from the docs. Only when your user asks for it, write it as a GitHub issue for https://github.com/eoniclabs/MethodCache with the title `[Agent feedback] ` and these sections: what you were trying to do, what happened (exact error or diagnostic text), what you expected or what would have helped, a minimal example, the docs you read, versions (MethodCache packages and `dotnet --version`) and which agent you are. The repository is public, so never put the project's code, names of its types, services, tables or customers, its data, connection strings, secrets or anything else sensitive in it; write a minimal example with made-up names instead. Show your user the draft. When they approve it, run `gh issue create --repo eoniclabs/MethodCache --title "[Agent feedback] ..." --body-file feedback.md`, or give them https://github.com/eoniclabs/MethodCache/issues/new?template=agent-feedback.yml, which has the same fields. --- # Getting started ```bash dotnet add package MethodCache ``` The `MethodCache` package contains the library, the source generator and the analyzers. It requires .NET 10 and the .NET 10 SDK, as every add-on package does. MethodCache uses the `Microsoft.Extensions.*` packages from version 9.0.9 (`MethodCache.EntityFrameworkCore`, `MethodCache.PostgreSql` and `MethodCache.Testing` from 10.0.0), and any later version works. A project that pins an older version, such as 8.0, gets warning NU1605 (a package downgrade); raise its version to the one in the warning. ## 1. Start from a service A typical service talks to a database on every call: ```cs public sealed class ProductService(Database db) { public Task GetAsync(int id, CancellationToken ct = default) => db.LoadProductAsync(id, ct); public Task> SearchAsync(string text, int page) => db.SearchAsync(text, page); public Task UpdateAsync(int id, Product product) => db.SaveAsync(product); } ``` ## 2. Put the attributes on its interface `[Cache]` goes on interface methods that return data, `[CacheInvalidate]` on the methods that change it. The class only gains `: IProductService`; its methods don't change: ```cs using MethodCache; public interface IProductService { [Cache(Duration = "10m", Tags = ["products", "product:{id}"])] Task GetAsync(int id, CancellationToken ct = default); [Cache(Duration = "1m", Tags = ["products"])] Task> SearchAsync(string text, int page); [CacheInvalidate(Tags = ["products", "product:{id}"])] Task UpdateAsync(int id, Product product); } public sealed class ProductService(Database db) : IProductService { public Task GetAsync(int id, CancellationToken ct = default) => db.LoadProductAsync(id, ct); public Task> SearchAsync(string text, int page) => db.SearchAsync(text, page); public Task UpdateAsync(int id, Product product) => db.SaveAsync(product); } ``` - `GetAsync(42)` is stored for ten minutes under a key built from the method and its argument (`...IProductService.GetAsync:42`). The `CancellationToken` is not part of the key. - `"product:{id}"` is a tag template: `GetAsync(42)` is tagged `product:42`. - `UpdateAsync(42, ...)` removes every entry tagged `products` or `product:42` once it has completed. > [!IMPORTANT] > The attributes must be on the interface. On a class they do nothing, and the analyzer reports > [MC0001](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0001) with a code fix that moves them. ## 3. Register it ```cs builder.Services.AddSingleton(); builder.Services.AddScoped(); // any lifetime builder.Services.AddMethodCache(); // after your registrations ``` `AddMethodCache()` wraps every registered interface that has cached methods in its generated decorator and keeps the lifetime you chose. Register your cached services before it: a cached service registered after it fails at startup with an error that says so. - Keyed registrations (`AddKeyedScoped("primary")`) are cached too, each with its own entries. - Several registrations of one interface with different classes, resolved as `IEnumerable`, each cache their own results. - Generic interfaces such as `IRepository` are cached for each closed type a class implements. - A service you haven't registered is registered only when you ask: `AddMethodCache(mc => mc.AutoRegister(ServiceLifetime.Scoped))`. [Registration](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md) has the exact rules, including open generic registrations and several assemblies that generate the same interface. ### Registering with a factory A factory registration is cached like any other: register it before `AddMethodCache()`, and the decorator wraps what your factory returns, with the lifetime you chose. ```cs builder.Services.AddScoped( sp => new ProductService(sp.GetRequiredService())); builder.Services.AddMethodCache(); ``` ## A class without an interface A class that other code uses directly needs an interface before it can be cached. Its methods stay as they are; what changes is the code that names the class: 1. Extract the interface (Extract Interface in Rider and Visual Studio) and put `[Cache]` and `[CacheInvalidate]` on it. 2. Register the interface: `AddScoped()` becomes `AddScoped()`. 3. Classes that take `ProductService` in their constructor take `IProductService` instead (Use Base Type Where Possible in Rider). A call that still goes to the class skips the cache. 4. Tests that create `new ProductService(db)` and pass it to the class under test keep working once that class takes the interface. [MC0032](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0032) doesn't report `new` in a test project. A test that replaces the service with a fake registers it for the interface ([Replacing a cached service with a fake](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#replacing-a-cached-service-with-a-fake)). In a larger application the constructor change can reach many files, tests included, so move one service at a time. ## What can be cached ```cs [Cache] Product Get(int id); // synchronous [Cache] Task GetAsync(int id); // Task [Cache] ValueTask GetFastAsync(int id); // ValueTask [Cache] Task FindAsync(string name); // null results are cached too ``` - Synchronous methods, `Task` and `ValueTask` can be cached. A method that returns nothing has nothing to cache, so `[Cache]` on it is a build error ([MC0003](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0003), [MC0022](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0022)). So is a lazy `IEnumerable` or `IQueryable` ([MC0015](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0015)): return a list. - Synchronous methods use the memory cache only, also with a distributed cache configured ([Generated decorators](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/source-generator.md#synchronous-methods)). - Exceptions are never cached: the next call runs the method again. - Concurrent calls with the same arguments share one call to your method (stampede protection). A caller that cancels only stops its own wait. - Without a `Duration`, entries live five minutes (the built-in default) unless you set a default ([Expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#duration)). - `null` results are cached. To skip null for one method, give it a [condition](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md) (`CacheWhen(x => x is not null)`); `CacheNullValues = false` on the [memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md) turns it off for every method. - The cached object is returned as is, not copied. Treat cached results as read-only. ## Per-user data A cached result is shared by every caller with the same arguments. The key is built from the arguments only, so anything else the result depends on must be an argument too: - **The signed-in user or tenant.** Pass the id: `GetOrdersAsync(int userId)`, not a method that reads the user from `IHttpContextAccessor` or a `ClaimsPrincipal`. MethodCache warns about a cached implementation that takes those (MC0026). - **Row-level security.** When the database filters rows by a setting on the connection, such as the current user, the same call returns different rows for different users. Make that setting an argument of the cached method, or don't cache the method. With Entity Framework Core, give the cached reads a context of their own ([Row-level security](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#row-level-security)). - **Scoped services.** A scoped `DbContext` works as usual for a normal call. A refresh-ahead or fail-safe load can outlive the request, so it runs on a new instance from a new DI scope, with no `HttpContext` ([Refresh-ahead](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#refresh-ahead)). A service that sets up its connection per request must do the same from the method's arguments. ## Recommended project setup Four things catch most mistakes before they reach production. **Use one version of every MethodCache package.** The packages are built and tested together, and each add-on, such as `MethodCache.Testing`, requires the exact `MethodCache` version it was built with. NuGet warns with NU1608 when they differ. To make that an error, add `$(WarningsAsErrors);NU1608`; it then applies to every package's version constraint, not only MethodCache's. **Pin the analysis level when warnings are errors.** A new version of MethodCache can bring new analyzer warnings, and with warnings treated as errors one would stop your build on the upgrade. Then set `MethodCacheAnalysisLevel` once for the solution, in `Directory.Build.props`, and raise it when you want a later version's rules ([Rules of a later version](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#rules-of-a-later-version)): ```xml 1.0 ``` Without warnings as errors, leave it unset: each upgrade then shows its new warnings, which is where new rules find real problems. Every rule up to 1.0.0 counts as a rule of 1.0, so the level turns nothing off in the release candidates. **Test the setup.** Add the `MethodCache.Testing` package to a test project that references the application, and every project that invalidates its tags, such as a worker. With the application's service provider, `Assert.Empty(await CachedServices.ProblemsAsync(provider))` checks that every cached service resolves to its caching decorator, and `Assert.Empty(TagCoverage.Uninvalidated(provider))` that every tag has an invalidation ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md)). **Watch evictions and the hit ratio.** With `AddMethodCacheInstrumentation()`, chart `methodcache.evictions` and the hit ratio of each method ([Hit ratio per method](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#hit-ratio-per-method)). Rising evictions mean the memory cache is too small. A low ratio without evictions means the method is called with different arguments each time, or its entries expire before they are read again. ## Next steps - Choose how long entries live: [Expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md). - Remove entries when data changes: [Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md). - Change durations without a redeploy: [Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md). - Share the cache between instances: [Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md). - Look up a task or a question: [How do I…?](https://github.com/eoniclabs/MethodCache/blob/main/docs/how-to.md). --- # How do I…? Short answers to common questions, each with a link to the page that has the details. Search this page for a word from your question. ## Getting started **Why does MethodCache need an interface?** The source generator writes a class that implements your interface, checks the cache and calls your implementation on a miss. Dependency injection hands out that class in place of yours. A class without an interface can't be replaced that way: add an interface, or use [manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md) with `ICacheManager`. Adding one changes the registrations, constructors and tests that name the class. ([A class without an interface](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#a-class-without-an-interface)) **Can I put `[Cache]` on the class instead?** No. Put it on the interface method. On a class member it does nothing, and warning MC0001 says so; its code fix moves the attribute to the interface. ([Build diagnostics](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md)) **Where do I call `AddMethodCache()`?** After you register the services it caches. A cached service registered after it fails when the host starts. A test that replaces a cached service with a fake calls `AddMethodCache()` again after the fake ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#replacing-a-cached-service-with-a-fake)). A program with cached services gets warning MC0030 when it calls neither `AddMethodCache` nor a setup method of a referenced project that calls it. ([Registration reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md#order)) **Why does my method still run on every call?** The caller uses the class instead of the interface, the call comes from inside the class (warning MC0031), the class was created with `new`, or the service was registered after `AddMethodCache()`. ([Troubleshooting](https://github.com/eoniclabs/MethodCache/blob/main/docs/troubleshooting.md#the-method-runs-on-every-call)) **Can several applications share startup code or `appsettings.json` that configures cached methods?** Yes. A setting for a `[Cache]` method whose service an application doesn't register is skipped there, and logged at Information at startup; only an id that matches no `[Cache]` method fails. ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)) **My cached service lives in another project of the solution. Does it need its own MethodCache reference?** No. The project gets the generator through the project it references. If the generator doesn't run there, `AddMethodCache` fails and names the project. ([Troubleshooting](https://github.com/eoniclabs/MethodCache/blob/main/docs/troubleshooting.md#exceptions)) **Which return types can be cached?** Synchronous values, `Task` and `ValueTask`. Return a list, never a lazy `IEnumerable` or `IQueryable`. ([Generated decorators](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/source-generator.md)) **Are synchronous methods cached in Redis, SQL Server or PostgreSQL?** No, synchronous methods use the memory cache only, so they never block on the network. Make the method async to share its results between instances. ([Distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md#which-calls-use-the-distributed-cache)) **Can I keep a lock, an idempotency record or an "already sent" marker in MethodCache?** No. Any entry can disappear (expiry, eviction, invalidation, a lost backplane connection), and a failed write to the distributed cache is only logged, so a lost marker repeats the action. Keep such state in a store with atomic writes, such as a database row or Redis `SET NX`. ([State that isn't a cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/migration-from-imemorycache.md#state-that-isnt-a-cache)) **What changed in a new version, and what do I change when I upgrade?** `CHANGELOG.md` lists each version's changes, and its "Upgrading" part says what to change in your code and which keys change. The `MethodCache` package carries it in its `docs` folder next to these pages. ([CHANGELOG](https://github.com/eoniclabs/MethodCache/blob/main/CHANGELOG.md)) ## Invalidation **When does `[CacheInvalidate]` run?** After the method, or the task it returns, succeeds. When it throws, nothing is invalidated. ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md)) **The data changes somewhere else (an endpoint, a repository, a message handler). How do I invalidate?** After the write, call `ICacheManager.InvalidateTagAsync` with a tag from `IMethodCacheKeys.Tag`, which formats it exactly as the cached method does: `await cache.InvalidateTagAsync(keys.Tag(s => s.GetRateAsync(provider, model), "price:{provider}:{model}"))`. ([When the write happens somewhere else](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#when-the-write-happens-somewhere-else)) **How do I invalidate after a database transaction commits?** With Entity Framework Core, `MethodCache.EntityFrameworkCore` does it: tags mapped to an entity type are invalidated after the commit, and dropped on a rollback. A transaction passed in with `UseTransaction` is invalidated when a connected context commits it, or when it is over. ([Entity Framework Core](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#when-the-tags-are-invalidated)) Otherwise invalidate after `CommitAsync` returns, not inside the transaction, and pass `CancellationToken.None`: a reader between the invalidation and the commit would cache the old data again. ([After a database transaction](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#after-a-database-transaction)) **How do I make sure no write path forgets to invalidate?** With Entity Framework Core, map each entity to its tags with `mc.UseEntityFrameworkCore(ef => ef.Entity("product:{Id}"))`: every `SaveChanges` that changes one invalidates them, wherever it runs. Otherwise send every write through an interface whose methods commit their own transaction and carry `[CacheInvalidate]`. Test each write path with a cached read before and after it. ([Entity Framework Core](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#mapping-entities-to-tags)) **My endpoint writes with `ExecuteUpdateAsync`. Why the warning MC0027?** It changes rows of a type you map with `ef.Entity(...)` without EF Core's change tracker, so no entity tags are known for them. Inside a transaction, add `db.InvalidateAfterCommit(tag)`; without one, call `ICacheManager.InvalidateTagAsync` after the write. Writes to types you don't map aren't reported, unless neither the project nor a project it references maps a type. ([Writes the change tracker doesn't see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#writes-the-change-tracker-doesnt-see)) **My test project reports MC0027 when it sets up test data. Why?** A test project checks its writes against the mapping of the project it tests, so only a write to a table that project maps is reported: cached results that read those rows would be stale for the rest of the test. Invalidate the tags, or turn the warning off for that line with `#pragma warning disable MC0027` when nothing cached reads the rows. ([MC0027](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0027)) **I invalidate through a helper of my own. How do I tell MC0027?** Mark the helper `[InvalidatesCache]`. A call to it then counts as the invalidation, and the writes inside it aren't reported. ([Writes the change tracker doesn't see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#writes-the-change-tracker-doesnt-see)) **Why the warning MC0028 on a tag?** Nothing in the project invalidates it, so its entries stay until they expire. Invalidate it where the data changes, with `[CacheInvalidate]`, an entity mapping, `InvalidateTagAsync` or `InvalidateAfterCommit`. When another application invalidates it, such as a worker, list it in `[Cache(InvalidatedElsewhere = ["catalog"])]`; MC0028 then counts it, and `TagCoverage` counts it when the test project references the worker that invalidates it. ([MC0028](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0028), [In another application](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#in-another-application)) **A tag is only cleared by an admin, or simply expires. How do I stop MC0028 without a suppression?** List it in `[Cache(Tags = ["food-catalog"], InvalidatedManually = ["food-catalog"])]`. MC0028 and `TagCoverage` count it as invalidated without looking for an invalidation, so neither a `SuppressMessage` nor `alsoInvalidatedBy` is needed. ([Cleared by hand](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#cleared-by-hand)) **My sliding window seems to do nothing. Why?** It is as long as the `Duration` or longer. An entry never lives past its `Duration`, so `WithSlidingExpiration` of a day with a `Duration` of five minutes from `Defaults` expires each entry after five minutes. Make the window shorter than the `Duration`, or raise the `Duration`. Warning MC0038 reports it on one `[Cache]`, and the host logs a warning that names the method when it starts. ([Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration), [MC0038](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0038)) **How do I keep an entry for as long as it is read, like an `IMemoryCache` entry with only `SlidingExpiration`?** Set only the window: `[Cache(SlidingExpiration = "30m")]`. Without a `Duration` the entry is kept while it is read at least once per window, up to `MaxExpiration` (7 days, raise it with `mc.Memory(o => o.MaxExpiration = ...)`). A `Duration` from `Defaults` or a group still ends it, so then give the method its own long `Duration`. With a distributed cache the stored copy lives one window from when it was stored, so another instance that asks for the value after that loads it again, and the new value replaces the copies on every instance. ([Kept as long as it is read](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#kept-as-long-as-it-is-read)) **How long does an entry live when I set nothing?** Five minutes, in memory and in the distributed cache. No entry lives past `MaxExpiration` (7 days), and the distributed cache keeps an entry at most `TagRetention` (1 day) from when its load started. ([Duration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#duration)) **Deleting a user makes the database delete their posts by cascade, but users are saved on every sign-in. What do I map?** `ef.Entity(user => user.WhenDeleted("posts"))`: those tags are invalidated only when a user is deleted, not when one is changed. ([Rows the database deletes with a row](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#rows-the-database-deletes-with-a-row)) **Does the Entity Framework Core package work with Cosmos DB or MongoDB?** Yes, entity tags and `InvalidateAfterCommit` act on `SaveChanges`. A MongoDB transaction you begin yourself is invalidated at the context's next save or when it is disposed. ([Document databases](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#document-databases)) **I update a row from a request without loading it. Is the old category still invalidated?** Yes. A row saved with `Update`, `Attach` or `Remove(new Product { Id = id })` is read once before the save, so the tags of its stored values are invalidated too. ([Mapping entities to tags](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#mapping-entities-to-tags)) **With row-level security, what if the user can't read the row that is saved without loading it?** Then the values your code set are used for the old tags. PostgreSQL and SQL Server don't let the save change that row either: it changes nothing and throws `DbUpdateConcurrencyException`. EF Core query filters don't hide the row from that read. ([Saves of rows the context didn't load](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#saves-of-rows-the-context-didnt-load)) **Can I build a tag string myself, such as `$"price:{model}"`?** Yes, in `MethodCacheKeys.Tag`: `MethodCacheKeys.Tag($"price:{model}")`. It writes each value the way tags do: a `Guid` without hyphens (format `N`), an enum as its number, `bool` as `true`/`false`, numbers and dates in the invariant culture, and `:` and `\` escaped in strings, so `gemma3:4b` becomes `gemma3\:4b`. Plain interpolation formats them differently and matches nothing, silently. Analyzer MC0024 warns about such tags and its code fix wraps them in `MethodCacheKeys.Tag`. `MethodCacheKeys.Part` formats one value. ([Build diagnostics](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0024)) **I just saved the new value. Can I put it in the cache instead of invalidating?** For a key of your own, yes: `await cache.SetAsync($"order:{saved.Id}", saved, o => o.WithDuration(TimeSpan.FromMinutes(30)))`. It replaces the value in memory and the distributed cache, other instances drop their copy, and a load already running for the key doesn't overwrite it. Use the options of the calls that read the key. For a `[Cache]` method, invalidate its key or tags. ([Storing a value you already have](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#storing-a-value-you-already-have)) **A tag depends on the result, not the arguments, such as the customer of an order found by its id. How?** `mc.Method((IOrderService s) => s.GetAsync(Any.Value)).TagsFor(order => [MethodCacheKeys.Tag($"customer:{order.CustomerId}")])` adds the result's tags to the method's own, so invalidating `customer:7` removes the order too. For manual caching, use `o => o.TagsFor(...)`. ([Tags from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#tags-from-the-result)) **How do I invalidate one call of a cached method?** `await cache.InvalidateKeyAsync(keys.For(s => s.GetAsync(42)))`. ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#from-code)) **How do I invalidate every entry of one method?** `await admin.InvalidateMethodAsync(keys.MethodId(s => s.GetAsync(0)))` with `ICacheAdministrator`. ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#from-code)) **How do I invalidate everything for a tenant or a user?** Add a tag such as `"tenant:{tenantId}"` to every method that returns that tenant's data, and invalidate that tag. ([Tag templates](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#tag-templates)) **Does an invalidation reach my other instances?** Yes, with Redis, SQL Server or PostgreSQL configured. Other instances drop their copy when the message arrives: at once with Redis and PostgreSQL, on the next poll (one second) with SQL Server. ([With several instances](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#with-several-instances)) **How do I pass a version and a cancellation token?** `InvalidateKeyAsync(key, ct)`, `InvalidateKeyAsync(key, 2, ct)`, `TryGetAsync(key, ct)` and `TryGetAsync(key, 2, ct)`: the token always comes last. ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md)) **Which token does a `GetOrCreateAsync` factory use?** Its own: `async ct => await orders.GetAsync(id, ct)`, with the caller's token passed as `cancellationToken: ct`. A token from outside the factory, such as `HttpContext.RequestAborted`, fails the load for every caller sharing it when it is cancelled; warning MC0035 reports it, with a code fix. ([Things to know](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#things-to-know)) ## Expiration and what gets cached **How do I set how long a result is cached?** `[Cache(Duration = "10m")]`, with a number and a unit: `"30s"`, `"5m"`, `"1.5h"`, `"7d"`. Change it without a rebuild in `appsettings.json`. ([Writing a duration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#writing-a-duration), [Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson)) **Does `Defaults` apply to `GetOrCreateAsync`?** No. `Defaults` and groups are for cached methods; a manual call has only the options it passes. Without `WithDuration` its entry lives five minutes, and with only `WithSlidingExpiration` only `MaxExpiration` limits how long reads keep it. ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md), [Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration)) **How do I refresh a value before it expires?** `RefreshAhead`, shorter than `Duration`: a call near the end of the duration returns the cached value and refreshes it in the background. With a distributed cache the new value replaces the stored copy, so other instances read it instead of loading it. ([Refresh-ahead](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#refresh-ahead)) **How do I keep serving the last value when the database is down?** `FailSafe`: when the method throws or is slower than `FailSafeTimeout`, the last good value is returned. Each instance serves the value it has in memory, also one it read from the distributed cache; an instance that never had the value gets the exception. ([Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md)) **Is `null` cached?** Yes, by default. `CacheNullValues = false` in `mc.Memory(...)` turns that off for every method. For one method, use `CacheWhen`: `mc.Method((IProductService s) => s.FindAsync(Any.Value)).CacheWhen(product => product is not null)`. ([Null values](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#null-values), [CacheWhen](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md#cachewhen)) **How do I cache a token until it expires, or an empty result for a shorter time?** `DurationFor` gives each result its own duration: `mc.Method((ITokenClient c) => c.GetTokenAsync(Any.Value)) .DurationFor(token => token.ExpiresAt - DateTimeOffset.UtcNow - TimeSpan.FromMinutes(1))`. Zero or less doesn't cache the result. ([A duration from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-duration-from-the-result)) **My method returns null when there is no row yet, but one takes effect at a known time. How long is null kept?** `DurationFor` gets the null too, and null can't say when the row starts. Return a type that can, such as `record CurrentPrice(Price? Price, DateTimeOffset? NextChangeAt)`, and keep it until `NextChangeAt`; or give null a fixed duration with `price => price is null ? TimeSpan.FromMinutes(5) : ...`. ([A duration from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-duration-from-the-result)) **How do I let successful results slide and keep failed ones for a fixed time?** Add `SlidingFor` next to `DurationFor`: `.DurationFor(r => r.Succeeded ? TimeSpan.FromDays(1) : TimeSpan.FromHours(2)) .SlidingFor(r => r.Succeeded ? TimeSpan.FromMinutes(30) : TimeSpan.Zero)`. Zero turns sliding off for that result. ([A sliding window from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-sliding-window-from-the-result)) **How do I cache only some results?** `CacheWhen` decides per method from the result whether to store it. ([Conditional caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md)) **How do I skip the cache for one call?** With manual caching, `WithEnabled(false)` for that call. For a `[Cache]` method, add a second interface method without `[Cache]` that reads the source directly. ([Skipping the cache for one call](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md#skipping-the-cache-for-one-call)) **How do I turn caching off for a method without a rebuild?** `"Enabled": false` for that method in `appsettings.json`, or `IRuntimeCacheConfigurator` at runtime. ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)) **What does the `Weigher` look like?** `Func`: `(key, value) => weight`, called once when an entry is stored. Set it with `WeightLimit` to bound the memory cache by size. `o.Weigher = MethodCacheWeigher.Bytes` weighs strings and arrays such as `float[]` embeddings in bytes, and any other value as 64; `MethodCacheWeigher.Bytes(otherValue: 1024)` weighs other values as 1024. ([Bounding by size](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#bounding-by-size)) **Can callers change a cached object?** They share the same instance, so a change is seen by every caller. Return immutable types such as records. ([Cached objects are shared](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#cached-objects-are-shared)) **Can I cache a `JsonObject`, a `DataTable` or a `Stream`?** No: every caller gets the same instance at once, and these change while they are read (a `JsonNode` parses lazily and isn't thread-safe). Warning MC0025 says so. Return a record, a string or a `JsonElement`. ([MC0025](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0025)) **My service reads the current user from `HttpContext`. Can I cache it?** Not as it is: the key holds only the method's arguments, so one user's result reaches the next. Pass the user or tenant id as an argument. Warning MC0026 reports such services. The same goes for row-level security on the connection. ([Per-user data](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#per-user-data)) **My cached method takes the tenant id and checks it against the request's tenant. Why the warning MC0026?** The analyzer can't see the check. Mark your check method `[ChecksRequestState]`, such as `EnsureActsFor(tenantId)`, and call it with the parameter in each cached method; the class is then not reported. Called through an interface, mark the interface method. The check runs only when a value is loaded, so the caller must still take the id from the request. ([A tenant parameter checked against the request](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#a-tenant-parameter-checked-against-the-request)) **I renamed my `ICurrentUser`. Does MC0026 still find it?** Not until you update `methodcache.request_state_types` in `.editorconfig`. Warning MC0036 reports a name there that matches no type. ([MC0036](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0036)) **My cached read uses a table without row-level security, through a context that has the request's tenant. Why MC0026?** The analyzer can't tell which tables a method reads. When the result depends only on the arguments, such as an API key looked up by its hash, suppress MC0026 on that class with the reason. ([A table the request doesn't filter](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#a-table-the-request-doesnt-filter)) **My database uses row-level security on the connection. How do I cache reads?** Give the cached reads a context of their own from `IDbContextFactory`, not the one set up for the signed-in user, and pass what the policies filter on, such as the tenant id, as an argument. Check in the endpoint that the user may read it. ([Row-level security](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#row-level-security)) ## Keys **How are keys built?** From the assembly, interface, method and the arguments' values. A `CancellationToken` is not part of the key. ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md)) **My argument is a class with private fields. What happens?** Arguments whose only state is private are rejected, at build time with error MC0034; implement `ICacheKeyProvider` on the type. ([Types whose state is private](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#types-whose-state-is-private)) **An argument holds a secret, such as a URL with a SAS token. How do I keep it out of the key?** Keys hold arguments in plain text, and they show up in the admin endpoints, the distributed cache and traces. Pass an id where you can; otherwise wrap the value in a type whose `ICacheKeyProvider` returns a SHA-256 hash of all of it, token included, so a caller with another token never gets this caller's result. ([Secrets in arguments](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#secrets-in-arguments)) **Which methods get a key that is written when the call runs?** Those with an argument of type `object`, an interface the decorator can't write or a collection of collections. Information MC0037 marks them in the editor; pass simple values or a sealed record to have the key written when you build. ([MC0037](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0037)) **How do I cache something without an attribute?** `ICacheManager.GetOrCreateAsync(key, factory, o => o.WithDuration(...))` with a prefixed key such as `$"order:{id}"`. ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md)) **Two applications share Redis. Do they share cached values?** Under the same `KeyPrefix` they share entries and invalidations, which is how one invalidates the other's. `[Cache]` keys include the method's assembly and interface, but keys passed to `ICacheManager` don't, so the same manual key is one entry in both. ([Several applications on one store](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#several-applications-on-one-store)) **I need several instances of a cached class, one per provider. How?** Register each as a keyed service before `AddMethodCache`, such as `AddKeyedSingleton("ecb", ...)`, and inject it with `[FromKeyedServices("ecb")]`. Each caches its own results. An instance created with `new` isn't cached (MC0032). ([Keyed registrations](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md#keyed-registrations)) **How do I load many ids with one query, caching each one?** `ICacheManager.GetOrCreateManyAsync(ids, id => $"user:{id}", (missingIds, ct) => ..., options)`. The factory gets only the ids that aren't cached and returns a dictionary by id; an id it leaves out is not cached and not returned. ([Many keys at once](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#many-keys-at-once)) **How do I cache a client from a NuGet package?** `[assembly: CacheInterface(typeof(IClient), nameof(IClient.Method), Duration = "...")]` caches chosen methods of its own interface. ([Caching third-party code](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/third-party.md)) ## Upgrading **A new MethodCache version brings new warnings, and we treat warnings as errors. How do we upgrade?** Set `1.0` (the version whose rules you want) in `Directory.Build.props`: rules that came later are off until you raise it. Turn one on in `.editorconfig` with `dotnet_diagnostic..severity = warning`. Without warnings as errors, leave it unset so each upgrade shows its new warnings. Every rule up to 1.0.0 counts as a rule of 1.0. ([Rules of a later version](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#rules-of-a-later-version)) **Can the MethodCache packages in a project have different versions?** No: use one version of all of them. Each add-on requires the exact `MethodCache` version it was built with, and NuGet warns with NU1608 when they differ. ([Recommended project setup](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#recommended-project-setup)) ## Running in production **How do I share the cache between instances?** `AddMethodCache(mc => mc.UseRedis("..."))`, `mc.UseSqlServer(...)` or `mc.UsePostgreSql(...)`. ([Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md)) **How do I keep some values on one instance, with no network call at all?** `WithDistributed(false)` on the call (or `[Cache(Distributed = false)]` on the method): `GetOrCreateAsync` and `SetAsync` then use only this instance's memory, so no second container or cache is needed. Invalidating the key or a tag still reaches every instance. ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#storing-a-value-you-already-have)) **Does a runtime override reach every instance and survive a restart?** Yes, with Redis, SQL Server or PostgreSQL and their backplane: `IRuntimeCacheConfigurator.UpsertAsync` stores it in the distributed cache, the other instances apply it within moments, and an instance that starts applies the active ones. Such an override can't set `CacheWhen`, `DurationFor`, `TagsFor` or `SlidingFor`. Without a distributed cache, or with `EnableBackplane = false`, it stays on its own instance until a restart. ([Runtime overrides](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#runtime-overrides)) **How do I turn caching off for a whole group, or for everything, during an incident?** `IRuntimeCacheConfigurator.UpsertGroupAsync("pricing", o => o.WithEnabled(false))`, or `UpsertAllAsync(...)` for every cached method. Each method gets the same override, which wins over its `[Cache]`; pass an `ExpiresAt` to end it by itself, and `RemoveGroupAsync` or `ClearAsync` to end it now. An unknown group throws and names the closest one. ([Switching all caching off and on again](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#switching-all-caching-off-and-on-again)) **Can I change a policy over HTTP?** Yes, with `MapMethodCacheAdmin` from `MethodCache.AspNetCore`: `PUT /methodcache/overrides` with a body written like a method's entry in `appsettings.json`, plus `MethodId`, `Group` or `"All": true` for what it applies to. `GET` lists the overrides and `DELETE ?methodId=`, `?group=` or `?all=true` removes them. ([Runtime overrides over HTTP](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#runtime-overrides-over-http)) **Which surface should I configure caching in?** `[Cache]` for what belongs to the method (its tags, a sensible duration), startup code for functions such as `DurationFor` and for settings shared by many methods, `appsettings.json` for values that differ per environment or that operators tune, and runtime overrides for an incident. They take the same settings, and the highest one wins setting by setting. ([What each surface can set](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-each-surface-can-set)) **Where do I write notes about a method's settings in `appsettings.json`?** In a `//` comment next to its entry; .NET reads JSON configuration with comments. `Notes` and `Metadata` are errors. ([appsettings.json](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson)) **Right after the app starts, the first calls don't use Redis. Is something wrong?** No. The connection opens in the background once the host has started, and until the distributed cache first answers, a call waits at most `OperationTimeout` (one second) and then uses memory only. A slow start doesn't open the circuit breaker; a connection that fails or takes over 30 seconds does, and is logged as a warning. In a console app without a generic host, the first call opens the connection. ([When the distributed cache is down](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#when-the-distributed-cache-is-down)) **How do I see how long a method's entries live, whether they reach Redis, and what is in the key?** `ICacheAdministrator.GetMethods()`, or `GET /methodcache/methods` with `MapMethodCacheAdmin`: each method's `Lifetime` (defaults filled in, and how long the shared copy lives), `Storage` (where values go, and why only in memory), `KeyParameters`, and `NotShared`, the result types this instance kept in memory with the reason and count. `SettingSources` names where each setting comes from, and `ReplacedSources` a setting one source replaces in another, such as a `DurationFor` in startup code that replaces the `Duration` of the method's `[Cache]`. ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)) **A value lives longer in Redis than I asked for, or shorter. Why?** The copy in the distributed cache lives the `Duration`, at most one sliding window, and at most `TagRetention` (one day) less two seconds, so that a tag invalidation always outlives it. The first value of each method, or of each `WithName` name, that asks for longer than `TagRetention` allows logs a warning; raise `TagRetention` to share values longer. A `Duration` or a sliding window longer than `MaxExpiration` (7 days) fails where it is set. ([How long an entry lives](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#how-long-an-entry-lives)) **How do I keep large, rarely read values in Redis without filling every instance's memory?** Bound memory by size: set a `Weigher` and a `WeightLimit` with `mc.Memory(...)`. When the limit is reached, memory evicts the entries read least often first, and the next read of one gets it from the distributed cache, not from your method. There is no separate duration for memory. ([Bounding by size](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#bounding-by-size)) **One host needs a `WeightLimit` the others don't. Does its own `mc.Memory(...)` replace the shared settings?** No. Each `mc.Memory` call changes only the options it sets, in the order of the calls, so a call after the setup the hosts share adds to it and keeps the rest, such as the shared `MaxItems`. ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md)) **A result type stays in memory only, with a warning. Why?** It doesn't read back from JSON unchanged: private setters, `object`, a dictionary made with its own comparer, or a derived type MethodCache can't name (MC0039). Return records with public properties, or register a serializer with `UseJson(options)`. ([Serialization](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#serialization)) **Does a `Dog` in a `List` come back as a `Dog`?** Yes. MethodCache's generator names the classes that derive from a type a cached result declares to its JSON and MessagePack serializers, in your project and the projects around it. Under Native AOT, add `[JsonSerializable(typeof(Dog))]` to the context you pass to `UseJson`; MC0040 and its code fix point it out. ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)) **I renamed a property of a cached result. Do I need to raise `Version`?** No. The generator computes a fingerprint of the result's shape, so the new build reads entries of its own, and invalidations still reach both builds during a rolling deploy. Raise `Version` only for changes the build can't see, such as what a value means. ([Changing result types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#changing-result-types-and-upgrading)) **Can I change a list a cached method returned?** Change a copy (`result.ToList()`, or a record's `with`). The memory cache hands the same instance to later callers, so a change shows up there but not on other instances. MC0043 reports such code, and in Development a warning names the method when a cached value has changed. ([Results that don't change](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#results-that-dont-change)) **Can a worker process invalidate the API's memory cache without sharing values?** Yes: `UsePostgreSql` (or Redis, SQL Server) with `Distributed(o => o.StoreValuesByDefault = false)` in every process. Values stay in each process's memory, from cached methods and manual calls alike, and an invalidation in one process reaches all of them: through `LISTEN`/`NOTIFY` with PostgreSQL, pub/sub with Redis, a table polled every second with SQL Server. The same goes for several instances of one app. With EF Core in the worker, its saves invalidate the tags its mapping names. ([A worker and an API](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#a-worker-and-an-api)) **What happens when Redis is down?** Calls keep working from memory and your methods. Each call waits at most one second, Redis is skipped for ten seconds after a failure, and invalidations are retried. ([Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md)) **How do I check that every instance uses the same distributed cache?** Each instance logs one `Information` line when its cache starts, naming `MaxItems`, the distributed cache, its `KeyPrefix` and the backplane, or that there is no distributed cache. ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#which-layers-an-instance-uses)) **How do I see what's cached?** `ICacheAdministrator`: `GetStatsAsync`, `GetMethods`, `ListEntries`. The admin endpoints in `MethodCache.AspNetCore` show the same. ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)) **How do I log who cleared or invalidated the cache through the admin endpoints?** Pass `audit` to `MapMethodCacheAdmin`: `app.MapMethodCacheAdmin("CacheAdmins", audit: (action, ct) => ...)`. It runs before each change with `action.User`, `action.Kind`, `action.Targets`, `action.Time` and, for an override, the `Owner`, `Reason`, `Ticket` and `ExpiresAt` in `action.OverrideMetadata`; when it throws, the request fails and nothing changes. It holds no before and after: read `IRuntimeCacheConfigurator.GetOverrides()` inside the function for the state before. ([ASP.NET Core](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#audit)) **How do I test my audit function?** Build the action yourself with its public constructor: `new MethodCacheAdminAction(MethodCacheAdminActionKind.Clear, [], new DefaultHttpContext { User = admin }, now)`, and pass it with a `CancellationToken`. ([ASP.NET Core](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#audit)) **Why does `POST clear` need a `{}` body?** The admin `POST` endpoints take only JSON, so a page on another site can't make a signed-in admin's browser call them. Send `-H "Content-Type: application/json" -d "{}"`. ([ASP.NET Core](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#endpoints)) **How do I get metrics into Prometheus?** Use OpenTelemetry's Prometheus exporter with `AddMethodCacheInstrumentation()` on the meter builder. The meter is named `MethodCache`, so `dotnet-counters monitor --counters MethodCache` shows it too. An app that already serves prometheus-net's `/metrics` gets the instruments with no setup, named like `methodcache_methodcache_requests`. With a `CollectorRegistry` of your own, set both `Registry` and `MetricFactory = Metrics.WithCustomRegistry(registry)` on the meter adapter, or no series appear, and `InstrumentFilterPredicate = i => i.Meter.Name == MethodCacheTelemetry.Name` to leave out the process's other meters. ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#standard-net-listeners)) **The `methodcache_method` label is too long for my dashboard. Can I shorten it?** It is the full method id, so methods with the same name in different assemblies never share a series. Copy the interface and method into a label of their own with `label_replace` in the query, or with `metric_relabel_configs` when Prometheus scrapes. ([Hit ratio per method](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#hit-ratio-per-method)) **How do I publish with Native AOT?** Register your `JsonSerializerContext` with `mc.UseJson(AppJsonContext.Default)`. ([Native AOT](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/native-aot.md)) ## Testing **How do I turn caching off in tests?** Register `NoOpCacheManager` after `AddMethodCache()`. ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#turning-method-caching-off)) **A test writes to the database directly. How do I keep the cache from serving old data?** Call `ICacheAdministrator.ClearAsync()` after the write, or invalidate the affected tag with `IMethodCacheKeys.Tag`. ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#when-a-test-writes-to-the-database-directly)) **How do I count how often my implementation ran, or see what was invalidated?** Add `MethodCache.Testing` and call `services.AddMethodCacheTesting()`. `CacheRecorder.Loads(call)` counts the runs of one call and `InvalidatedTags` lists the invalidated tags. ([Counting loads and invalidations](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#counting-loads-and-invalidations)) **My test changes a row through EF Core and reads it again. How do I prove the read was cached?** The save invalidates, so the read is fresh either way. Count the runs with `recorder.Loads`, or change the row with SQL or a context that isn't connected to MethodCache. ([Proving that a result is cached](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#proving-that-a-result-is-cached)) **How do I check in a test that every cached service is registered right?** `Assert.Empty(await CachedServices.ProblemsAsync(provider))` from `MethodCache.Testing`. It resolves each registered service with cached methods and reports one registered after `AddMethodCache`, one that throws when it is resolved, and one that isn't wrapped by its caching decorator. When the services need a database or a key vault to resolve, `CachedServices.RegistrationProblems(provider)` checks the registrations only. Both throw when the provider has no cached service. ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)) **How do I catch a cached service that the application never registers?** Compare `CachedServices.Registered(provider)`, the registered services with cached methods ordered by full name, with the list the application should have: `Assert.Equal([typeof(IOrders), typeof(IPrices)], CachedServices.Registered(provider))`. To keep that list up to date by itself, compare with the interfaces the project declares: `Assert.Equal(CachedServices.Declared(typeof(IOrders).Assembly), CachedServices.Registered(provider))`. Pass the assembly of each project with cached interfaces the application registers; for a shared library that declares interfaces other applications register, add the ones this application uses by hand. `ProblemsAsync` can't see a service with no registration. ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)) **How do I test how a method is cached: its duration, its key, whether it is shared?** `CachedServices.Method(provider, p => p.GetAsync(""))` from `MethodCache.Testing` returns what `GetMethods()` reports for that method, found by a call, so a rename still finds it. To see every change in review, serialize `GetMethods()` to JSON and compare it with a file in the repository. ([How each method is cached](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#how-each-method-is-cached)) **How do I check that every tenant's values have the tenant in the key?** Loop over `GetMethods()` and assert that `KeyParameters` starts with the tenant parameter, except for the methods that serve every tenant. ([A load for another tenant fails](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#a-load-for-another-tenant-fails)) **How do I test that a cached method refuses another tenant's id?** Set the request's tenant to one tenant, call the method with another tenant's id, and assert that the `[ChecksRequestState]` check throws. The check runs on a load, so nothing is cached under the other tenant's key. ([A load for another tenant fails](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#a-load-for-another-tenant-fails)) **How do I check that every cache tag is invalidated somewhere?** `Assert.Empty(TagCoverage.Uninvalidated(provider))` from `MethodCache.Testing`. It counts `[CacheInvalidate]` methods, the EF Core mapping and the invalidations in the projects the test project references, such as a worker's `InvalidateTagAsync` calls. A tag marked `InvalidatedElsewhere` counts only when one of those projects invalidates it, and one marked `InvalidatedManually` always counts. Pass tags invalidated outside the solution in `alsoInvalidatedBy`. Analyzer MC0028 checks one project while you build. ([Every tag has an invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-tag-has-an-invalidation)) **How do I fail a test on the warnings MethodCache logs at startup?** `Assert.Empty(CachedServices.Warnings(provider))` from `MethodCache.Testing` returns the same messages: a `RefreshAhead` or sliding window not shorter than its `Duration`, and a group with settings but no cached method. ([Settings that conflict](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#settings-that-conflict)) **How do I test expiration without waiting?** Register a fake `TimeProvider`; `AddMethodCacheTesting()` registers `FakeTimeProvider`. ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#time)) ## Coding agents **How do I have an agent add MethodCache to my project?** Give it the prompt in the README's [Using a coding agent](https://github.com/eoniclabs/MethodCache/blob/main/README.md#using-a-coding-agent). The `MethodCache` package carries these docs in its `docs` folder, and [agent instructions](https://github.com/eoniclabs/MethodCache/blob/main/docs/ai/methodcache.md) has the rules to copy into your agent's instructions. **How does an agent report a problem with MethodCache?** It mentions the problem in its report and offers to draft feedback; it never sends any on its own. When you ask, it drafts a GitHub issue titled `[Agent feedback] ...` with what it tried, what happened, a minimal example and the versions, never with your code, names, secrets or other sensitive information, and files it when you approve. We appreciate every report. ([Agent instructions](https://github.com/eoniclabs/MethodCache/blob/main/docs/ai/methodcache.md#feedback)) --- # Generated decorators Put cache attributes on interface methods. The generator builds a decorator around the registered implementation and routes cached calls through MethodCache. Your implementation stays ordinary application code. The generator supports synchronous result methods, `Task` and `ValueTask`, overloaded methods, generic interfaces and generic methods, including interfaces nested in generic containing types. Constraints on both the containing type and the interface, including `unmanaged` and base class constraints, are preserved, and so are `scoped` parameters on forwarded members. Each overload has its own [method id](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson) and its own cache entries. Public interface members are forwarded to the implementation: uncached methods, properties, indexers and events. Non-public and sealed default interface methods stay on the interface with their own bodies; the decorator doesn't implement them, so `[Cache]` or `[CacheInvalidate]` on one (or on a `static` member) is warning [MC0018](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0018). An interface with non-public abstract members is rejected with [MC0014](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0014), because the decorator can't call those members on the implementation. Keywords and unusual names are escaped, and your own types named like framework types (such as `Task` or `List`) don't clash with the generated code. You don't need to rename anything. Long namespace and type names also work with `EmitCompilerGeneratedFiles`: the generated files get short, stable names. Unsupported cached method shapes receive a [generator diagnostic](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md), with a code fix to remove the cache attribute where available. Reference returns, ref struct results and pointer/function pointer results are rejected before cached code is emitted. Those methods are forwarded when another method on the interface is cacheable. See [keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md) for argument identity and [configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md) for generated policy identifiers. ## Registration `AddMethodCache()` wraps every registration of a cached interface in its decorator, and keeps the container's ownership as it is: the container disposes the implementations it creates, and leaves instances you registered yourself open. Factory registrations are wrapped the same way ([Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#registering-with-a-factory)). A factory registration for the README's `IUserService`, once `IUserDatabase` is registered: ```cs builder.Services.AddScoped(sp => new UserService(sp.GetRequiredService())); builder.Services.AddMethodCache(); ``` `AddMethodCache` decorates the services you registered before it. A service you didn't register is registered only with `AutoRegister(lifetime)`. The rules for keyed, generic, factory and several registrations are in [Registration](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md). ## Synchronous methods A synchronous `[Cache]` method loads synchronously: concurrent callers with the same arguments share one call, and it never blocks on an async load. It uses the memory cache only, also when a distributed cache is configured, so it never waits on the network; use an async method to share results between instances. A synchronous `[CacheInvalidate]` method clears this instance's memory before it returns, and reaches the distributed cache in the background. With your own `ICacheManager`, which has only async operations, synchronous methods aren't cached and a warning is logged once per method. ## Language versions C# 12 and newer are supported with the .NET 10 SDK. With C# 13 or newer, generated decorators keep `allows ref struct` constraints on generic methods; a type parameter that may be a ref struct, used as an argument or result, is [MC0009](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0009). --- # Cache keys You never write keys for `[Cache]` methods. The generated decorator builds each key from the interface, the method and the arguments, so two calls share an entry exactly when they call the same method with equal arguments. Chapter 10 of the [console demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.Demo) includes the tenant ID in both the key and the invalidation tag, keeping the same product ID separate for two tenants. Derive that tenant from an authorized identity in an application; cache-key separation does not authorize access. ```cs public sealed record UserQuery(string Name, int Page); public interface IUserService { [Cache] Task GetAsync(int id); // [MyApp]MyApp.IUserService.GetAsync:42 [Cache] Task> SearchAsync(UserQuery query); // [MyApp]MyApp.IUserService.SearchAsync:(alice:2) [Cache] Task> ByIdsAsync(int[] ids); // [MyApp]MyApp.IUserService.ByIdsAsync:[3:1:2:3] [Cache] Task CountAsync(Dictionary filters); // [MyApp]MyApp.IUserService.CountAsync:{hash} (hashed) } ``` Examples below assume the service assembly is named `MyApp`. Its simple name prefixes every key as `[MyApp]`; assembly versions are excluded, so redeploying a new version preserves key identity. Closed generic argument types also include their assembly identity. Assemblies with the same namespace/type names therefore keep separate entries. Assembly-name characters outside letters, digits, `.`, `_` and `-` are escaped as `%XXXX` UTF-16 code units. Use `IMethodCacheKeys` to get the exact key of a call ([Building a key yourself](#building-a-key-yourself)); the admin method list shows the method ids configuration uses. ## How arguments become keys - **Simple values** (strings, numbers, `bool`, `Guid`, dates, enums) are written as they are: `GetAsync:42`. - **Records, classes and structs** whose public properties and fields are simple values are written field by field: `SearchAsync:(alice:2)`. Two records with equal values give the same key. - **Types that implement `ICacheKeyProvider`** contribute their `CacheKeyPart`. - **Arrays and collections** of those values are written with their count and then each element in order: `ByIdsAsync:[3:1:2:3]`. Records and classes inside a collection must be sealed, since an unsealed element type could hold a subclass with more members. A dictionary counts when its keys and values are simple values. When a collection's runtime type differs from its declared type (an array or a list passed as `IEnumerable`), the key includes that type, so an array and a list with the same elements stay two entries. Unknown collection subclasses passed through a base class or interface use the key generator so their own runtime state is preserved. - **Sets and dictionaries** (`HashSet`, `ISet`, `IReadOnlySet`, `Dictionary` and the other dictionaries) have no order of their own, so their elements are written sorted, wherever they appear in an argument: two equal sets get one key, also on two servers that enumerate them differently. They are sorted by their written form, a dictionary by its keys' and then its values', so elements and keys of any type sort, also types that can't be compared. A list or an array keeps its order, because `[1, 2]` and `[2, 1]` are two different lists. When the order of your ids doesn't matter, pass them as a set, such as `IReadOnlySet`, or sort them before the call. - **Collection subclasses with public state**, such as a list with a tenant or scope property, use the key generator. Their keys include both that public state and the elements, including when the collection is behind a base-class property. This applies to the internal fallback generator. - **Everything else**, such as an interface or `object` argument or a collection of collections, goes through the key generator. The internal default generator hashes the arguments into a key such as `CountAsync:fc08ab0d…`. A hashed key is built from every public property and field, so it tells values apart as exactly as the readable form; `IMethodCacheKeys.For` shows the key of a call ([Building a key yourself](#building-a-key-yourself)). - **Framework types** are written by their value wherever they appear, not by their public properties; see [Framework types](#framework-types). Other framework types are a build error. - **`nint` and `nuint`** also go through the key generator, as the 64-bit number they hold, so a value gets the same key in 32-bit and 64-bit processes. Their type is kept: `(nint)1`, `1` and `1L` are three keys, also inside an `object[]` or an `object` property. - **Values inside hashed arguments keep their runtime type.** Where a value's type differs from the type it is declared as (an element of `object[]` or `List`, an `object` property, a property typed as a base class or interface), the key records the value's version-independent assembly/type identity and all of its members: `new object[] { 1 }` and `new object[] { 1L }` get different keys, and so do two `Circle`s behind a `Shape` property that differ only in `Radius`. - A `CancellationToken` parameter is never part of the key. - Keys don't depend on the current culture: `-1`, `1.5` and dates are written the same under every culture. - `0.0` and `-0.0` are two keys in every key form (`1 / x` tells them apart). `NaN` and the infinities work anywhere, also inside a hashed argument, such as `double.PositiveInfinity` as a "no limit" value in a filter record. The generator writes the key code when you build. Only the values the list above sends to the key generator are read when the call runs, from the public properties and fields of their actual type. A type of your own whose public properties are simple values never goes there. Information [MC0037](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0037) marks each `[Cache]` method whose key is written when the call runs, in the editor. To see which form a call gets, look at its key with `IMethodCacheKeys.For`. On .NET 10 the decorator writes simple keys into a stack buffer and looks them up without allocating. ## Types whose state is private A type with only private state, including private fields inherited from a base class, would give every value the same key, so the key generators refuse it with an `InvalidOperationException` instead of returning wrong results, and build error [MC0034](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0034) reports it in a `[Cache]` method. This holds wherever the type appears in an argument: as the argument itself, as a property of a record, or as an element of an array, list or dictionary. Implement `ICacheKeyProvider` on it, or give it public properties: ```cs public sealed class TenantId(Guid value) : ICacheKeyProvider { private readonly Guid _value = value; // private state: MethodCache can't see it public string CacheKeyPart => _value.ToString("N"); } ``` ## Framework types Types from .NET itself often keep their value out of their public properties (`BigInteger` has `IsZero` and `Sign`, `IPAddress.ScopeId` throws for IPv4), so writing those would give different values one key. These go through the key generator, which writes their value, in an argument of their own or inside a record, collection or tuple: - `Guid`, `DateTime`, `DateTimeOffset`, `TimeSpan`, `DateOnly`, `TimeOnly` - `Half`, `Int128`, `UInt128`, `BigInteger`, `Complex` - `Uri`, `Version`, `IPAddress` (`IPAddress.Loopback` and `IPAddress.Parse("127.0.0.1")` share a key) - `JsonElement`, as its JSON, so `{"a":1}` and `{ "a": 1 }` share a key - `Index`, `Range`, `Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Plane`, `Matrix3x2`, `Matrix4x4` - ASP.NET Core's `PathString`, `QueryString` and `HostString` - arrays, collections, `Memory`, `Tuple`, `ValueTuple` and `KeyValuePair` of these Any other type from .NET itself, ASP.NET Core or Microsoft.Extensions in a key (one from an assembly named `System.*`, `Microsoft.AspNetCore.*` or `Microsoft.Extensions.*`), such as `StringBuilder` (which can change after the call), `CultureInfo`, `Stream`, `Type` or a delegate, is build error [MC0019](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0019), also as a property of your own record. Pass a value that identifies it, such as `culture.Name`, or wrap it in a type that implements `ICacheKeyProvider`. Other libraries' models, such as an SDK's classes in a `Microsoft.*` namespace, are written by their public properties like your own types. ## Key construction and value serialization Key construction belongs to the runtime. Complex arguments use the internal canonical encoder; custom key parts use `ICacheKeyProvider`. JSON and MessagePack settings select distributed **value** serialization and do not replace the key generator. ```cs builder.Services.AddMethodCache(cache => cache.UseJson()); ``` ## Method scope Generated keys always include the assembly simple name, interface, method, version, closed generic types, the implementation type when an interface has several registrations, and the service key of a keyed registration. An argument cannot replace that scope: `CacheKeyAttribute` and its `UseAsRawKey` flag have been removed. Use `ICacheKeyProvider` to customize one argument's part, or the manual `ICacheManager` API when supplying a complete key. ```cs public interface IDocumentStore { // The document path is an argument; the interface and method remain part of the key. [Cache] Task GetAsync(string key); } ``` ## Building a key yourself To invalidate or inspect one entry, ask `IMethodCacheKeys` for the key of the call. Resolve it from dependency injection; the compiler checks the call, so overloads, versions, generic methods and argument formatting can't be gotten wrong: ```cs var key = keys.For(orders => orders.GetAsync(42)); await cache.InvalidateKeyAsync(key); // "[MyApp]Docs.Invalidation.IOrderService.GetAsync:42" ``` ```cs // A method with a Version: "[MyApp]MyApp.IInvoiceService.GetAsync:v2:42" var versioned = keys.For(invoices => invoices.GetAsync(42)); // An overloaded method: "[MyApp]MyApp.IInvoiceService.FindAsync(string):INV-7" var overload = keys.For(invoices => invoices.FindAsync("INV-7")); ``` `For` runs the call on a stand-in that records the key the decorator would use, under the method's current policy, so it also follows a runtime version change. The method itself never runs. The call must reach exactly one cached method; anything else, such as a method without `[Cache]`, throws an `InvalidOperationException`. For a keyed registration, pass its service key: `keys.For(rates => rates.Get("EUR"), serviceKey: "ecb")`. To work with every entry of one method, ask for its method id instead. It is the id the admin method list shows and appsettings uses, and it covers all arguments, versions, generic arguments and keyed registrations of the method: ```cs // "[MyApp]MyApp.IInvoiceService.FindAsync(string)": Any.Value stands for any argument var methodId = keys.MethodId(invoices => invoices.FindAsync(Any.Value)); var entries = admin.ListEntries(methodId: methodId); ``` ```cs var methodId = keys.MethodId(invoices => invoices.FindAsync(Any.Value)); var result = await admin.InvalidateMethodAsync(methodId); // every result of the method, on every instance ``` `MethodId` reads the method from the call and never creates the service; `Any.Value` stands for any argument. `For` creates the service only to learn its type, when the interface has several registrations and the last is a singleton factory. `CacheEntryInfo.MethodId` tells which method an entry belongs to; it is `null` for entries stored through `ICacheManager` directly. An application `ICacheManager` stores entries under `MethodCacheKeys.StoredKey(key, version)`; see [Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md). ## Secrets in arguments Keys hold the arguments as they are, and keys show up in `ListEntries`, the admin endpoints, your distributed cache and, when you turn it on, traces. A plain string doesn't look secret to MethodCache, yet a URL can carry a SAS token or another secret in its query, and an argument can be a refresh token or a private report link. Pass an identifier instead where you can. Where the secret is what identifies the result, wrap it in a type whose `ICacheKeyProvider` returns a hash: ```cs // A URL with a SAS token in its query: the key holds a hash of the whole URL, never the token public sealed class SignedUrl(Uri value) : ICacheKeyProvider { public Uri Value { get; } = value; public string CacheKeyPart => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(Value.AbsoluteUri))); } public interface IBlobReader { [Cache(Duration = "10m")] Task ReadAsync(SignedUrl url); } ``` - Hash the whole value, token included. A key without the token would hand the cached result to a caller whose token is wrong or has expired. - Each new token is a new entry, so a URL that is signed again for every call is never read from the cache. Cache by what the token grants access to, such as the blob's name, only where the caller is already authorized for it. - SHA-256 of a long random token can't be reversed; a hash of a short or guessable secret, such as a password or a PIN, can be. Don't cache by those. ## Things to know - **Keys contain the arguments.** Don't cache methods that take secrets such as passwords or tokens as arguments; pass an identifier, or a hash ([Secrets in arguments](#secrets-in-arguments)). Hashed keys are not encryption. No argument, whatever characters it contains, can produce another call's key; see [Security](https://github.com/eoniclabs/MethodCache/blob/main/docs/security.md). - **`Version` changes every key** of a method, so values cached by an earlier version are ignored. See [Expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#versions). - **Overloaded methods** have their parameter types in their keys, so overloads never share entries. See [method ids](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson). - **A method name that another interface in the hierarchy also declares** gets the same treatment. Keys start with the decorated interface, so for `ICatalog : ILookup` with `ILookup.Find(int)` and `ICatalog.Find(string)` the keys are `[MyApp]MyApp.ICatalog.Find(int):7` and `[MyApp]MyApp.ICatalog.Find(string):7`. When two base interfaces declare the same signature, the declaring interface is added too: for `IC : IA, IB` that both declare `Get(int)`, the keys are `[MyApp]MyApp.IC.[MyApp]MyApp.IA.Get(int):1` and `[MyApp]MyApp.IC.[MyApp]MyApp.IB.Get(int):1`. Policy ids don't change; each method keeps the id of the interface that declares it. - **Keyed registrations** have their service key after the method name, so `AddKeyedScoped("ecb")` and `AddKeyedScoped("fed")` each cache their own results: `[MyApp]MyApp.IRates.Get@ecb:1` and `[MyApp]MyApp.IRates.Get@fed:1`. Other keys carry their type (`Get@[MyApp]MyApp.Region.Eu`, `Get@Int32(7)`), and a string with a `.`, `(` or `"` in it is written in quotes, so keys of different types never share entries. The service key must be a string, enum, bool, char, integer or `Guid`; `AddMethodCache()` throws for a keyed registration of a cached interface with any other key, and for a `KeyedService.AnyKey` registration. A constructor parameter marked `[ServiceKey]` receives your key, as it does without MethodCache. - **Several registrations of one interface** under the same service key (or under none) with different implementation types each cache their own results. Their keys carry the implementation type before any service key: with `AddSingleton()` and `AddSingleton()` the keys are `[MyApp]MyApp.IRates.Get#[MyApp]MyApp.EcbRates:1` and `[MyApp]MyApp.IRates.Get#[MyApp]MyApp.FedRates:1`. A single registration keeps the plain key. Two registrations the container builds from the same implementation type, such as a library and the application both calling `AddSingleton()`, are interchangeable and share their results. An instance registration can be configured differently, so `AddMethodCache()` fails when one has the same type as another registration under that key; a factory that creates the same type as another registration fails when both have been created. Give each its own service key instead. `keys.For(...)` returns the key of the last registration, the one `GetService()` returns. When that one is a scoped or transient factory, which may create another type in each scope, `For` throws an `InvalidOperationException` instead of guessing: register it with its implementation type, give it a service key of its own, or invalidate by tag. - **All registrations of a method share its method id and its tags.** A `[CacheInvalidate]` tag, on any registration, and `InvalidateMethodAsync` remove the matching entries of all of them. - **Generic methods** carry their closed type arguments after the method name, before any implementation type or service key: `Get<[System.Private.CoreLib]System.Int32>:1`. Overloads that differ only in generic arity stay apart in ids and keys: `Get(int)`, ``Get`1(int)`` and ``Get`2(int)``. `keys.For` writes the type arguments for you, and the method id covers every closed type. - To see the keys your application produces, list them with `ICacheAdministrator.ListEntries()` or the admin endpoints ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). --- # Expiration Each cached method decides how long its entries live. The settings below can be set on `[Cache]`, in startup code, in `appsettings.json` or at runtime ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)). Chapter 7 of the [console demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.Demo) runs absolute expiry, sliding windows and refresh-ahead with an explicitly advanced clock and checked source-call counts. ```cs public interface IReportService { // Gone ten minutes after it was stored [Cache(Duration = "10m")] Task GetAsync(int year); // Kept while it is read at least every five minutes, but never longer than an hour [Cache(Duration = "1h", SlidingExpiration = "5m")] Task GetSessionAsync(string id); // Reloaded in the background when it is read in its last minute, so callers never wait [Cache(Duration = "10m", RefreshAhead = "1m")] Task GetPricesAsync(string region); // Changing the version changes every key, so values cached by the previous version are ignored [Cache(Duration = "1d", Version = 2)] Task GetYearlyAsync(int year); } ``` ## Writing a duration Attributes, `appsettings.json` and runtime configuration read durations the same way: a number and a unit, such as `"10m"` or `"24h"`. | Write | Means | Example | |---|---|---| | a number and `s` | seconds | `"30s"`, `"0.5s"` | | a number and `m` | minutes | `"5m"`, `"1.5m"` | | a number and `h` | hours | `"24h"`, `"1.5h"` | | a number and `d` | days | `"1d"`, `"7d"` | | `"off"` | turned off (`SlidingExpiration`, `RefreshAhead` and `FailSafe` only) | `"off"` | - Units are case-insensitive and the number uses a `.` for decimals, whatever the culture. - Milliseconds are written as seconds (`"0.25s"`). There is no `ms` unit. - A bare number (`"300"`), zero, a negative value, combined units (`"1h30m"`) and a `TimeSpan` (`"00:05:00"`) are errors: at build time in an attribute ([MC0004](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0004), whose code fix rewrites a `TimeSpan` as `"5m"`), and at startup in `appsettings.json`, with the value to write instead. - In code, pass a `TimeSpan`; `TimeSpan.Zero` turns `SlidingExpiration`, `RefreshAhead` or `FailSafe` off. ## Duration `Duration` is how long an entry lives after it was stored. A method without one uses the global default: ```cs builder.Services.AddMethodCache(config => config.Defaults(o => o.WithDuration(TimeSpan.FromMinutes(15)))); ``` Without any default, entries live for five minutes. `Defaults` and groups are for cached methods; a manual call ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md)) has only the options it passes, so without a `Duration` its entry lives five minutes. No entry lives longer than `MethodCacheMemoryOptions.MaxExpiration` (seven days), so a longer `Duration` fails where it is set instead of being cut short: at startup, in a runtime override or in a manual call. For longer entries, raise the limit, up to 365 days, with `mc.Memory(o => o.MaxExpiration = ...)`. With your own `ICacheManager`, its own limits apply. See [Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md). ### How long an entry lives What a cached method or a manual call ends up with, by what it sets. A cached method also takes a `Duration` from `Defaults` or its group when it sets none itself; a manual call takes only its own options. | Sets | Kept in memory | Kept in the distributed cache | |---|---|---| | nothing | 5 minutes | 5 minutes | | `Duration` | the `Duration` | the `Duration`, at most one day | | `DurationFor` | the duration the result gives | that duration, at most one day | | `SlidingExpiration` | while it is read once per window, up to `MaxExpiration` (7 days) | one window from when it was stored | | `Duration` and `SlidingExpiration` | while it is read once per window, up to the `Duration` | one window from when it was stored, or the `Duration` if that is shorter | - No entry lives longer than `MaxExpiration` (7 days, at most 365); a longer `Duration` or sliding window fails where it is set, at startup for a method and at the call for manual caching. - The one-day limit in the distributed cache is `TagRetention` (1 day) less `ClockSkewTolerance` (2 seconds), counted from when the method started loading the value, so that a tag invalidation always outlives the entries it covers. Raise `TagRetention` to share values longer ([Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#options)). The first value of each method, or of each `WithName` name for manual caching, that asks for longer logs a warning that says so. - An instance that reads a value from the distributed cache keeps it no longer than the copy stored there. - `FailSafe` keeps an expired value in memory for its window, to serve when a reload fails, on every instance that has the value, also one that read it from the distributed cache ([Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md)). ## A duration from the result `DurationFor` gives each result its own duration, in place of `Duration`, such as the time left on a token, a shorter time for an empty result, or the time until the next row of a schedule takes effect, as with future-dated prices. Set it in startup code, for one method: ```cs builder.Services.AddMethodCache(mc => { // A token is kept until a minute before it expires; one that expires sooner isn't cached mc.Method((ITokenClient c) => c.GetTokenAsync(Any.Value)) .DurationFor(token => token.ExpiresAt - DateTimeOffset.UtcNow - TimeSpan.FromMinutes(1)); // An empty result is kept for 30 seconds instead of ten minutes mc.Method((ISearch s) => s.FindAsync(Any.Value)) .DurationFor(result => result.Items.Count == 0 ? TimeSpan.FromSeconds(30) : TimeSpan.FromMinutes(10)); // A price is kept until the next one takes effect, so a future-dated price applies on time mc.Method((IPriceSchedule s) => s.GetCurrentAsync(Any.Value)) .DurationFor(price => price.NextChangeAt is { } next ? next - DateTimeOffset.UtcNow : TimeSpan.FromHours(1)); }); ``` - A duration of zero or less doesn't cache the result, and neither does a function that throws. The caller still gets the result, and the next call runs the method again. - A null result reaches the function as null, so a method that returns `Task` needs `price => price is null ? ... : ...`. Null carries no time of its own: when "no row yet" has a known time at which one takes effect, such as a price that starts next week, return a type that can say so, such as `record CurrentPrice(Price? Price, DateTimeOffset? NextChangeAt)`, or give null a fixed duration. With `CacheNullValues = false` a null result isn't cached at all. - It runs once per load and on each value read from the distributed cache, which keeps the value for the time the result gives on every instance. It never runs on a hit in memory. - No jitter is added ([Spreading out expiry](#spreading-out-expiry)), and `MaxExpiration` still caps it. `SlidingExpiration` and `RefreshAhead` count from the duration the result gives, so keep `RefreshAhead` shorter than the shortest one. To slide some results and not others, add [`SlidingFor`](#a-sliding-window-from-the-result). - `WithDuration` and `DurationFor` replace each other in code: whichever is called last wins. A `Duration` for the method in `appsettings.json` or a runtime override replaces `DurationFor`. - A `DurationFor` in startup code replaces the `Duration` of the method's `[Cache]` attribute too, so the attribute's time doesn't cap it: a cap belongs in the function, such as `left < cap ? left : cap`. `GetMethods()` lists a setting one source replaces in another under `ReplacedSources` ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)). - In `Defaults` or a group it fails at startup, since it reads one method's result type. So does a `DurationFor` for a type the method can't return. - With manual caching, pass it in the options: `o => o.DurationFor(token => ...)` ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md)). ## Sliding expiration `SlidingExpiration` keeps an entry while it is read: each read extends its life by the sliding window. It never lives past its `Duration`; without a `Duration`, only `MaxExpiration` limits it. A cached method can get its `Duration` from `Defaults` or a group; a manual call only from its own options, so a manual call with only a sliding window is kept as long as it is read, up to `MaxExpiration`. So the window must be shorter than the `Duration`, or reads never extend anything: `Duration = "5m"` with `SlidingExpiration = "1d"` expires each entry five minutes after it was loaded. On one `[Cache]` that is warning [MC0038](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0038). When the two come from different places, such as `WithSlidingExpiration` on a method and `WithDuration` in `Defaults`, the host logs a warning when it starts that names the method. A method that inherits a sliding window from the defaults, a group or configuration turns it off with `SlidingExpiration = "off"` (`TimeSpan.Zero` in code). Leaving the setting out inherits it. `RefreshAhead` works the same way. With a distributed cache, the copy stored there lives one window from when it was stored, or the `Duration` if that is shorter: reads in one instance's memory don't reach it. An instance that got the value from the distributed cache keeps it no longer than the stored copy, and the next instance that asks for it after that loads it again. The instance that loaded the value keeps extending its own copy while it is read, up to the `Duration`, until another instance loads the value again: a new value replaces the older copies on every instance. So a value that several instances read is loaded about once per window. To share a value for its whole `Duration`, leave the window out. ### Kept as long as it is read For a cache that only slides, such as one that replaces an `IMemoryCache` entry with only `SlidingExpiration`, set the window and no `Duration`: the entry is kept while it is read at least once per window, up to `MaxExpiration`. ```cs public interface ILayouts { // Kept while it is read at least every 30 minutes, up to MaxExpiration (7 days) [Cache(SlidingExpiration = "30m")] Task GetAsync(string name); } ``` - When `Defaults` or the method's group sets a `Duration`, that still ends the entry. `Duration` can't be turned off, so give the method its own `Duration` as long as you accept, such as `Duration = "7d"`. - To keep entries past seven days, raise `MaxExpiration`, up to 365 days: `mc.Memory(o => o.MaxExpiration = TimeSpan.FromDays(30))`. - A manual call does the same with only `o.WithSlidingExpiration(...)`, since it takes no `Duration` from `Defaults`. ### A sliding window from the result `SlidingFor` gives each result its own sliding window, in place of `SlidingExpiration`. Zero turns sliding off for that result, so it lives its duration whether it is read or not. Together with `DurationFor`, a result that loaded can stay while it is read and one that failed can be tried again after a fixed time: ```cs builder.Services.AddMethodCache(mc => // A preview that loaded is kept while it is read at least every 30 minutes, for at most a day. // One that failed is kept for two hours, read or not, and then the page is tried again. mc.Method((ILinkPreviews p) => p.GetAsync(Any.Value)) .DurationFor(preview => preview.Succeeded ? TimeSpan.FromDays(1) : TimeSpan.FromHours(2)) .SlidingFor(preview => preview.Succeeded ? TimeSpan.FromMinutes(30) : TimeSpan.Zero)); ``` - It never keeps a result past its duration, the one `DurationFor` gives or the method's `Duration`. - A function that throws doesn't cache the result. It runs once per load and on each value read from the distributed cache, never on a hit in memory. - `WithSlidingExpiration` and `SlidingFor` replace each other in code: whichever is called last wins. A `SlidingExpiration` for the method in `appsettings.json` or a runtime override replaces `SlidingFor`. - Like `DurationFor`, it is set for one method, in startup code or in the options of a manual call: `o => o.SlidingFor(preview => ...)`. ## Refresh-ahead `RefreshAhead` reloads an entry in the background when it is read within that window before it expires. The caller gets the cached value at once, and the reload replaces it, so a popular entry never makes anyone wait. An entry that isn't read in the window simply expires. With a distributed cache the reload also replaces the stored copy, so other instances read the new value instead of loading it. The window must be shorter than `Duration` and `SlidingExpiration`, or every read would reload the entry: on `[Cache]` (build error [MC0023](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0023)), in code (`Build()` throws an `InvalidOperationException`) and in `appsettings.json` (startup fails) a longer one is rejected. When settings from different places combine into such a window, for example an attribute's `RefreshAhead` with a shorter `Duration` from configuration, the reload starts halfway through the entry's life instead. The reload outlives the request that triggered it. For a service registered as scoped or transient (a repository with a scoped `DbContext`, say), it runs on a new instance from a new DI scope, which is disposed when the reload ends, never on the request's instance, whose scope may already be gone. That instance has none of the request's state: no `HttpContext`, and no values the request set on the instance or in `AsyncLocal`. Each scoped or transient cached service the reload calls gets an instance this way, also from a manual `GetOrCreateAsync` factory, and every scope is disposed when the reload ends; a call the factory leaves running after it returned keeps the instance it was given. Singletons reload on their one instance. A `CancellationToken` parameter of the method still cancels the reload. ## Versions `Version` is part of every key the method produces. Raise it when the shape of the cached result changes, for example after adding a property, so values cached by the previous deployment are never returned. The old entries expire on their own. ## Spreading out expiry Entries created at the same moment, for example right after a deploy, also expire together. `MethodCacheMemoryOptions.JitterMaxDuration` adds a random extra lifetime to each entry to spread them out ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md)). ## Removing entries early > [!TIP] > Expiration is for data that may be a little old. When you know data changed, remove it right away with > [invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md). --- # Invalidation Expiration removes entries eventually; invalidation removes them the moment you know the data changed. ## Tags Give cached methods tags, and list the same tags on the methods that change the data: ```cs public interface IOrderService { [Cache(Duration = "10m", Tags = ["orders", "order:{orderId}"])] Task GetAsync(int orderId); [Cache(Duration = "5m", Tags = ["orders", "customer:{customerId}:orders", "customer:{customerId}"])] Task> ListForCustomerAsync(int customerId); // Removes this order and the customer's list, nothing else [CacheInvalidate(Tags = ["order:{orderId}", "customer:{customerId}:orders", "customer:{customerId}"])] Task CancelAsync(int orderId, int customerId); // Removes every cached order [CacheInvalidate(Tags = ["orders"])] Task ImportAsync(Stream file); } ``` - `[CacheInvalidate]` removes every entry with any of its tags once the method has completed successfully. If it throws, nothing is removed. - A tag can be shared by many methods, so one write clears every cached view of the same data. - `[CacheInvalidate]` without tags removes nothing and is reported as [MC0007](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0007). ## Tag templates `"order:{orderId}"` is filled in from the method's arguments: `GetAsync(42)` is tagged `order:42`, and `CancelAsync(42, 7)` removes `order:42`. The name in braces must be a parameter of the method it is on. The exact spelling is used first; otherwise a single case-insensitive match is used. A name that matches several parameters only by case, such as `{NAME}` for `name` and `Name`, stays literal text and is reported as [MC0017](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0017). An unknown name is reported as [MC0010](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0010), with a code fix that offers the closest parameter. Arguments use canonical key-part formatting: strings escape backslashes and colons, GUIDs use the 32-digit `N` format, and null uses `\0`. Braces in an argument remain literal: an id of `"{org}"` gives the tag `order:{org}` on both the cached call and the invalidation. A template takes a parameter name only. `"{order.Id}"` is not a template and stays literal text, so every call would share one tag; it is reported as [MC0016](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0016). Add the id as a parameter, as `UpdateAsync(int id, Product product)` does in [Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md). Static tags never format method arguments. A template formats only the parameters it references, in the invariant culture; an unrelated argument's `ToString()` is not invoked. Tags set in startup code, `appsettings.json` or runtime overrides can use templates too, with any parameter of the method. They are added to the `[Cache]` attribute's tags, so the attribute's `[CacheInvalidate]` tags keep working; only an explicit `ClearTags()` (or `"ClearTags": true` in `appsettings.json`) replaces them ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)). An override with `o => o.AddTags("incident")` on `GetAsync` above gives its entries the tags `orders`, `order:{orderId}` and `incident`. `[CacheInvalidate]` also works on methods with `ref` or `ref readonly` returns, and on `Task` and `ValueTask` methods with `ref`, `out` or `in` parameters. The tags are filled in after the call returns, and the entries are removed only once the task has completed successfully. ## Tags from the result A template reads the method's arguments. When a tag depends on the result instead, such as the customer of an order that `GetAsync(orderId)` finds by its id, add it with `TagsFor` in startup code: ```cs services.AddMethodCache(mc => { // GetAsync(orderId) finds the order by its id; its entry also gets the tag of the order's customer mc.Method((IOrderService s) => s.GetAsync(Any.Value)) .TagsFor(order => [MethodCacheKeys.Tag($"customer:{order.CustomerId}")]); }); ``` - The tags are added to the method's own, so `CancelAsync(42, 7)` above, which invalidates `customer:7`, now also removes `GetAsync(42)`, and so does `InvalidateTagAsync("customer:7")`. - Build each tag with `MethodCacheKeys.Tag($"...")`, which writes values the way tag templates do, so it matches the tag that is invalidated. - It runs once per load, never on a hit. A function that throws, or gives a null, empty or whitespace tag, doesn't cache the result; the caller still gets it. - The result's tags aren't known while it loads, so a tag invalidated in that time keeps it from being cached, whichever tag it was. The next call loads it again. - For manual caching, pass `o => o.TagsFor(order => [...])` in the options ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#options)). - It is set for one method only: in `Defaults` or a group it fails at startup, and so does a `TagsFor` for a type the method can't return. `ClearTags()` in a higher layer removes it. ## From code `ICacheManager` invalidates by tag or by key: ```cs await cache.InvalidateTagsAsync(["order:42", "customer:7:orders"]); ``` ```cs var key = keys.For(orders => orders.GetAsync(42)); await cache.InvalidateKeyAsync(key); // "[MyApp]Docs.Invalidation.IOrderService.GetAsync:42" ``` ```cs await cache.InvalidateTagAsync("customer:7"); // add this tag to every customer entry ``` - `IMethodCacheKeys.For` returns the key the generated decorator uses for that call, including overloads, versions, generic methods and keyed registrations; resolve `IMethodCacheKeys` from dependency injection. See [Building a key yourself](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#building-a-key-yourself). - Invalidation matches exact tags and keys; there are no wildcard patterns. Attach a common tag to all entries in a group instead. - To remove every entry of one method, pass its id to `ICacheAdministrator.InvalidateMethodAsync`; get the id from `IMethodCacheKeys.MethodId` ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#building-a-key-yourself)). - The admin endpoints and `ICacheAdministrator` also invalidate by tag and by method ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). ## When the write happens somewhere else `[CacheInvalidate]` covers writes that go through the cached interface. With Entity Framework Core, [`MethodCache.EntityFrameworkCore`](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md) invalidates after every commit that changes a mapped entity, wherever the write happens. When the data changes somewhere else, such as an endpoint or a command that writes to the database directly, or a transaction that commits after the `[CacheInvalidate]` method has returned, invalidate after the write or the commit. Get the tag from `IMethodCacheKeys.Tag`, so you never build it by hand: ```cs public interface IPriceSource { const string RateTag = "price:{provider}:{model}"; [Cache(Duration = "5m", Tags = [RateTag])] Task GetRateAsync(string provider, string model); } ``` ```cs public static async Task UpdateRateAsync(string provider, string model, decimal rate, PriceDb db, ICacheManager cache, IMethodCacheKeys keys) { await db.SaveRateAsync(provider, model, rate); // written directly, not through IPriceSource // The tag GetRateAsync(provider, model) stored its result under, formatted exactly as the decorator does await cache.InvalidateTagAsync( keys.Tag(s => s.GetRateAsync(provider, model), IPriceSource.RateTag)); } ``` - `keys.Tag(call, template)` fills in the template from the call's arguments exactly as the decorator does. The method never runs. The template must be one of the method's tags, or it throws and lists them, so a template that drifts away from the method fails in your tests instead of silently matching nothing. A `const` on the interface lets the attribute and the call share it. - For one entry, `cache.InvalidateKeyAsync(keys.For(s => s.GetRateAsync(provider, model)))` removes only that call's result. - Don't build the tag with plain string interpolation. Tags write arguments in one canonical way (`:` and `\` escaped in strings, a `Guid` without hyphens, an enum as its number), so `$"price:{provider}:{model}"` can match nothing for a model such as `gemma3:4b`, and the old value stays until it expires. The analyzer reports such a tag as [MC0024](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0024). Wrap it in `MethodCacheKeys.Tag` instead, which writes every value the canonical way: `MethodCacheKeys.Tag($"price:{provider}:{model}")`. A nullable value such as an `int?` is written as its value, or as null is in tag templates. A value of a type tags can't hold, or with a format such as `{price:F2}`, doesn't compile. `MethodCacheKeys.Part(value)` writes one value the same way, nullable values included. - A `[CacheInvalidate]` method with an empty body, such as `Task PriceChangedAsync(string provider, string model)`, works too: call it after the write. ### In another application When another application or process invalidates a tag, such as a worker that imports the data, list the tag in `InvalidatedElsewhere`. Caching works the same; analyzer [MC0028](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0028) counts the tag as invalidated, on every method that has it. `TagCoverage` ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-tag-has-an-invalidation)) checks the mark: it counts the tag only when a project the test project references, such as the worker, invalidates it: ```cs public interface IRecipeCatalog { // The import worker invalidates "recipes" after each import; this application invalidates "recipe:{id}" [Cache(Duration = "1h", Tags = ["recipes", "recipe:{id}"], InvalidatedElsewhere = ["recipes"])] Task GetAsync(int id); [CacheInvalidate(Tags = ["recipe:{id}"])] Task RenameAsync(int id, string name); } ``` Write each tag as it is written in `Tags`; one that matches none of them is warning [MC0029](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0029). The other application's invalidation reaches this one's memory cache only through a shared distributed cache ([With several instances](#with-several-instances)). ### Cleared by hand Some data has no write in the application to invalidate after: a catalog loaded once a year, or settings an operator changes in another system. When an operator clears the tag by hand instead, such as with `POST invalidate` of `MapMethodCacheAdmin` ([Admin endpoints](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#admin-endpoints)), and the entries otherwise expire, list the tag in `InvalidatedManually`: ```cs public interface IFoodCatalog { // The catalog changes a few times a year, and an operator clears "food-catalog" after each update [Cache(Duration = "1d", Tags = ["food-catalog"], InvalidatedManually = ["food-catalog"])] Task> SearchAsync(string text); } ``` Caching works the same. Analyzer [MC0028](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0028) and `TagCoverage` ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-tag-has-an-invalidation)) count the tag as invalidated, on every method that has it, without looking for an invalidation; unlike `InvalidatedElsewhere`, there is nothing in another project to check. Write each tag as it is written in `Tags`; one that matches none of them is warning [MC0029](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0029). ### After a database transaction With Entity Framework Core, [`MethodCache.EntityFrameworkCore`](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md) does this for you. With another way to write, such as Dapper or ADO.NET, invalidate after the transaction commits, not before and not inside it. An invalidation before the commit lets a reader cache the old data again in between, and a rollback after it has nothing to undo. Pass `CancellationToken.None`: once the data has changed, the invalidation must happen even if the caller has gone. ```cs public static async Task RenameAsync(int id, string name, DbConnection connection, ICacheManager cache, IMethodCacheKeys keys, CancellationToken ct) { await using (var transaction = await connection.BeginTransactionAsync(ct)) { await using var command = connection.CreateCommand(); command.Transaction = transaction; command.CommandText = "update products set name = @name where id = @id"; AddParameter(command, "@name", name); AddParameter(command, "@id", id); await command.ExecuteNonQueryAsync(ct); await transaction.CommitAsync(ct); } // After the commit, and not cancelled with the request: the data has changed either way await cache.InvalidateTagAsync( keys.Tag(r => r.GetNameAsync(id), IProductReads.ProductTag), CancellationToken.None); } ``` To make a forgotten invalidation unlikely, give every write path one place to go. Put the writes behind an interface with `[CacheInvalidate]` methods that commit their own transaction: the attribute runs after the method returns, so after the commit, and only when it succeeded. Where writes must stay inline, wrap them in a helper that commits and then invalidates, and test each write path with a cached read before and after it ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#when-a-test-writes-to-the-database-directly)). ## With several instances With [Redis, SQL Server or PostgreSQL](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md), invalidating a tag or key removes it from the distributed cache and sends every other instance a message to drop its in-memory copy. You don't need to do anything else, but the other instances drop their copies when the message arrives, not when the call returns: until then they can serve the copy they hold. How each provider catches up after a lost connection is in [What other instances see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#what-other-instances-see). The `InvalidationResult` that `InvalidateTagAsync` and `InvalidateKeyAsync` return counts how far the invalidation got, per tag or key: | Count | Means | |---|---| | `Local` | Removed from this instance's memory | | `Distributed` | Confirmed by the distributed cache: instances without a copy in memory, and instances that start later, read the new value | | `Queued` | Not confirmed by the distributed cache yet. It is retried every `CircuitBreakerDuration`, and until then other instances can serve the old value | | `Published` | The message to the other instances was sent. Nothing confirms that each one received it | | `PublicationQueued` | Confirmed by the distributed cache, but the message wasn't sent yet; it is retried | Without a distributed cache only `Local` counts. --- # Entity Framework Core The `MethodCache.EntityFrameworkCore` package invalidates cached results when Entity Framework Core commits a change. Map an entity type to the tags of the methods that read it, and every save that adds, changes or deletes one of its rows invalidates those tags, after the data is committed. Writes don't need invalidation code of their own, also when they happen inline in an endpoint. Install it at the same version as `MethodCache`. ## Setting it up The cached reads are ordinary `[Cache]` methods with tags: ```cs public interface IProductReads { [Cache(Duration = "10m", Tags = ["product:{id}"])] Task GetAsync(int id); [Cache(Duration = "10m", Tags = ["category:{categoryId}"])] Task> ListAsync(int categoryId); [Cache(Duration = "1h", Tags = ["top-sellers"])] Task> TopSellersAsync(); } ``` Connect the context in `AddMethodCache`, and say which tags a change to each entity type invalidates: ```cs builder.Services.AddDbContext(o => o.UseSqlite(connectionString)); builder.Services.AddScoped(); builder.Services.AddMethodCache(mc => mc.UseEntityFrameworkCore(ef => ef .Entity("product:{Id}", "category:{CategoryId}") .Entity("top-sellers"))); ``` `AddDbContext`, `AddDbContextPool` and `AddDbContextFactory` stay as they are, before or after `AddMethodCache`. A save is now all a write needs: ```cs public static async Task ChangePriceAsync(int id, decimal price, ShopDb db, CancellationToken ct) { var product = await db.Products.SingleAsync(p => p.Id == id, ct); product.Price = price; // Invalidates product:{id} and category:{CategoryId} once the save succeeded await db.SaveChangesAsync(ct); } ``` ## Mapping entities to tags `Entity(tags)` takes the tags to invalidate when a row of that type is added, changed or deleted. - **A name in braces is a property of the entity**, also a shadow property such as a foreign key that has no property in the class. The exact spelling is used first; otherwise the only property that matches without regard to case. - **Values are written as cached methods write arguments**: a `Guid` as 32 digits without hyphens, an enum as its number, `:` and `\` escaped in strings. So `"product:{Id}"` on the entity matches `"product:{id}"` on a method, and `"sku:{Sku}"` matches `"sku:{sku}"` for a SKU such as `ham:mer`. - **A changed row invalidates the tags of its old and its new values.** Moving a product to another category invalidates `category:1` and `category:2`. The new values include columns the database computes, such as a computed column, which EF Core reads back after the save. - **A row you change without loading it is read once before it is saved**, for its stored values. That covers `Update(product)` with values from a request, `Attach` with a few properties set, and `Remove(new Product { Id = id })`: the category it had in the database is invalidated, not the empty value of a new object. A row the context loaded is never read again. With row-level security, see [Saves of rows the context didn't load](#saves-of-rows-the-context-didnt-load). - **A new row is tagged with its saved values**, so a key the database generates is the real one, not a temporary value. A cached "not found" for that id is invalidated too. - **A derived type** invalidates the tags of every mapped type it derives from. - **A type mapped with `OwnsOne` or `OwnsMany`**, such as an address stored in the customer's row, invalidates the tags of its owner. **A many-to-many link** added or removed invalidates the tags of both sides that are mapped. A side the context hasn't loaded is read once before the save when its tags use more than its key, so a link added with only the two ids still invalidates `category:{CategoryId}` of the product. - **A tag without braces**, such as `"top-sellers"`, is invalidated by any change to that entity type. - **Everything the save writes counts**: rows another `SaveChanges` interceptor changes, adds or deletes, and rows EF Core deletes by cascade during the save. The tags are checked against the model when the host starts. A name that is not a property, or a type the context doesn't map, stops the host with a message that lists the entity's properties. When the context can't be created at startup, because it needs something only a request has, the first save checks them instead. Map each entity to the tags of every cached method whose result reads it. A method that reads several tables needs a tag that each of their entities invalidates, such as `top-sellers` above for order lines. ### Rows the database deletes with a row Rows the database changes by itself aren't seen: rows that `ON DELETE CASCADE` removes when the context hadn't loaded them, and rows a trigger writes. Give the cached methods that read them a tag that the parent entity invalidates too, such as `category:{CategoryId}` on products for a method that lists a category with its products. When the parent is saved often for reasons that change no cached result, such as a customer whose last sign-in is stored, map those tags with `WhenDeleted`. They are invalidated only when a row of that type is deleted, with the deleted row's values in the braces: ```cs builder.Services.AddMethodCache(mc => mc.UseEntityFrameworkCore(ef => ef .Entity("product:{Id}", "category:{CategoryId}") .Entity("top-sellers") // Every sign-in saves the customer, and changes no cached result. A deleted customer does: the // database deletes their order lines, which the context never loaded .Entity(customer => customer.WhenDeleted("top-sellers")))); ``` `Tags(...)` in the same call maps tags for any change, the same as `Entity("...")`, so `customer => customer.Tags("customer:{Id}").WhenDeleted("top-sellers")` maps both. A type mapped only with `WhenDeleted` doesn't invalidate anything for an added or changed row. A change to an `OwnsOne` or `OwnsMany` type or to a many-to-many link doesn't reach those tags either, since it doesn't delete the row they belong to. ## When the tags are invalidated Never before the data is committed: a reader in between would cache the old rows again. | Situation | Invalidated | |---|---| | `SaveChanges` without a transaction | After it succeeds | | Inside `BeginTransaction` | After `Commit`. `Rollback` drops them | | Inside a `TransactionScope` | When the scope ends, also when it aborts: a connection outside the scope may have saved | | A transaction passed in with `UseTransaction` | When a context connected to MethodCache commits it, or else once it is over: when its connection closes, or when the context is disposed after the commit | | `SaveChanges` throws | Nothing, when nothing reached the database. When part of it may have, such as a commit that failed on the way back, its tags are invalidated | | An execution strategy retries | A failed attempt invalidates nothing early; the retry collects its tags again | ```cs public static async Task MoveAsync(int id, int categoryId, ShopDb db, CancellationToken ct) { await using var transaction = await db.Database.BeginTransactionAsync(ct); var product = await db.Products.SingleAsync(p => p.Id == id, ct); product.CategoryId = categoryId; await db.SaveChangesAsync(ct); // nothing invalidated yet: the transaction is open await transaction.CommitAsync(ct); // product:{id}, the old and the new category:{CategoryId} } ``` - Synchronous `SaveChanges()` and `Commit()` invalidate the memory cache before they return. Redis, SQL Server or PostgreSQL confirm in the background, so the call never waits on the network. - An invalidation after a commit never throws: the data is saved, and an exception would make the caller think the save failed. If the distributed cache is down, the invalidation is retried until it is back, and logged as a warning. The warning names the context, the number of tags and the error's type, not the tags or the error's message, which can hold user ids or connection details. - With several instances, the other instances drop their copies as with any invalidation ([With several instances](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#with-several-instances)). - Commit through EF Core: `Commit()` on what `BeginTransaction` returned, or `Database.CommitTransaction()`. A transaction that ends some other way, such as a commit on its `DbTransaction`, has its tags invalidated at the context's next save or when the context is disposed. - Where the outcome is unknown, the tags are invalidated: an extra invalidation costs a cache miss, a missing one serves old data until it expires. ## Writes the change tracker doesn't see `ExecuteUpdate`, `ExecuteDelete` and `Database.ExecuteSql…` change rows without loading them, so no entity tags are known for them. Warning [MC0027](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0027) reports such a write when the method around it doesn't invalidate anything: - `ExecuteUpdate` and `ExecuteDelete` on a type the project maps with `Entity(...)`, or on a type it derives from or that derives from it. A type mapped only with `WhenDeleted` is reported for `ExecuteDelete` alone. Writes to tables that nothing caches, such as refresh tokens, aren't reported. A project that references the one with the mapping, such as its tests, uses that mapping too. In a project that sees no mapping, such as a data layer that the startup project references, every `ExecuteUpdate` and `ExecuteDelete` is reported. - `Database.ExecuteSql…` when the SQL names the table of a mapped type, runs code (`call`, `exec`, `do`), or can't be read, such as SQL in a variable or a string interpolated into `ExecuteSqlRaw`. A table is known by its class name, `DbSet` name, `ToTable` or `[Table]` name, in any case, so `ai_model_prices` matches `AiModelPrice`. Statements that only `select`, such as an advisory lock, or `set` a session setting never count. In a project that sees no mapping, all other raw SQL is reported. - A generic helper, such as `PurgeAsync()`, since any type could reach it ([Generic helpers](#generic-helpers) shows what to do). A call to `InvalidateAfterCommit`, `ICacheManager.InvalidateTagsAsync`, a `[CacheInvalidate]` method or a method of your own marked `[InvalidatesCache]` counts as the invalidation: ```cs public static class CacheChanges { // Invalidates through the app's own plumbing: MC0027 counts a call to it [InvalidatesCache] public static void Changed(this HttpContext http, string tag) => ...; } ``` A method marked `[InvalidatesCache]` isn't reported for the writes inside it either. Inside a transaction, queue the tags with `InvalidateAfterCommit`. They are invalidated with the entity tags after the commit, and dropped on a rollback: ```cs public static async Task RecalculateAsync(ShopDb db, IMethodCacheKeys keys, int categoryId, CancellationToken ct) { await using var transaction = await db.Database.BeginTransactionAsync(ct); await db.Products .Where(p => p.CategoryId == categoryId) .ExecuteUpdateAsync(s => s.SetProperty(p => p.Price, p => p.Price * 1.1m), ct); // ExecuteUpdateAsync goes past the change tracker: name the tags it changes db.InvalidateAfterCommit(keys.Tag(r => r.ListAsync(categoryId), "category:{categoryId}")); await transaction.CommitAsync(ct); } ``` Without a transaction, the write is committed when it returns. Invalidate at once: ```cs public static async Task DeleteCategoryAsync(ShopDb db, ICacheManager cache, IMethodCacheKeys keys, int categoryId, CancellationToken ct) { // Without a transaction the delete is committed when it returns: invalidate at once await db.Products.Where(p => p.CategoryId == categoryId).ExecuteDeleteAsync(ct); await cache.InvalidateTagAsync( keys.Tag(r => r.ListAsync(categoryId), "category:{categoryId}"), CancellationToken.None); } ``` `InvalidateAfterCommit` takes tags exactly as cached methods write them. Build them with `IMethodCacheKeys.Tag`, or with `MethodCacheKeys.Tag($"order:{id}")`; [MC0024](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0024) reports a hand-built tag that formats a value differently. Outside a transaction, queued tags wait for the next commit, a successful `SaveChanges` or a transaction's `Commit`, and are invalidated when the context is disposed if none comes. A rollback doesn't drop them, since they don't belong to it. Writes outside EF Core, such as Dapper or another service, are covered in [When the write happens somewhere else](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#when-the-write-happens-somewhere-else). ### Generic helpers A helper that runs `ExecuteUpdate` or `ExecuteDelete` for any entity type can't know which cached results its rows feed, so MC0027 reports it. Have it take the tags of what it changes from its caller, invalidate them after the write, and mark it `[InvalidatesCache]`. MC0027 then counts each call to it as the invalidation, and doesn't report the helper: ```cs public static class Bulk { // Deletes rows of any type past the change tracker, then invalidates the tags its caller names. // [InvalidatesCache] makes each call count as the invalidation, so MC0027 doesn't report the helper [InvalidatesCache] public static async Task DeleteWhereAsync(ShopDb db, ICacheManager cache, Expression> where, string[] tags, CancellationToken ct) where TEntity : class { var deleted = await db.Set().Where(where).ExecuteDeleteAsync(ct); await cache.InvalidateTagsAsync(tags, CancellationToken.None); return deleted; } } ``` The caller names the tags, built from the cached method they belong to: ```cs await Bulk.DeleteWhereAsync(db, cache, p => p.CategoryId == categoryId, [keys.Tag(r => r.ListAsync(categoryId), "category:{categoryId}")], ct); ``` A helper that only ever gets types nothing caches, such as audit or log rows, turns the warning off inside it with `#pragma warning disable MC0027` and a comment that says why ([MC0027](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0027)). ## Row-level security When the database filters rows by a setting on the connection, such as the signed-in user's id, cached reads and saves of rows the context didn't load work as follows. ### Cached reads A cached result is shared by every caller with the same arguments, and a refresh-ahead or fail-safe load runs after the request, without its user. So a cached read can't use a context that is set up for the signed-in user. Give the cached reads a context of their own, and pass what the policies filter on as an argument: ```cs // For cached reads: a context of its own, which nothing sets up from the request public sealed class ReadDb(DbContextOptions options) : DbContext(options) { public DbSet Recipes => Set(); } public interface IRecipeReads { [Cache(Duration = "10m", Tags = ["recipes:{householdId}"])] Task> ListAsync(Guid householdId); } public sealed class RecipeReads(IDbContextFactory factory) : IRecipeReads { public async Task> ListAsync(Guid householdId) { // Its own context and connection for each call, also for a refresh that runs after the request await using var db = await factory.CreateDbContextAsync(); // The policies read the household from the argument, which is part of the key, not from the request await db.Database.OpenConnectionAsync(); await db.Database.ExecuteSqlAsync($"select set_config('app.household', {householdId.ToString()}, false)"); return await db.Recipes.Where(r => r.HouseholdId == householdId) .Select(r => new RecipeDto(r.Id, r.Title)).ToListAsync(); } } ``` Register it next to the app's context: ```cs // Requests read and write through the app's context, set up for the signed-in user builder.Services.AddDbContext(o => o.UseNpgsql(connectionString).AddInterceptors(signedIn)); // Cached reads use their own builder.Services.AddDbContextFactory(o => o.UseNpgsql(connectionString)); builder.Services.AddScoped(); // The writes' context is the one connected to MethodCache builder.Services.AddMethodCache(mc => mc.UseEntityFrameworkCore(ef => ef .Entity("recipes:{HouseholdId}"))); ``` - The household is part of the key: each household has its own entry, and a refresh reads the same rows. - The endpoint checks that the signed-in user belongs to the household before it calls `ListAsync`, as it checks any id it takes from a request. For the cached call, the policy no longer does. - For data every user may read, such as a shared catalog, the read context can connect as a database user that the policies let read all of it, and the method needs no argument for it. - Warning [MC0026](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0026) reports a cached implementation that takes the request's state, or takes a class whose constructor does, such as a context that takes `IHttpContextAccessor`. It doesn't see a setting that an interceptor makes on the connection. ### Saves of rows the context didn't load A row changed or deleted without loading it is read for its stored values before the save, and so is the side of a many-to-many link the context hasn't loaded ([Mapping entities to tags](#mapping-entities-to-tags)). The read runs on the save's connection: - **EF Core query filters don't apply to it**, so a row that a tenant filter hides from queries is still read. - **Row-level security does.** When a policy hides the row from the user, the read finds nothing, and the values your code set are used for the old tags. PostgreSQL and SQL Server hide that row from EF Core's `UPDATE` and `DELETE` too, also when a PostgreSQL policy lets the user change rows: the save changes nothing and throws `DbUpdateConcurrencyException`. So a save never changes a row whose old tags weren't read. - On a database that lets a user change a row they can't read, load the row before you change it, or queue the old tags yourself with `InvalidateAfterCommit`. ## Document databases Azure Cosmos DB and MongoDB have EF Core providers. Entity tags and `InvalidateAfterCommit` work with them, since both act on `SaveChanges`. Cosmos DB has no transactions you begin yourself in EF Core, so each `SaveChanges` is the commit. A MongoDB transaction you begin with `BeginTransaction` isn't seen by the package; its tags are invalidated at the context's next save after the commit, or when the context is disposed. With these providers, a context can't tell which rows it loaded until its first save. A changed row it loaded before then is read once when it is saved, as a row changed without loading is, if its tags use more than its key. ## Testing Use SQLite in memory, or your real database, with the same registration. A test that writes to the database without EF Core needs its own invalidation ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#when-a-test-writes-to-the-database-directly)). With `MethodCache.Testing`, `recorder.Loads` proves a read is cached and `recorder.InvalidatedTags` lists the tags a save invalidated ([Counting loads and invalidations](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#counting-loads-and-invalidations)). `EntityTagMapping` lists what the mapping holds. `TagCoverage` counts the mapping's tags as invalidated, so a test can check that every tag of a cached method is mapped or has another invalidation: ```cs var mapping = provider.GetRequiredService>(); // [(Product, ["product:{Id}", "category:{CategoryId}"], []), (OrderLine, ["top-sellers"], [])] var entities = mapping.Entities; // TagCoverage counts the mapping, so every tag of a cached method is mapped or has another invalidation Assert.Empty(TagCoverage.Uninvalidated(provider)); ``` --- # Fail-safe Fail-safe keeps an expired value for a while and returns it when calling the method again fails, so a database or API outage shows slightly old data instead of errors. It is off by default. Chapter 8 of the [console demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.Demo) shows a failing API, retry suppression, recovery and a slow response that finishes after the caller receives its fallback. A fake clock controls the expiry, retry and timeout windows; the same scenario runs in the docs tests. ## Turning it on For every cached method at once: ```cs builder.Services.AddMethodCache(config => config.Defaults(o => o .WithFailSafe(TimeSpan.FromHours(1)) // how long an expired value is kept as a fallback .WithFailSafeTimeout(TimeSpan.FromMilliseconds(200)) // optional: don't wait longer than this when a fallback exists .WithFailSafeRetryAfter(TimeSpan.FromSeconds(30)))); // optional: reuse the fallback this long before trying again ``` or in `appsettings.json`: ```json { "MethodCache": { "FailSafe": { "Duration": "1h", "Timeout": "0.2s", "RetryAfter": "30s" } } } ``` ## What happens - **When the method throws**, the caller gets the expired value if it is younger than the fail-safe duration. That value is then reused for the retry delay (`RetryAfter`, default 30 seconds) before the method is called again, so a failing dependency isn't hammered; no [refresh-ahead](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#refresh-ahead) reload starts during that time either. - **When the method is slow** and a `Timeout` is set, the caller gets the expired value after it and the call finishes in the background; its result replaces the old value. Without an expired value the caller waits as usual. Because the call may outlive the request, a scoped or transient service makes it on a new instance from a new DI scope, disposed when the call ends, whenever a fallback exists and a `Timeout` is set (the instance has none of the request's own state, such as values set on the instance). The caller's `HttpContext` and `AsyncLocal` values still flow to it, as it starts on the caller's call. Singletons use their one instance. - A caller's own cancellation is never treated as a failure, so it doesn't trigger fail-safe. - A value that was invalidated (its key, a tag or a clear) or replaced is never a fallback, also when that happened while the reload ran: callers then wait for the reload, or get its exception. - Without an expired value, the exception reaches the caller as usual. - `GetOrCreateManyAsync` works the same way for each key: when the batch factory throws, each key gets its own fallback, and the exception is thrown only when a key has none. A key the factory leaves out also gets its fallback, and is left out of the result when it has none. ## Per method A method or group can change any of it, and its own setting wins over the central one. `[Cache]` takes the same three settings as `FailSafe`, `FailSafeTimeout` and `FailSafeRetryAfter`: ```cs public interface IAccountService { [Cache(Duration = "5m", FailSafe = "1h", FailSafeTimeout = "0.2s")] Task GetRatesAsync(); [Cache(FailSafe = "off")] // a balance must never be old, so an error is better Task GetBalanceAsync(int accountId); } ``` In code, use the builder methods with the same names: `WithFailSafe`, `WithFailSafeTimeout` and `WithFailSafeRetryAfter`, for example `Configure(o => o.WithFailSafeTimeout(TimeSpan.FromMilliseconds(100)))` to change only the timeout. `o.WithFailSafe(TimeSpan.Zero)` turns fail-safe off. In `appsettings.json`, a method takes `FailSafe` (a time span or `"off"`), `FailSafeTimeout` and `FailSafeRetryAfter`. ## Limits > [!NOTE] > The fallback lives in each instance's memory: an instance has one for each value it loaded or read from the > distributed cache, for the fail-safe window after the value expired. Right after a restart there is none until the > instance has had the value once. Cancelling a call stops its wait for the distributed cache, a slow method or a fail-safe value. Work that other callers share may finish for them, and a cancelled call doesn't count as a failure. --- # Conditional caching Sometimes a result should be returned but not remembered: an empty search, a product that doesn't exist yet, a response that says "try again later". Chapter 9 of the [console demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.Demo) skips missing products and proves that a newly created product is visible on the next lookup, while existing products are cached. ## CacheWhen `CacheWhen` stores a result only when the predicate returns true: ```cs builder.Services.AddMethodCache(config => { // Don't remember empty search results: the next search asks the database again config.Method((IProductService s) => s.SearchAsync(Any.Value)) .CacheWhen(results => results.Count > 0); // A product that doesn't exist yet may be created any moment config.Method((IProductService s) => s.FindAsync(Any.Value)) .CacheWhen(product => product is not null); }); ``` - A rejected result is still returned to the caller, and the next call runs the method again. - The entry it would have replaced, including a fail-safe value, stays. - The predicate runs once per load, and on each value read from the distributed cache: a value it rejects there is skipped and the method runs. It never runs on a hit in memory. If it throws, the result is returned and not stored. - `config.Method(...).CacheWhen` gets the method's result type. A `CacheWhen` set elsewhere for a type the method can't return, such as `CacheWhen` on a method that returns `int`, fails where it is set instead of silently caching nothing: in code with an `InvalidOperationException` at startup, and in a runtime override with an `ArgumentException` that leaves the policy as it was. A generic method's result type depends on the call, so there the call throws the `InvalidOperationException`. In `Method(...).Configure(...)`, `GetOrCreateAsync` and `GetOrCreateManyAsync`, build error [MC0033](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0033) finds it first. - It is set for one method in code only, so it can't come from `appsettings.json`. In `Defaults` or a group it fails at startup. `.CacheWhen(...)` and `.Configure(o => o.CacheWhen(...))` set the same thing: the last call wins. `Any.Value` stands for any argument. > [!TIP] > To stop caching `null` everywhere, set `CacheNullValues = false` on the [memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md) instead. ## Skipping the cache for one call With [manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md), `WithEnabled` decides per call whether to use the cache at all: ```cs var results = await cache.GetOrCreateAsync( $"search:{text}", async ct => await search(), o => o.WithDuration(TimeSpan.FromMinutes(10)) .WithEnabled(!preview)); // preview requests skip the cache entirely ``` With `WithEnabled(false)`, the factory runs and its result is neither read from nor written to the cache. To decide from the result instead, use `CacheWhen` ([Validation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#validation)). --- # Configuration A cached method's policy (duration, sliding expiration, refresh-ahead, fail-safe, tags, group, version) can come from four layers. Change it in `appsettings.json` or at runtime, and the next call uses it, without a redeploy. | Layer | How you set it | Priority | Changes while running | |-------|----------------|----------|-----------------------| | Attributes | `[Cache(...)]` on the interface method | 10 (lowest) | No | | Startup code | `AddMethodCache(config => ...)` | 40 | No | | Configuration | `AddMethodCache(b => b.FromConfiguration(configuration))` | 50 | Yes, when the configuration reloads | | Runtime overrides | `IRuntimeCacheConfigurator` | 100 (highest) | Yes | When several layers configure the same method, they are merged setting by setting, and the highest layer that sets a setting wins. A runtime override of `Duration` leaves the attribute's `Tags` in place. ## What each surface can set The four surfaces take the same settings, with the same names, and reject the same mistakes. Where they differ, the table says why. | Setting | `[Cache]` | Startup code | `appsettings.json` | Runtime override | |---|---|---|---|---| | `Duration`, `SlidingExpiration`, `RefreshAhead`, `FailSafe`, `FailSafeTimeout`, `FailSafeRetryAfter`, `Tags`, `Version`, `Enabled`, `Distributed` | Yes | Yes | Yes | Yes | | `ClearTags` | No (1) | Yes | Yes | Yes | | `Group` (which group a method is in) | Yes | Yes | Yes | No (2) | | `CacheWhen`, `DurationFor`, `SlidingFor`, `TagsFor` | No (3) | Yes | No (3) | Only without a backplane (3) | | `InvalidatedElsewhere`, `InvalidatedManually` | Yes (4) | No | No | No | | For every method (`Defaults`) | No | Yes | Yes | Yes, `UpsertAllAsync` (5) | | For a group | No | Yes | Yes | Yes, `UpsertGroupAsync` (5) | | Over HTTP | No | No | No | Yes, `PUT /methodcache/overrides` ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#admin-endpoints)) | | Memory, distributed cache, telemetry | No | Yes (6) | No (6) | No | 1. The attribute is the lowest layer, so it has no tags under it to clear. `mc.Defaults(...)` and `"Defaults"` can't clear tags either, for the same reason, and say so at startup. 2. A method's group decides which group settings it gets, which belongs to how the application is built rather than to an incident. 3. These are functions. An attribute and a JSON file can't hold one, and another instance can't run one, so an override that every instance applies can't carry one. 4. These only tell the analyzers at build time where a method is invalidated; they change no policy. 5. A runtime override always wins, also over a method's own `[Cache]`. So the group and all-methods versions put the same override on each method instead of filling in what methods leave unset, as `Defaults` does. 6. These register services rather than set a policy. To read them from configuration, bind a section yourself: `mc.Memory(o => builder.Configuration.GetSection("MethodCacheMemory").Bind(o))`. `WithName` names an application's own `GetOrCreateAsync` call in metrics and logs. A cached method is always named by its method id, so `WithName` in `mc.Method`, `mc.Defaults`, `mc.Group` or a runtime override is an error. Tags are the exception: they are combined, not replaced. Tags from startup code, `appsettings.json`, runtime overrides and the defaults are added to the `[Cache]` attribute's tags (without duplicates), so a `[CacheInvalidate]` that lists an attribute tag always reaches the entry. To replace the tags instead, call `ClearTags()` before `AddTags` (`o => o.ClearTags().AddTags("orders")`), or set `"ClearTags": true` next to `Tags` for a method in `appsettings.json`. The tags of the lower layers and of the defaults are then dropped, and an entry without them is no longer removed by a `[CacheInvalidate]` that lists them. ## Defaults and groups Within the layers, each setting comes from the most specific place that sets it: the method itself, then its group, then the defaults. ```cs builder.Services.AddMethodCache(config => { // Every cached method: fills in what the method leaves unset config.Defaults(o => o.WithDuration(TimeSpan.FromMinutes(15))); // Methods in the "user-data" group: [Cache(Group = "user-data")] or WithGroup("user-data") config.Group("user-data", o => o.WithSlidingExpiration(TimeSpan.FromMinutes(10))); // One method config.Method((IUserService s) => s.GetProfileAsync(Any.Value)) .Configure(o => o.WithDuration(TimeSpan.FromHours(2)).WithRefreshAhead(TimeSpan.FromMinutes(5))); }); ``` - `Defaults` applies to every cached method, also ones that only have `[Cache]`. `[Cache(Duration = "10m")]` keeps its ten minutes while the defaults fill in what it leaves out. `ClearTags()` in `Defaults` fails at startup, since nothing under the defaults has tags. - A method joins a group with `[Cache(Group = "name")]`, `WithGroup("name")` in code, or `Group` in `appsettings.json`. Group names are case-sensitive. A group's defaults come from `config.Group(...)` and from `"Groups"` in `appsettings.json`, which wins where both set a value; a method's own settings win over both. `ClearTags()` in a group drops the tags from `Defaults`, not the method's own tags, which are above it. A group that has settings but no cached method in it, usually a typo or a difference in case, is logged as a warning at startup with the closest group name in use. - `CacheWhen`, `DurationFor`, `SlidingFor` and `TagsFor` are set for one method only. In `Defaults` or a group they fail at startup ([Conditional caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md), [A duration from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-duration-from-the-result), [A sliding window from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-sliding-window-from-the-result), [Tags from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#tags-from-the-result)). - `Any.Value` stands for any argument when you point at a method. Startup uses `MethodCacheBuilder`: `Defaults`, `Group`, typed `Method` expressions, `Memory`, `Distributed`, `Telemetry`, `FromConfiguration`, `FromAssemblyOf` and explicit `AutoRegister(lifetime)`. Redis, SQL Server, PostgreSQL and MessagePack packages add `UseRedis`, `UseSqlServer`, `UsePostgreSql` and `UseMessagePack`; Core provides `UseJson`. Use one distributed cache: calling more than one of `UseRedis`, `UseSqlServer` and `UsePostgreSql` throws. `Distributed(...)`, `UseMessagePack` or `UseJson` without a distributed cache logs a warning, since they have nothing to apply to. `builder.Services` is the service collection, for a package that adds its own `UseXxx` method. `Method` on a method without `[Cache]` fails at startup, and on a method that returns nothing (`void`, `Task`, `ValueTask`) throws an `ArgumentException`. All integration packages require the exact same Core package version; do not override this bound. CI uses strict restore (NU1608 as an error) to reject direct-version overrides. Configure services before `AddMethodCache`. Runtime overrides use the same immutable options builder as startup and manual cache calls. ## appsettings.json ```cs builder.Services.AddMethodCache(methodCache => methodCache.FromConfiguration(builder.Configuration)); // the "MethodCache" section ``` ```json { "MethodCache": { "Defaults": { "Duration": "15m" }, "FailSafe": { "Duration": "1h" }, "Groups": { "user-data": { "SlidingExpiration": "10m" } }, "Methods": { "[MyApp]MyApp.IUserService.GetProfileAsync": { "Duration": "1h", "SlidingExpiration": "10m", "RefreshAhead": "5m", // Profiles change rarely "Tags": ["users"], "Version": 1 }, "[MyApp]MyApp.IAccountService.GetBalanceAsync": { "FailSafe": "off" } } } } ``` - Each key under `Methods` is the **method id**: the escaped assembly simple name in brackets, the full interface name, a dot and the method name (for example `[MyApp]MyApp.IUserService.GetProfileAsync`). Assembly versions do not participate. A generic interface is written with its type parameters (`[MyApp]MyApp.IRepository.GetAsync`), and an overloaded method adds its parameter types (`[MyApp]MyApp.IUserService.FindAsync(int)`). Parameter types other than built-in ones are qualified by namespace (`[MyApp]MyApp.IUsers.Find(MyApp.Request)`), so overloads taking `A.Request` and `B.Request` stay separate. Types are named as reflection sees them: a tuple is `System.ValueTuple` (element names dropped), `nint` is `System.IntPtr` and `dynamic` is `object`. Runtime overrides by method id use the same format, and the parameter list is also part of the method's cache keys. The admin endpoints list every method id ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)), and `IMethodCacheKeys.MethodId(s => s.FindAsync(Any.Value))` returns the id of a call ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md)). - Settings: `Duration`, `SlidingExpiration`, `RefreshAhead` and `FailSafe` (each but `Duration` a time span or `"off"`), `FailSafeTimeout`, `FailSafeRetryAfter`, `Tags`, `Version`, `Enabled` and `Distributed`. A group under `Groups` and a method under `Methods` can also set `ClearTags` (`true` or `false`): `true` makes their `Tags` replace the lower layers' instead of adding to them. Only a method can set `Group`; in `Defaults` or a group it is an error. Keep notes about a method in a `//` comment next to its entry: `Notes` and `Metadata` are errors. Names are case-insensitive; any other name is an error, so a misspelled `"Durration"` is reported instead of ignored. A setting written without a value, such as `"Enabled": ""`, or an empty tag is an error too, rather than read as unset. The same goes for the section itself: it holds only `Defaults`, `FailSafe`, `Groups` and `Methods`. A leftover `Services` section from 1.0.0-rc.1 is reported as an unknown setting. - Tag templates such as `"order:{orderId}"` are checked against the parameters of every method they reach, as for `[Cache]` ([MC0010](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0010)): a template that names a parameter a method doesn't have fails at startup. - Durations are written as in attributes, with a unit: `"30s"`, `"5m"`, `"1.5h"`, `"7d"`; see [Writing a duration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#writing-a-duration). A bare number such as `"300"` is rejected rather than interpreted as days, and a `TimeSpan` such as `"00:05:00"` is rejected with the value to write instead (`"5m"`). - `Tags` is a list (`["users"]`), and a method's `FailSafe` is one duration: the `{ "Duration", "Timeout", "RetryAfter" }` block exists only at the top of the section. Setting the same value in that block and in `Defaults` (for example `FailSafe.Timeout` and `Defaults.FailSafeTimeout`) is an error. - A method can also be listed under an index with a `MethodId` property. Environment variable names can't hold `.`, `(` or `<`, so this is how environment variables, Kubernetes `env` or Linux App Service configure a method: ```bash MethodCache__Methods__0__MethodId="[MyApp]MyApp.IUserService.FindAsync(int)" MethodCache__Methods__0__Duration="2m" ``` A method can be listed once. Listing it both by name and under an index, for example by name in `appsettings.json` and under an index in an environment variable, fails at startup and names both paths. To override one file's settings from another source, list the method under the same index in both. - `Defaults` applies to every cached method; the top-level `FailSafe` section is described in [Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md). - Pass a section name as the second argument to read another section. Environment files such as `appsettings.Production.json` work as usual. The section is read when the host starts, so configuration sources added after `FromConfiguration`, such as a later `AddJsonFile` or a `WebApplicationFactory`'s test settings, apply from the first call. - Changes apply while the application runs, as soon as the configuration reloads (`appsettings.json` reloads on save by default). - Only methods with `[Cache]` (or listed in `[assembly: CacheInterface]`) have a decorator, so the file can change their policy but can't make other methods cached. A method id that matches no cached method, such as a misspelled name or an id without its `[Assembly]` prefix, fails at startup and suggests the closest cached id. `*` and `group:` are not method ids; use `Defaults` and `Groups`. - A setting for a `[Cache]` method whose service this application doesn't register is skipped, in the file and in `mc.Method(...)`, so configuration and startup code shared by several applications works in each of them. Each skipped method is logged once at startup, at Information, so a service you forgot to register shows up in the log. - An invalid value, such as a `Duration` that isn't a positive time span, makes the host fail to start with an `InvalidOperationException` naming the setting (without a generic host, the first cached call throws). If a reloaded file has one, the reload is logged as an error naming the setting's path, never its value, and the previous policies stay. ## Runtime overrides A runtime override of a method wins over that method's other layers (its attribute, startup code and `appsettings.json`). Use them to change a policy without a deploy, for example to shorten a duration during an incident: ```cs var configurator = app.Services.GetRequiredService(); // One method, strongly typed, with who and why for the audit trail await configurator.UpsertAsync( s => s.GetAsync(Any.Value), o => o.WithDuration(TimeSpan.FromMinutes(2)), new RuntimeOverrideMetadata { Owner = "ops", Reason = "Incident 4211", ExpiresAt = DateTimeOffset.UtcNow.AddHours(4) }); // By method id, for example from an admin form await configurator.UpsertAsync($"[{typeof(IUserService).Assembly.GetName().Name}]Docs.Configuration.IUserService.GetProfileAsync", o => o.WithDuration(TimeSpan.FromMinutes(10))); // Back to the lower layers await configurator.RemoveAsync(s => s.GetAsync(Any.Value)); await configurator.ClearAsync(); ``` | Method | What it does | |--------|--------------| | `UpsertAsync` | Adds or replaces the override for one method, by expression (`UpsertAsync(s => s.GetAsync(0), ...)`) or method id | | `UpsertGroupAsync` | Puts the same override on every cached method in a group | | `UpsertAllAsync` | Puts the same override on every cached method | | `RemoveAsync` / `RemoveGroupAsync` / `ClearAsync` | Removes one method's override, the overrides of a group's methods, or all of them | | `GetOverrides()` | Returns the active overrides, ordered by method id, with their options and audit metadata | To change a whole group or every method at once, for example to turn caching off for the `user-data` group during an incident: ```cs // Every method in the "user-data" group gets the same override await configurator.UpsertGroupAsync("user-data", o => o.WithEnabled(false), new RuntimeOverrideMetadata { Reason = "Incident 4211", ExpiresAt = DateTimeOffset.UtcNow.AddHours(1) }); // Every cached method await configurator.UpsertAllAsync(o => o.WithDuration(TimeSpan.FromMinutes(1))); // Back: the group's overrides, then all of them await configurator.RemoveGroupAsync("user-data"); await configurator.ClearAsync(); ``` The async operations return `ValueTask` and take cancellation last. These throw an `ArgumentException` before anything is stored: - a method id or expression that reaches no cached method, or a method that returns nothing (the message names the closest cached id), or a group no cached method is in (the message names the closest group); - a tag template that doesn't fit a method the override reaches; - an override that sets nothing, or sets `WithName`; - an `ExpiresAt` that has already passed; - a `RefreshAhead` or `Duration` that would leave a method refreshing its entries as soon as they are stored, such as a `RefreshAhead` of 20 minutes on a method whose `[Cache]` keeps entries for 10. The group and all-methods versions check every method first, so a mistake for one method changes none of them. - `UpsertGroupAsync` and `UpsertAllAsync` give each method an override of its own, replacing the one it had. `GetOverrides()` lists them per method, `RemoveAsync` removes one of them, and a method that joins the group later doesn't get it. Groups are case-sensitive, as everywhere. - Tags from an override are added to the method's tags unless the override calls `ClearTags()`. `WithEnabled(false)` turns caching off for the method; `WithDistributed(false)` keeps it in memory only. - An override that changes how the method caches drops the entries cached under the old settings at once; calls already running may still return their earlier result. An override that only changes its audit metadata keeps them. - With a [distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md) and its backplane (the default with `UseRedis`, `UseSqlServer` and `UsePostgreSql`), an override applies on every instance. It is stored in the distributed cache before `UpsertAsync` returns, the other instances apply it when the backplane tells them the method changed, and an instance that starts applies the active ones before it serves. So overrides outlive restarts and slot swaps, and `GetOverrides()` lists the same ones everywhere. Instances with the same override share its entries. - An override that every instance applies can't set `CacheWhen`, `DurationFor`, `TagsFor` or `SlidingFor`: they are functions, which another instance can't run. `UpsertAsync` throws an `ArgumentException`; set them in `AddMethodCache`. - When the distributed cache doesn't answer within `OperationTimeout`, `UpsertAsync`, `RemoveAsync` and `ClearAsync` throw an `InvalidOperationException` and the override stays as it was. An instance that can't read them when it starts logs a warning, starts without them and reads them again after `CircuitBreakerDuration`. - Without a distributed cache, or with `EnableBackplane = false`, overrides live in this instance's memory: they are lost on restart and don't reach other instances, and they may set functions. While such an override changes how a method caches, that method's entries in the distributed cache are this instance's own; removing the override invalidates the method and shares entries again ([Distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md#policies-and-shared-entries)). - `RuntimeOverrideMetadata` keeps owner, reason and ticket for the audit trail, and `ExpiresAt` removes the override when it passes. - `MethodCache.AspNetCore` sets, lists and removes overrides over HTTP with a body written like a method's entry in `appsettings.json` ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#admin-endpoints)). - A changed `appsettings.json` applies on this instance before the reload notification returns. Each instance reloads its own configuration; MethodCache doesn't distribute files. ### Switching all caching off and on again During an incident, or to rule the cache out while you look for a bug, switch caching off for every method and back on when you are done: ```cs // During an incident: every cached method calls its implementation, on every instance await configurator.UpsertAllAsync(o => o.WithEnabled(false), new RuntimeOverrideMetadata { Owner = "ops", Reason = "Incident 4211", ExpiresAt = DateTimeOffset.UtcNow.AddHours(2) }); // After it: every override goes, and each method has its other settings again await configurator.ClearAsync(); ``` - While it is off, every call runs the method, and the entries cached before are dropped, so the first calls after `ClearAsync` load again. - `UpsertAllAsync` replaces the overrides the methods had, so `ClearAsync` afterwards loses nothing that was still active. To keep an override for one method, set it again after `ClearAsync`. - `ExpiresAt` switches caching back on by itself if nobody does. - Over HTTP: `PUT overrides` with `{ "All": true, "Enabled": false, "Reason": "..." }`, then `DELETE overrides?all=true` ([Runtime overrides over HTTP](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#runtime-overrides-over-http)). - To switch off only some methods, put them in a [group](#defaults-and-groups) and use `UpsertGroupAsync` and `RemoveGroupAsync`. ## Seeing the effective policy `ICacheAdministrator.GetMethods()` shows each method's effective options, where each setting comes from, and whether its distributed cache entries are shared with other instances or its own because of a runtime override: ```cs var diagnostics = app.Services.GetRequiredService(); foreach (var report in diagnostics.GetMethods()) { var sources = string.Join(", ", report.SettingSources.Values.Distinct()); Console.WriteLine($"{report.MethodId}: Duration={report.Options.Duration}, from {sources}"); } ``` `SettingSources` is keyed by the `CacheEntryOptions` property name (`Duration`, `Tags`, `SlidingExpiration`, `RefreshAhead`, `Version`, `FailSafe`, `FailSafeTimeout`, `FailSafeRetryAfter`, `Enabled`, `Distributed`), and each value is a `CacheSettingSource`: `Attribute`, `Code`, `Configuration` or `RuntimeOverride`. A setting no layer sets is left out. `ReplacedSources` lists a setting that two of the method's own sources set, with the lower ones the higher one replaced: `Duration` with `[Attribute]` when startup code sets a `DurationFor` for a method whose `[Cache]` sets a `Duration`. A `Defaults` or group setting the method replaces isn't listed, since that is what defaults are for. Tags add up across layers, so `SettingSources["Tags"]` names the highest layer that adds tags. `Group` is the group the method is in, or null. The admin endpoint `GET /methodcache/methods` shows the same, with the sources as strings ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). ### What applies on this instance `Options` holds what the method's sources set; a setting none of them sets is null there and missing from `SettingSources`, and has the library's default. Next to it, each method says what that comes to on this instance, with the defaults filled in: ```cs foreach (var method in diagnostics.GetMethods()) { // Defaults filled in: 5 minutes without a Duration, the stored copy's life, and why values stay local Console.WriteLine($"{method.MethodId}: in memory up to {method.Lifetime.Duration}, " + $"shared for {method.Lifetime.Distributed?.ToString() ?? "-"} ({method.Storage.MemoryOnlyReason ?? method.Storage.Store})"); Console.WriteLine($" key: {string.Join(", ", method.KeyParameters)}"); foreach (var kept in method.NotShared) Console.WriteLine($" {kept.Type} kept in memory {kept.Count} times since {kept.Since}: {kept.Reason}"); } ``` | Property | Shows | |---|---| | `Lifetime.Duration` | The longest an entry lives in memory: the method's `Duration`, from `Defaults` or its group, else five minutes; with only a sliding window, `MaxExpiration`. Null when `DurationFor` gives each result its own (`DurationFromResult`) | | `Lifetime.SlidingExpiration` | The sliding window, or null without one or when `SlidingFor` gives each result its own (`SlidingFromResult`) | | `Lifetime.MaxExpiration` | The longest any entry lives: a limit for the whole cache, not a setting of the method (7 days unless `mc.Memory` sets it) | | `Lifetime.Distributed` | How long the copy in the distributed cache lives: the `Duration`, at most one sliding window and at most `TagRetention` less `ClockSkewTolerance`. Null when values aren't stored there or the result gives its own times | | `Storage.Distributed` | Whether values are stored in the distributed cache as well as in memory | | `Storage.Store` | The distributed cache, such as `Redis`, `SqlServer` or `PostgreSql` | | `Storage.MemoryOnlyReason` | Why values stay in memory: no distributed cache, `Enabled` or `Distributed` false (and where), `StoreValuesByDefault = false`, or a synchronous method | | `Storage.Shared` | Whether other instances read the values this one stores: false when values stay in memory, and while a runtime override that only this instance applies gives it a namespace of its own | | `KeyParameters` | The parameters whose values make up the key, in order; a `CancellationToken` isn't part of it, and `Version` is | | `NotShared` | Result types this instance kept in memory although the method shares its values, with the reason, how many and since when: a type the serializer can't write, or one that doesn't read back unchanged ([Serialization](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#serialization)) | `NotShared` is what this instance saw since it started; each instance keeps its own. ## Validation | Setting | Rule | Checked | |---------|------|---------| | `Duration` | A positive time span, and with the built-in memory cache at most `MethodCacheMemoryOptions.MaxExpiration` (7 days by default) | `[Cache]`: at build time ([MC0004](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0004)). Code: `ArgumentOutOfRangeException`. JSON: at startup. Longer than `MaxExpiration`: at startup from `[Cache]`, code and JSON, an `ArgumentException` from a runtime override, and an `ArgumentOutOfRangeException` from a manual call | | `SlidingExpiration`, `RefreshAhead`, `FailSafe` | A positive time span or `"off"`; in code, `TimeSpan.Zero` turns it off. A `SlidingExpiration` is at most `MaxExpiration`, like `Duration` | `[Cache]`: at build time ([MC0004](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0004)). Code: `ArgumentOutOfRangeException` for a negative value. JSON: at startup. A window longer than `MaxExpiration` fails where a longer `Duration` does | | `RefreshAhead` | Shorter than `Duration` and `SlidingExpiration` | `[Cache]`: at build time ([MC0023](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0023)). Code: `InvalidOperationException` when the options are built. JSON: at startup. Runtime override: `ArgumentException`. When the two come from different layers, such as `RefreshAhead` in code and `Duration` in `Defaults`, the host logs a warning at startup and the cache refreshes halfway through the duration | | `FailSafeTimeout`, `FailSafeRetryAfter` | A positive time span | `[Cache]`: at build time. Code (`WithFailSafeTimeout`, `WithFailSafeRetryAfter`): `ArgumentOutOfRangeException`. JSON: at startup | | `Tags` | Not empty or whitespace; templates name parameters of the method | `[Cache]`: at build time. Code: `AddTags` throws an `ArgumentException` for an empty tag; templates at startup. JSON: at startup | | `Version` | Zero or more | Code: `ArgumentOutOfRangeException`. JSON: at startup. On `[Cache]`, a negative explicit value is MC0021; omission inherits | `CacheEntryOptions.Builder` applies to startup, configuration, runtime overrides and manual calls. Each setting has one `With` method named like the attribute setting, such as `WithFailSafe`, `WithFailSafeTimeout` and `WithFailSafeRetryAfter`. `CacheWhen`, `DurationFor`, `SlidingFor` and `TagsFor` are configured in code for one method; one for a type the method can't return, such as `CacheWhen` on a method that returns `int`, throws an `InvalidOperationException` at startup (an `ArgumentException` from a runtime override) instead of silently caching nothing. Cache callbacks and context predicates are not supported. `[Cache]` takes named settings only. `Enabled` and `Distributed` inherit the configured policy when you leave them out, and an explicit `false` wins over the lower layers. `FailSafeRetryAfter` sets how long a served fail-safe value is reused before the method is tried again (30 seconds by default). `[assembly: CacheInterface(typeof(...), nameof(...))]` takes the same named settings. Overloaded generic methods have the number of type parameters in their method id: `Get(int)`, `Get``1(int)` and `Get``2(int)` are three methods, in `appsettings.json` as well. Options and tags you pass in code are copied, so changing the collection afterwards changes nothing. --- # Manual caching When an attribute doesn't fit, such as a call in the middle of a method or a client without an interface, use the same cache through `ICacheManager` with a key you choose: ```cs public sealed class OrderReader(ICacheManager cache, IOrderRepository orders) { public ValueTask GetAsync(int id, CancellationToken ct = default) => cache.GetOrCreateAsync( $"order:{id}", async token => await orders.GetAsync(id, token), o => o.WithDuration(TimeSpan.FromMinutes(30)).AddTags("orders", $"order:{id}"), cancellationToken: ct); } ``` It shares the in-memory cache, the distributed cache, stampede protection and invalidation with `[Cache]` methods. ## Keys You always pass the key yourself. MethodCache doesn't derive keys from the lambda, so a captured variable never ends up in a key by accident, and two calls share an entry only when their keys are equal. Use a prefix per kind of data, such as `order:42`, so keys from different places can't collide. An empty or whitespace key throws `ArgumentException`. The key is used as it is: MethodCache adds neither the result type, the service nor the application to it. Every service in the application shares these keys, and so does every application that shares a distributed cache under one `KeyPrefix`, as they do to invalidate each other's entries: `order:42` in two services, or in two of those applications, is one entry. Start each key with the area it belongs to, such as `billing:order:42`, and cache one type under a key. Keys of `[Cache]` methods include the method's assembly and interface, so they don't collide this way ([Several applications on one store](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#several-applications-on-one-store)). ## Options `GetOrCreateAsync` takes every option, including a predicate that only makes sense per call: ```cs var list = await cache.GetOrCreateAsync( $"orders:{customerId}:{status}", async ct => await orders.ListAsync(customerId, status, ct), o => o.WithDuration(TimeSpan.FromMinutes(30)) .WithSlidingExpiration(TimeSpan.FromMinutes(10)) .WithRefreshAhead(TimeSpan.FromMinutes(5)) .AddTags("orders", $"customer:{customerId}") .WithVersion(2) .WithEnabled(customerId > 0)); // skip the cache when false ``` - Duration, sliding expiration, refresh-ahead, tags and version work as described in [Expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md) and [Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md). - `Defaults` and groups are for cached methods: a manual call has only the options it passes. Without `WithDuration` its entry lives five minutes, whatever `Defaults` sets, and with only `WithSlidingExpiration` only `MaxExpiration` limits how long reads keep it. To keep values out of the distributed cache, manual calls included, set `StoreValuesByDefault = false`; a call with `WithDistributed(true)` then still shares its value ([Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only)). - `WithEnabled(false)` runs the factory on every call, and neither reads nor stores the entry. - `WithName("crm-token")` names the call in metrics, traces and logs (`methodcache.name`), where a manual call otherwise reports only that it was one ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#opentelemetry)). Use one fixed name for one kind of value, not one per key. - `WithDistributed(false)` uses this instance's memory only: neither `GetOrCreateAsync` nor `SetAsync` makes a network call, so a cache of values that must never leave the instance needs nothing else. Invalidating a key or tag still reaches every instance. `CacheWhen` checks the result before it is stored, and a value read from the distributed cache. `DurationFor` gives each result its own duration in place of `WithDuration` ([A duration from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-duration-from-the-result)), and `SlidingFor` its own sliding window in place of `WithSlidingExpiration` ([A sliding window from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-sliding-window-from-the-result)). `TagsFor` adds tags read from the result ([Tags from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#tags-from-the-result)). - On a hot path, build the options once and reuse them: `static readonly CacheEntryOptions Options = new CacheEntryOptions.Builder().WithDuration(...).Build();` and pass `Options` instead of a builder action, so a call doesn't build options again. - To avoid a closure, `ICacheManager.GetOrCreateAsync(key, state, (state, ct) => ..., options)` passes your state to a static factory. - Configuration files and runtime overrides apply to declared cached methods. Explicit-key calls use their own options. - `Build()` copies the tags, so changing the builder afterwards changes nothing. `ICacheManager` has four operations: `GetOrCreateAsync`, `TryGetAsync`, `InvalidateKeysAsync` and `InvalidateTagsAsync`. The interface takes every argument; extension methods give the short forms, such as `TryGetAsync(key, cancellationToken)`, `InvalidateKeyAsync(key)` and `InvalidateKeyAsync(key, version)`, and take a builder action instead of built options. `SetAsync` is an extension method too: on a manager of your own it invalidates the key and then stores the value through `GetOrCreateAsync`. To write your own manager, see [Registration](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md#your-own-cache-manager). ## Reading without loading ```cs var lookup = await cache.TryGetAsync("order:42"); if (lookup.Found) { Console.WriteLine(lookup.Value); } ``` `TryGetAsync` takes the `version` an entry was stored with: `TryGetAsync("order:42", 2)`. ## Storing a value you already have When you already have the new value, such as right after you saved it, `SetAsync` stores it so the next read doesn't load it again: ```cs var saved = await orders.SaveAsync(order, ct); await cache.SetAsync($"order:{saved.Id}", saved, o => o.WithDuration(TimeSpan.FromMinutes(30)).AddTags("orders", $"order:{saved.Id}"), ct); ``` - It stores the value in memory and the distributed cache, and other instances drop their copy, so their next read gets the new value from the distributed cache. - With `WithDistributed(false)`, or with `StoreValuesByDefault = false` and no `WithDistributed(true)`, it changes only this instance's memory and makes no network call: the distributed cache and the other instances keep what they hold. To change what every instance sees, use `WithDistributed(true)` or invalidate the key. - It takes the options `GetOrCreateAsync` takes. Use the same duration, tags and version as the calls that read the key, since the value replaces theirs. `DurationFor` gives it its own lifetime. - A value the options turn down isn't stored, and the key's old value is removed instead, from this instance only when the value would have stayed in memory: one `CacheWhen` rejects, one `DurationFor` gives no time, or `null` without `CacheNullValues`. `WithEnabled(false)` does nothing. - A load of the key that is running when you call it doesn't overwrite the value with what it read before. - To remove a value instead, invalidate the key or its tags ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md)). ## Versions and the stored key An entry stored with `WithVersion` lives under a different key than the unversioned one: `entry` at version 1 never shares a value with the key `entry::v1`. `TryGetAsync` and `InvalidateKeyAsync` take the same key and version you cached with: `TryGetAsync("order:42", 2)`, `InvalidateKeyAsync("order:42", 2)`. `ICacheAdministrator` takes the stored key, `MethodCacheKeys.StoredKey(key, version)`, which is what `CacheEntryInfo.StoredKey` shows; treat its format as opaque. To invalidate a versioned entry through `ICacheManager`, pass the key and its version, `InvalidateKeyAsync(key, 2)`, not the stored key. ## Many keys at once `GetOrCreateManyAsync` checks the local cache for every key, looks up the local misses in the distributed cache, and calls the factory once with the keys neither holds. Each key gets the value the cache selects: memory first, then the distributed cache, then the factory. A bulk read therefore agrees with individual reads of the same keys, even across nodes: a value another node stored in the distributed cache is returned as is, and its key is not passed to the factory. A concurrent writer may still win over a value the factory produced; the returned dictionary then holds the writer's value, as an individual read would. Pass the ids and how each id makes its key. The factory gets the ids that are not cached and returns a dictionary by id, and so does the call: ```cs var users = await cache.GetOrCreateManyAsync( userIds, id => $"user:{id}", async (missingIds, ct) => { var loaded = await repository.GetUsersAsync(missingIds, ct); // one query for all misses return loaded.ToDictionary(u => u.Id); // an id without a user is left out }, o => o.WithDuration(TimeSpan.FromHours(1))); ``` - An id the factory leaves out, such as one that doesn't exist, is not cached and is left out of the returned dictionary. When the key has an expired fail-safe value, it gets that value instead, as when the factory throws. To cache that an id has no value, return it with `null`. Nothing fails for a missing id, so when every id must have a value, check the returned dictionary: an id missing from it had none. - Two different ids that make the same key throw an `ArgumentException`, since one would get the other's value. - The factory returns a dictionary, an empty one when no id has a value; `null` fails like a factory that throws. - On a hot path, build the options once and pass the `CacheEntryOptions` instead of a builder action. - Each key behaves as `GetOrCreateAsync` would for it. When the factory throws, each key it was asked for gets its fail-safe value; when a key has none, the factory's exception is thrown. - `cancellationToken` stops this caller's wait. A factory that ignores it finishes in the background, and its values are cached unless they were invalidated while it ran. With string keys, pass the keys; the factory gets the keys that are not cached and returns a dictionary by key, with the same rules: ```cs var users = await cache.GetOrCreateManyAsync( userIds.Select(id => $"user:{id}"), async (missingKeys, ct) => { var ids = missingKeys.Select(k => int.Parse(k["user:".Length..])).ToList(); var loaded = await repository.GetUsersAsync(ids, ct); return loaded.ToDictionary(u => $"user:{u.Id}"); }, o => o.WithDuration(TimeSpan.FromHours(1))); ``` ## Things to know - Concurrent calls for the same key share one factory run, which gets the token of the caller that started it. A caller's `cancellationToken` stops its own wait; if it cancels a run others joined, they run the factory again rather than fail. - Name the factory's token and pass it on, as in `async ct => await orders.GetAsync(id, ct)`. CA2016 asks for that when the factory calls a method that takes a token, and named `ct` it hides the method's own `ct` inside the factory. Pass the method's token as `cancellationToken`: a token from outside the factory that the call doesn't pass, such as `HttpContext.RequestAborted`, fails the shared run for every caller when it is cancelled. [MC0035](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0035) reports it, with a code fix. - A factory that asks for the key it is loading (itself, or through the cached service it belongs to) would wait for itself, so that call throws an `InvalidOperationException` instead, and the key is free for the next caller. - To cache a sequence, materialize it in the factory (`await query.ToListAsync(ct)`) and cache the list. - The four operations on `ICacheManager` can be mocked directly. The options-builder convenience overload delegates to that interface. You can also pass a `NoOpCacheManager` ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md)). - `TryGetAsync` returns a fresh entry, a cached `null` included, also when refresh-ahead is due; it never runs a factory or starts a refresh. - An entry invalidated while `GetOrCreateManyAsync`'s factory runs is returned to that caller but not stored. --- # Caching third-party code MethodCache can cache calls to code you don't own, such as API clients, cloud SDKs or payment gateways, to cut API costs and latency. Pick one of three approaches: | Approach | Best for | |----------|----------| | `[assembly: CacheInterface]` | A client that ships an interface: cache chosen methods with one line, no wrapper | | A wrapper interface with `[Cache]` | A client without an interface (a sealed class or static methods) | | `ICacheManager.GetOrCreateAsync` | One or two calls, or keys you want to build yourself | ## The client's own interface Name the interface and the methods to cache in an assembly attribute, anywhere in your project: ```cs [assembly: CacheInterface(typeof(IFxRatesClient), nameof(IFxRatesClient.GetRateAsync), Duration = "1m", Tags = ["fx", "fx:{from}"])] ``` ```cs builder.Services.AddSingleton(); // the vendor's client, registered as usual builder.Services.AddMethodCache(); ``` - The listed methods behave like methods with `[Cache]`: keys from the arguments, tag templates with the method's parameter names, zero-allocation hits on .NET 10. Methods you don't list always reach the client, so writes are never cached by accident. - The attribute's settings (`Duration`, `Tags`, `Group`, `SlidingExpiration`, `RefreshAhead`, `Version`, `FailSafe`, `FailSafeTimeout`, `FailSafeRetryAfter`, `Enabled`, `Distributed`) apply to every listed method. Give one method its own settings like any cached method: ```cs builder.Services.AddMethodCache(config => config.Method((IFxRatesClient c) => c.GetRateAsync(Any.Value, Any.Value)) .Configure(o => o.WithDuration(TimeSpan.FromSeconds(30)))); ``` - The method id in `appsettings.json` and the admin endpoints is the name of the assembly that declares the interface (the vendor's, not yours) in brackets, the interface's full name, a dot and the method name, for example `[FxVendor]FxVendor.IFxRatesClient.GetRateAsync`. `IMethodCacheKeys.MethodId` returns it for you. - List each interface once. It must be non-generic and come from another assembly; for your own interfaces, put `[Cache]` on the methods. A method with overloads can't be listed yet. - The attribute can live in a class library, such as your infrastructure project. Select its generated module explicitly with `MethodCacheBuilder.FromAssemblyOf()`, using a type declared in that assembly. This bootstraps the module under Native AOT without relying on discovery of loaded assemblies; your own `[Cache]` interfaces in other assemblies stay cached. - When multiple assemblies generate the same interface, the module you select wins. Calling and entry assemblies have no special precedence. An ambiguous registration throws `InvalidOperationException` naming the candidates. ```cs builder.Services.AddMethodCache(cache => cache.FromAssemblyOf()); ``` - Mistakes are build errors: [MC0011](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0011) (a type it can't cache, such as one with static abstract or non-public abstract members), [MC0012](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0012) (a method that is missing, overloaded, static, or one `[Cache]` would reject) and [MC0013](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0013) (an interface listed twice). ## A wrapper interface Define an interface in your project with the calls you need, and put the settings on it: ```cs public interface IRates { [Cache(Duration = "1m", Tags = ["fx", "fx:{from}"])] Task GetAsync(string from, string to); } public sealed class Rates(FxRatesClient client) : IRates // calls the vendor's concrete class { public Task GetAsync(string from, string to) => client.GetRateAsync(from, to); } ``` ```cs builder.Services.AddSingleton(); builder.Services.AddScoped(); builder.Services.AddMethodCache(); ``` Static methods and sealed classes work the same way: the wrapper calls them, and the interface carries the attributes. ## An explicit key ```cs var rate = await cache.GetOrCreateAsync( $"fx:{from}:{to}", async ct => await client.GetRateAsync(from, to), o => o.WithDuration(TimeSpan.FromMinutes(1)).AddTags("fx")); ``` See [Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md). ## Things to know - **Leave writes uncached.** Payments, uploads and deletes must not be cached; mark wrapper methods that change data with `[CacheInvalidate(Tags = ...)]`. - **Exceptions are not cached.** With [fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md) on, the previous value is served while the client fails. - **Invalidate from a webhook** with `cache.InvalidateTagAsync("fx:EUR")` when the vendor tells you data changed. - **Share results between instances** with a [distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md) when every instance calls the same paid API. - **Start with short durations** and lengthen them once you know how fresh the data must be. --- # HTTP response caching Add `AddHttpCaching()` to an `HttpClient` registration to cache HTTP responses according to their response headers, as RFC 9111 describes. Freshness comes from `Cache-Control` and expiry headers; `ETag` and `Last-Modified` enable conditional validation, and a successful 304 is returned to the caller as the full response. Chapter 11 of the [console tour](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.Demo#httpclient-caching) starts a local HTTP server and checks cache hits, ETag/304 validation, `no-store` and invalidation after PUT. It needs no external API or Docker. ```cs builder.Services.AddMethodCache(); builder.Services.AddHttpClient() .AddHttpCaching(); ``` The [package guide](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.HttpCaching/README.md) covers settings, private and shared caches, limits and metrics. This page covers the rules the cache follows. [Security](https://github.com/eoniclabs/MethodCache/blob/main/docs/security.md#methodcachehttpcaching) has the threat model, and the [HTTP caching reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/http-caching.md) the exact behavior. ## Freshness and validation - Stale-while-revalidate and stale-if-error are optional. Response `no-cache` requires successful validation before the response is reused, even when either option is on. Request `no-cache` has the same requirement: a 5xx response or network error reaches the caller rather than falling back to cached content. - `must-revalidate` forbids serving a stale response, as do `proxy-revalidate` and `s-maxage` in a shared cache. - An `Expires` at or before the response `Date`, or one that doesn't parse (such as `Expires: 0`), makes the response stale at once. Heuristic freshness and `DefaultMaxAge` don't extend it. An explicit `max-age` (or `s-maxage` in a shared cache) wins over `Expires`. - A 304 updates the stored response's headers and whether it may be stored. If it changes to `no-store`, `Vary: *`, or `private` in a shared cache, the stored response is removed. This applies to background revalidation too. A 304 without `Vary` keeps the original variant selection. If the updated response can't be stored, the old one is removed so its old rules are never used again; the caller still gets the response. If removing it fails too, the error reaches the caller. - A `Cache-Control` or `Vary` field that doesn't parse (such as `private; max-age=600` or `max-age=-1`), also next to a valid one, is not read as absent: the response is not stored, because the header may have said `private` or `no-store`. - An entry is kept at most a year, even when `Expires` is far in the future (`31 Dec 9999`). - Weak ETags (`W/"abc"`) are sent back as weak validators. - `only-if-cached` never contacts the origin, including for range requests, requests with their own validators, `no-store`, methods that aren't cached and background revalidation. When no stored response can be used, the answer is 504. ## Redirects, retries and request bodies - A redirect the transport follows (`AllowAutoRedirect`, the default) answers a different URL, so it is not stored under the URL you requested. The transport also drops `Authorization` on a redirect, so storing it could hand one caller's response to another. Requests that end at the redirect target are cached under that URL as usual. If the target answers the cache's own validators with 304, the request is sent again without them, so you get the full response. A URL that was cached and now redirects has its stored response removed, also when background revalidation finds out. - The cache stores responses for the request as you sent it, before the transport adds headers such as `Accept-Encoding` for automatic decompression. `Vary: Accept-Encoding` therefore works with `AutomaticDecompression`. - The `If-None-Match` / `If-Modified-Since` headers the cache adds are removed again before the response is returned, so a retry handler (Polly, standard resilience) that sends the same message again gets a full response. - A `GET` or `HEAD` with a body (search APIs such as Elasticsearch) goes to the origin: its URL doesn't identify it. - The URL fragment (`#top`) is not part of the key; it never reaches the origin. ## Writes and invalidation - A successful `POST`, `PUT`, `PATCH` or `DELETE` invalidates the cached responses for its URL before it returns: the URL you sent it to, also when the response redirects (`303 See Other`) elsewhere. A `GET` already in flight can't store its older response over it. - With Redis, SQL Server or PostgreSQL configured, every instance sees the invalidation at once, even when backplane messages are lost. - If the invalidation can't be confirmed, the call throws `HttpCacheInvalidationException`. The write may have succeeded at the origin, so don't retry it automatically. A `GET` that throws it is safe to retry. - To invalidate from code, use `ICacheAdministrator`: one response by the id `ListEntries` gives, a client's responses by its tag (`http:` followed by `MethodCacheKeys.Part(clientName)`) or the tags in `HttpCacheOptions.Tags`, or everything with `ClearAsync`. ## Storage Responses are stored in MethodCache's memory cache, in a budget of their own (`MaxHttpBytes`, 100 MiB by default, headers included) next to method results. With Redis, SQL Server or PostgreSQL configured, they are stored there instead, so every instance shares them. A response larger than the budget is streamed to the caller and not stored. `AddHttpCaching` needs `AddMethodCache` in the same container, in either order. The admin endpoints and `ICacheAdministrator` list and remove cached responses; they never show bodies, credentials, cookies or query strings. ## Transport and cookies `AddHttpCaching()` turns off automatic cookies on the client's `SocketsHttpHandler` or `HttpClientHandler`, after all other configuration of that handler, so the default registration caches at once. Other named clients are unaffected. A handler that already has cookies off is left alone, so a cookie-free handler shared between clients keeps working. `ConfigureHttpClientDefaults(b => b.AddHttpCaching())` caches every client, each under its own name: two clients never share entries, and they all use the settings given there. A client has at most one cache: calling `AddHttpCaching` again for one client, or twice, adds no second cache and applies every settings delegate. To give one client other settings, use `services.Configure("name", o => ...)`. `KeepCookies=true` leaves the transport's cookies on and turns response caching, validation and stale fallback off for that client. `only-if-cached` then returns 504, and a successful write still invalidates its URL. Send caller cookies as request headers; a handler that keeps a hidden cookie jar belongs on a client without HTTP caching. The cache runs after every other handler you add, so caller identity and rewritten requests are visible before lookup. Other transports (wrappers the cache can't see into, native platform handlers), and handlers inside the primary transport or below a cache handler you construct yourself, can't be checked. They bypass caching and log one warning per named client, unless you set `AllowUnverifiedTransport`. Set it only when you have checked that the whole transport sends no automatic cookies or hidden caller identity. A known transport with automatic cookies turned on always bypasses. --- # Distributed cache By default each application instance has its own in-memory cache. Add a distributed cache to share results between instances and keep them across restarts: ```cs builder.Services.AddMethodCache(mc => mc.UseRedis("localhost:6379")); // MethodCache.Redis ``` ```cs builder.Services.AddMethodCache(mc => mc.UseSqlServer(connectionString)); // MethodCache.SqlServer ``` ```cs builder.Services.AddMethodCache(mc => mc.UsePostgreSql(connectionString)); // MethodCache.PostgreSql ``` The [web demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.WebDemo) runs two instances that share Redis, including what happens when Redis goes down. ## How it works ```mermaid flowchart LR A([Call a cached method]):::dark --> B{In memory?} B -- yes --> R([Return the value]):::amber B -- no --> C{In Redis, SQL Server
or PostgreSQL?} C -- yes --> D[Keep it in memory]:::light --> R C -- no --> E[Run your method]:::dark --> F[Write it to memory
and the distributed cache]:::light --> R classDef dark fill:#1E1B3A,stroke:#1E1B3A,color:#F5F3FF classDef amber fill:#FFB020,stroke:#FFB020,color:#1E1B3A classDef light fill:#F5F3FF,stroke:#1E1B3A,color:#1E1B3A ``` ```mermaid sequenceDiagram participant A as Instance A participant D as Redis / SQL Server / PostgreSQL participant B as Instance B A->>A: [CacheInvalidate] or InvalidateTagsAsync A->>D: Remove the key, or stamp the tag A-->>B: Backplane message (pub/sub, NOTIFY, or the next poll) B->>B: Drop the in-memory copy Note over B: The next call reads the distributed cache or runs the method ``` - Results live in memory and in the distributed cache. An in-memory miss reads the distributed cache before running your method, and a new result is written to both. - Invalidating a key removes it from the distributed cache. Invalidating a tag records when it happened, so older entries with that tag read as misses. A backplane tells every other instance to drop its in-memory copy: at once with Redis pub/sub and PostgreSQL `NOTIFY`, or on their next poll (every second by default) with SQL Server. - Redis, Microsoft SQL Server and PostgreSQL are supported. Other stores are not; the storage interfaces are internal. Use one of them: calling more than one of `UseRedis`, `UseSqlServer` and `UsePostgreSql` throws. `Distributed(...)` and `UseMessagePack()` without one log a warning at startup, since they have nothing to apply to. - `[Cache]` methods and `GetOrCreateAsync` need no changes. Synchronous `[Cache]` methods use only the memory cache, so they never wait on the network; a synchronous `[CacheInvalidate]` reaches the other instances in the background. - MethodCache keeps its own distributed cache and connection, so your application's `IDistributedCache` is left alone and is never used as a fallback. > [!NOTE] > Instances on different 1.x versions can share a cache and backplane, so you can upgrade them one at a time: every > 1.x version reads the others' invalidations, and an entry in a format an instance doesn't read is a miss for it. A > backplane message an instance can't read clears its memory cache, with one warning. ## When the distributed cache is down Calls keep working from memory and your methods; the distributed cache never fails or stalls a call. Each call to it is capped at `OperationTimeout` (one second), a circuit breaker skips it until it is back, and invalidations are queued and retried instead of throwing. Until they are stored, the instance doesn't read entries from it, so an invalidated value can't come back. The [health check](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#health-check) reports Degraded while this lasts. Queued invalidations are stored a batch at a time once the cache answers, so a long outage's backlog drains at the pace the cache can take. More than 10,000 are replaced by one clear of the distributed cache (logged as a warning), and so is an invalidation the cache keeps refusing while it answers everything else, so neither holds up the rest. The queue lives in memory: when the instance shuts down, it waits for writes still running, then tries once more to store what is queued, each step (stamp, removal, publish) capped by `OperationTimeout`, and logs a warning with the number it had to drop. Other instances can read those invalidated values from the distributed cache until they expire. A value set directly while the distributed cache is down stays in that instance's memory, and the value it replaced is removed from the distributed cache and the other instances once it is back. An entry that comes back damaged (cut short, or unreadable by the serializer) is a miss: your method runs and its result replaces the entry. When the app starts, the connection is opened in the background once the host has started, so the first request finds it open. Opening a connection can take longer than one call: until the distributed cache first answers, a call waits for it up to `OperationTimeout` and then uses memory only, and once one call has waited that long the rest don't wait. A slow start doesn't open the circuit breaker; one that fails, or hasn't answered after 30 seconds, does. Without a generic host, such as in a console app that builds its own `ServiceProvider`, the first call opens the connection within its `OperationTimeout`. The timeout caps each call to the distributed cache, not a whole cache miss. A cache that stops answering costs a miss one timeout, after which the circuit breaker skips it. One that answers just within the timeout costs a miss up to three: reading the entry, writing your method's result and checking that no removal raced the write (and a fourth for the backplane message). ## Options `DistributedCacheOptions` apply to Redis, SQL Server and PostgreSQL alike: ```cs builder.Services.AddMethodCache(mc => mc.Distributed(options => { options.OperationTimeout = TimeSpan.FromMilliseconds(500); options.CircuitBreakerDuration = TimeSpan.FromSeconds(30); })); ``` | Option | Default | | |---|---|---| | `OperationTimeout` | 1 second | The longest one call to the distributed cache may take. A slower call is abandoned and counts as a failure, except a write (see [What other instances see](#what-other-instances-see)) | | `CircuitBreakerDuration` | 10 seconds | How long the distributed cache is skipped after a failure or timeout. Invalidations it didn't accept are retried at this interval | | `ClockSkewTolerance` | 2 seconds | How far apart your servers' clocks may be. A tag invalidation also applies to entries created up to this long after it. One stamped further ahead of an instance's clock (by a server whose clock runs fast) counts from when that instance first read it, until its clock reaches the stamp | | `TagCheckInterval` | 1 second | How long an instance trusts the invalidation time it last read for a tag. Without a backplane, an entry read from the distributed cache can outlive a tag invalidation made on another instance by up to this long | | `TagRetention` | 1 day | How long tag invalidations are kept. An entry stays in the distributed cache at most `TagRetention - ClockSkewTolerance` from when your method started loading it (less if its own duration is shorter), and the first value of each method or `WithName` name that asks for longer logs a warning; a load that takes longer is kept only in that instance's memory. Both values are truncated to whole milliseconds, and `TagRetention` must exceed `ClockSkewTolerance` by at least one millisecond, or startup fails; with SQL Server it must also end before 9999-12-31 | | `KeyPrefix` | `methodcache:` | The prefix of everything MethodCache stores and of its backplane messages. Applications that share a store share their entries and invalidations under one prefix; give an application its own to keep them apart ([below](#several-applications-on-one-store)). It can't change while the app runs | | `StoreValuesByDefault` | `true` | Store values in the distributed cache. `false` keeps values in memory, except those of methods and calls that set `Distributed` to `true`, and uses the distributed cache for invalidations ([Invalidations only](#invalidations-only)) | | `VerifyUnchangedInDevelopment` | `true` | In Development, write the values kept in memory again every two seconds and warn when code changed one ([Results that don't change](#results-that-dont-change)) | | `VerifyRoundTrip` | `true` | Read each value back before sharing it, and keep values that don't come back the same in memory only ([Serialization](#serialization)) | | `SerializerVersion` | `1` | Raise it when you change serializer settings, so values written with the old settings are not read | ## Several applications on one store Applications that use one Redis or database share everything under the same `KeyPrefix`: entries, tags and invalidations. That is how a worker invalidates what an API cached. A different prefix keeps two applications apart in both ways, so neither sees the other's entries nor its invalidations: ```cs builder.Services.AddMethodCache(mc => mc.UseRedis("localhost:6379").Distributed(o => o.KeyPrefix = "billing:")); ``` Under one prefix, `[Cache]` methods never share an entry by mistake, since each key holds the method's assembly, interface and name. A key you pass to `ICacheManager` is used as it is, without a type or application, so `GetOrCreateAsync("order:42", ...)` in two applications is one entry. Cache the same type under such a key everywhere, or start it with the application's name, such as `billing:order:42` ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#keys)). ## Invalidations only When each process should keep its own values, and only needs to hear about invalidations (a worker that changes data an API caches, say), set `StoreValuesByDefault = false` in every process. Values stay in each process's memory, those of cached methods and of [manual calls](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md) alike, and every invalidation still reaches the other processes: ```cs builder.Services.AddMethodCache(mc => mc .UsePostgreSql(connectionString) .Distributed(o => o.StoreValuesByDefault = false)); // values stay in memory; invalidations reach every process ``` Invalidations are still stored in the database, so it needs the same tables as a full distributed cache, but no values are written there unless a method or call asks for it (below). Each process then loads its own values, so with ten instances a key is loaded ten times, and a new instance starts with an empty cache. Responses cached by [HTTP caching](http-caching.md) are still stored in the distributed cache. To keep only some methods in memory, use `[Cache(Distributed = false)]`, a group or `WithDistributed(false)` instead ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)). `Defaults(o => o.WithDistributed(false))` applies to cached methods only, so a manual call would still store its value. ### Memory by default, shared where you say so With `StoreValuesByDefault = false`, a method with `[Cache(Distributed = true)]` or a call with `WithDistributed(true)` still stores its value in the distributed cache, so every instance reads it. Share values that are expensive or rate-limited to load, such as an access token or a supplier's response, and keep the rest in each instance's memory: ```cs builder.Services.AddMethodCache(mc => mc .UseRedis("localhost:6379") .Distributed(o => o.StoreValuesByDefault = false)); // values stay in memory unless a method or call says otherwise ``` ```cs // Every instance reuses one access token instead of asking the provider for its own return cache.GetOrCreateAsync("crm:access-token", async ct => await tokens.RequestTokenAsync(ct), o => o.WithDuration(TimeSpan.FromMinutes(50)).WithDistributed(true)); ``` A cached method gets `Distributed` from its settings as usual: from its attribute, its group, `Defaults` or `appsettings.json`. A manual call gets it only from its own options. A method or call that sets nothing stays in memory. A call that keeps its value in memory touches only that instance: `GetOrCreateAsync` and `SetAsync` with `WithDistributed(false)` make no network call, and the distributed cache and the other instances keep what they hold. To change a value every instance sees, set it with `WithDistributed(true)` or invalidate the key, which reaches every instance whatever `Distributed` says. ### A worker and an API A common case: a worker writes data with EF Core, and an API caches reads of it. The API caches in its own memory and marks the tag as invalidated by another process: ```cs public interface IFoodCatalog { // The worker writes the catalog; its saves invalidate food-catalog in every process [Cache(Duration = "1d", Tags = ["food-catalog"], InvalidatedElsewhere = ["food-catalog"])] Task> SearchAsync(string text); } ``` ```cs // The API caches reads of the catalog in its own memory builder.Services.AddDbContext(o => o.UseNpgsql(connectionString)); builder.Services.AddScoped(); builder.Services.AddMethodCache(mc => mc .UsePostgreSql(connectionString) .Distributed(o => o.StoreValuesByDefault = false)); ``` The worker caches nothing. With [MethodCache.EntityFrameworkCore](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md), its `SaveChanges` invalidates the tags its mapping names, and the invalidation reaches the API through PostgreSQL: ```cs // The worker caches nothing: its saves invalidate the tags the mapping names, in every process builder.Services.AddDbContext(o => o.UseNpgsql(connectionString)); builder.Services.AddMethodCache(mc => mc .UsePostgreSql(connectionString) .Distributed(o => o.StoreValuesByDefault = false) .UseEntityFrameworkCore(ef => ef.Entity("food-catalog"))); ``` The API reloads the catalog on its next read after the worker's save commits, usually within milliseconds. Writes the change tracker doesn't see, such as `ExecuteUpdate`, need their tags invalidated by hand ([Writes the change tracker doesn't see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#writes-the-change-tracker-doesnt-see)). Both processes use the same four tables. When a login may not create tables, such as an API that connects as a role other than the owner because the database uses row-level security, create them once with the package's script and grant that login `SELECT, INSERT, UPDATE, DELETE` on them ([Tables](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/README.md#tables)). `TagCoverage` ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-tag-has-an-invalidation)) counts `food-catalog` as invalidated only when the API's test project references the worker project, since the worker is where the invalidation is. ## What other instances see - An invalidation reaches another instance when the backplane delivers it, usually within milliseconds; until then that instance serves its in-memory copy. Instances without a copy read the distributed cache, which is already right. When an instance loses its backplane connection: - With SQL Server and PostgreSQL, invalidations are rows in a table, so the instance reads the ones it missed when it reconnects. An instance that couldn't read the table for half of `BackplaneRetention` may have missed some, so it clears its whole in-memory cache. - With Redis, a message reaches only the instances connected when it is sent, so the instance clears its whole in-memory cache when its connection comes back. - With `EnableBackplane = false`, no instance hears of another's invalidations: each serves its in-memory copy until it expires. - Messages carry no values, so a late, repeated or reordered message only makes an instance read the distributed cache again. - Reads don't reach the distributed cache, so a value with a sliding window is stored there for one window, or its `Duration` if that is shorter, from when it was stored. The next instance that asks for it after that loads it again, and the new value replaces the copy that the instance that loaded it first kept extending while it was read ([Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration)). - An invalidation the distributed cache didn't accept is retried every `CircuitBreakerDuration`. Until the retry succeeds, other instances can serve the old value; the instance that invalidated never does. - A write that timed out (a large value, say) doesn't open the circuit breaker, since the cache may answer everything else: the instance logs a warning and keeps using it. Such a write may still land later, because a distributed cache has no compare-and-set, so its key is removed again after `CircuitBreakerDuration` (as after a write that failed, once the cache answers). Further timed-out writes of the key push that one removal back, and an instance that shuts down first removes the key while it shuts down. Until then the late value can replace a newer one, and a write that lands after that removal stays until it expires. - Entries carry no checksum: damage that still reads as a valid value is served. ## Serialization Values are written as JSON with System.Text.Json, public fields included, so records, value tuples and structs are shared as they are. A `Dog` where `Animal` is declared comes back as a `Dog` too ([Derived types](#derived-types)). Each value is read back once before it is shared. A value that doesn't come back the same, such as a class with private setters, `object`, or a dictionary made with its own comparer, stays in that instance's memory only, with one warning that names the method and the type. Register your own `JsonSerializerOptions` or `JsonSerializerContext` with `UseJson` to share it (`[JsonInclude]` for private setters). [Distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md#serialization) has the exact rules. The `MethodCache.Serialization.MessagePack` package makes values smaller and faster to read: ```cs builder.Services.AddMethodCache(mc => mc .UseRedis("localhost:6379") .UseMessagePack()); // MethodCache.Serialization.MessagePack ``` Entries written in the other format read as misses and are replaced, so switching needs no flush. See the [MessagePack package guide](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.Serialization.MessagePack/README.md). Under Native AOT, register your `JsonSerializerContext` ([Native AOT](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/native-aot.md)). ## Derived types A cached result that declares a base type can hold a derived one: a `Dog` in a `List`, in an `Animal` property, or returned by a method declared to return `Animal`. MethodCache's generator finds the classes that derive from such a type or implement such an interface, and names them to MethodCache's JSON and MessagePack serializers, so a `Dog` comes back from the distributed cache as a `Dog`. It finds them in the project with the cached interface, in the declared type's own assembly and the assemblies built on it, and in projects that reference the one with the cached interface. Your application's own JSON doesn't change: `JsonSerializer.Serialize(dog)` still writes an `Animal`. The log at startup lists the derived types the distributed cache restores. - A base type with `[JsonDerivedType]` or `[JsonPolymorphic]`, or `[Union]` with MessagePack, keeps its own settings. - A derived type the generated code can't name, because it is private, file-local, generic or not public in another assembly, gets [MC0039](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0039) at build time. A value holding one stays in memory only. - Under Native AOT, the `JsonSerializerContext` you pass to `UseJson` needs `[JsonSerializable(typeof(Dog))]` as well. [MC0040](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0040) names a derived type it lacks, and its code fix adds it. At startup, MethodCache also logs a warning naming the derived types the context has no contract for. - EF Core entities with lazy-loading proxies come back as plain entities without their navigations ([MC0041](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0041)). Cache a projection such as a record instead. ## Results that don't change The memory cache keeps the instance your method returned and hands that same instance to every later caller on the instance. The distributed cache keeps a serialized copy. Code that changes a result, such as `orders.Add(draft)` or `order.Status = Shown`, changes what later callers on this instance get, while the other instances still read the copy without the change. Instances then give different answers until the entry expires. - Return types that can't be changed, so the compiler stops such code: records with `init` properties, and `IReadOnlyList` or `IReadOnlyDictionary` for collections. - When a caller needs to change a result, change a copy: `orders.ToList()`, `new List(orders)`, or `order with { Status = OrderStatus.Shown }`. A list copy holds the same objects, so copy an object before setting its properties. Copy an array, such as a `float[]` embedding, before you normalize it in place: `vector.ToArray()`, then write to the copy or a `Span` over it. - [MC0043](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0043) reports code that changes a cached result while you build. Your own methods that change an object, such as `order.Close()` or a helper you pass the result to, aren't seen by the build. In Development, MethodCache also writes the values it keeps in memory again every two seconds, compares them with what it stored, and logs one warning per method whose value has changed. That check runs only when `IHostEnvironment` says Development, and never when a call is answered from memory. When values are so large that writing them again slows down development, turn it off with `Distributed(o => o.VerifyUnchangedInDevelopment = false)`. - Keep all state in what the serializer writes: data only in private fields is written as `{}` ([MC0042](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0042)). - An object referenced twice in a result comes back as two copies, and a `DateTime` of kind `Local` shows another clock time on a server in another time zone. Use `DateTimeOffset` or UTC times. ## Keep invalidations from being evicted > [!WARNING] > Tag, clear and key-removal stamps are ordinary expiring keys next to the entries they invalidate. A store that evicts a > stamp under memory pressure while an entry it invalidated stays makes that entry valid again, on every instance, until > it expires. Runtime override records are stored the same way, and an evicted one no longer reaches instances that > start. Give the store room, and don't let it evict MethodCache's keys: for Redis, use `maxmemory-policy > noeviction` (or a Redis of its own). Every MethodCache key has a time to live, so the `volatile-*` policies can evict > them as well as the `allkeys-*` ones. With `noeviction`, a full Redis refuses writes instead: MethodCache then treats it > as down and answers from memory. SQL Server and PostgreSQL remove rows only once they expired. ## Changing result types and upgrading - When a cached result's shape changes, such as a renamed property, another property type or renumbered enum members, the new build reads entries of its own. MethodCache's generator computes a fingerprint of what the serializer writes for each cached method's result, including the derived types registered for it, and keeps entries of another shape apart. During a rolling deploy each build reads its own entries, and invalidations by key and by tag reach both. - Raise the method's `Version` for a change the build can't see: what a value means changes while its shape doesn't, a `JsonConverter` writes it differently, or a derived type in a project that references the cached interface's project changes. Raise `SerializerVersion` when you change serializer settings. - Instances on different 1.x versions can share a store and backplane, so a rolling upgrade works. When a release writes some keys differently, its CHANGELOG section says so under "Upgrading". During the rollout, instances on the old and the new version then miss each other's entries for those methods: each loads once and caches under its own key. An invalidation by tag reaches both. An invalidation by key, such as `IMethodCacheKeys.For(...)`, reaches only the entry written by the version that sent it, so the other version's entry stays until it expires. Keep the same `KeyPrefix` during the rollout, since a different one also keeps the two versions' invalidations apart. - SQL Server and PostgreSQL create their tables on first use. With an existing SQL Server invalidations table from before 1.0, or a login that may not create tables, see the [SQL Server](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.SqlServer/README.md) and [PostgreSQL](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/README.md) guides. ## Limits - Invalidation matches exact keys and tags; common tags provide group invalidation. - [Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md) values live in each instance's memory. [Runtime overrides](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#runtime-overrides) apply on every instance with a backplane, and only on their own instance without one. ## Package guides The [Redis](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.Redis/README.md), [SQL Server](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.SqlServer/README.md) and [PostgreSQL](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/README.md) READMEs cover their options, shared connections, table creation, outage settings and how each stores keys and invalidations. The PostgreSQL guide compares all three; the SQL Server guide has the schema migration for an existing invalidations table. [Benchmarks](https://github.com/eoniclabs/MethodCache/blob/main/docs/benchmarks.md#distributed-cache-providers) measures them side by side. The exact guarantees, such as what a cancelled call leaves behind and how each backplane recovers, are in the [distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md). --- # Monitoring Core emits standard .NET metrics and activities. `AddMethodCache()` uses the container's `IMeterFactory`, registering one when needed, and owns an `ActivitySource` with the same `MethodCacheTelemetry.Name` (`MethodCache`). Both use the assembly version. Separate containers keep their observation callbacks separate. ## Which layers an instance uses When the cache starts, MethodCache logs one `Information` line that names its layers: the memory cache with its `MaxItems`, and the distributed cache with its store, `KeyPrefix` and backplane, or that there is none. Compare it between instances and environments when they don't seem to share entries or invalidations: ```text MethodCache caches in memory, up to 10000 entries per instance, and in the distributed cache Redis under the key prefix 'methodcache:', with the Redis backplane telling other instances to drop their copy. ``` ## Administration and statistics `ICacheAdministrator`, registered for the built-in manager, exposes local statistics, methods and entries: ```cs var stats = await admin.GetStatsAsync(); var ratio = stats.Hits + stats.Misses == 0 ? 0 : (double)stats.Hits / (stats.Hits + stats.Misses); Console.WriteLine($"Hit ratio {ratio:P0}, {stats.LocalMethodEntries} local method entries"); Console.WriteLine($"HTTP: {stats.LocalHttpEntries} local responses, {stats.LocalHttpBytes} stored bytes"); Console.WriteLine($"Method weight: {stats.TotalWeight} (configured weight units)"); foreach (var method in admin.GetMethods()) Console.WriteLine($"{method.MethodId}: {method.Options.Duration}"); var entries = admin.ListEntries(tag: "user:42"); await admin.InvalidateTagsAsync(["user:42"]); ``` To read the statistics from outside, such as on a `/health` page, return them as JSON: ```cs // Hits, misses, evictions and entries of this instance, as JSON; protect it like any admin endpoint app.MapGet("/health/cache", async (ICacheAdministrator admin, CancellationToken ct) => Results.Ok(await admin.GetStatsAsync(ct))); ``` `Hits`, `Misses` and `Evictions` are local counters. Compute a hit ratio in the app or dashboard. Storage fields have explicit scopes: | Field | Meaning | |---|---| | `LocalMethodEntries` | Method results resident in this instance | | `LocalHttpEntries` | HTTP representations resident in this instance | | `LocalHttpBytes` | HTTP storage cost in bytes; separate from method weight | | `ObservedDistributedEntries` | HTTP responses this instance recently saw in the distributed cache (at most 1024); not a count of what is stored there | | `TotalWeight` | Resident method weight in the configured weigher's units; one per entry without a weigher | Statistics never serialize results or inspect their properties to estimate bytes. HTTP storage/observation fields remain zero until the separate HTTP store is registered. `GetMethods()` returns each method's `MethodId`, its effective `Options` and the `SettingSources` each setting comes from, and what applies on this instance: `Lifetime`, `Storage`, `KeyParameters` and the result types it kept in memory instead of sharing (`NotShared`) ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)). `ListEntries(storedKeyPrefix, tag, limit, methodId)` and `GetEntry(storedKey)` inspect live local entries without values; listing is a diagnostic scan, not a transaction. `CacheEntryInfo.MethodId` names the method an entry belongs to (`null` for manual entries and HTTP responses), and `ListEntries(methodId: ...)` lists exactly that method's entries. `IMethodCacheKeys.MethodId` returns the id of a call ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md)). `CacheEntryInfo.StoredKey` is the key as stored, which `GetEntry` and `RemoveEntryAsync` take. For a manual entry with a `Version` it includes the version, so it is not the key you pass to `ICacheManager`; there, use the key and version you cached it with. `InvalidateMethodAsync(methodId)` removes every entry of one method, on every instance; an id no cached method has throws an `ArgumentException`. `RemoveEntryAsync`, `InvalidateTagsAsync`, `InvalidateMethodAsync` and `ClearAsync` complete once a configured distributed cache has confirmed the change, and throw `CacheInvalidationQueuedException` when it is applied in memory but still queued for the distributed cache. Its `Result` holds the counts of the invalidation (`null` for `ClearAsync`). The cache retries on its own; don't repeat the call. `GetInvalidationQueues()` reports `Queued` (waiting for the distributed cache) and `PublicationQueued` (waiting for the backplane). A custom or NoOp manager has no built-in method administrator or fabricated storage statistics; with `AddHttpCaching` there is one for HTTP responses only. ## Admin endpoints The `MethodCache.AspNetCore` package exposes administration behind an explicit authorization policy: ```cs builder.Services.AddScoped(); builder.Services.AddMethodCache(); builder.Services.AddHealthChecks().AddMethodCache(); builder.Services.AddAuthorization(o => o.AddPolicy("CacheAdmins", p => p.RequireRole("Admin"))); var app = builder.Build(); app.UseAuthentication(); app.UseAuthorization(); app.MapMethodCacheAdmin("CacheAdmins"); app.MapHealthChecks("/health"); ``` The [package README](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#endpoints) lists the endpoints. `GET methods` shows each method's effective policy and group, and `GET`, `PUT` and `DELETE overrides` list, set and remove [runtime overrides](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#runtime-overrides) for a method, a group or every method, with a body written like a method's entry in `appsettings.json` ([Runtime overrides over HTTP](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#runtime-overrides-over-http)). To record who changes the cache, pass `audit`. It gets the user, what the request removes or overrides (`Kind` and `Targets`), the time and, for an override, who set it and why (`OverrideMetadata`), before the change; when it throws, nothing changes ([Audit](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#audit)): ```cs var audit = app.Services.GetRequiredService().CreateLogger("CacheAdminAudit"); app.MapMethodCacheAdmin("CacheAdmins", audit: (action, cancellationToken) => { // OverrideMetadata is the Owner, Reason, Ticket and ExpiresAt of an override; null for the other kinds audit.LogInformation("{User} ran {Action} on {Targets} at {Time}, reason {Reason}", action.User.Identity?.Name, action.Kind, action.Targets, action.Time, action.OverrideMetadata?.Reason); return ValueTask.CompletedTask; }); ``` Configure your application's authentication scheme as well as the authorization policy. The [web demo](https://github.com/eoniclabs/MethodCache/blob/main/samples/MethodCache.WebDemo) uses cookies and returns 401 for anonymous admin requests and 403 for signed-in callers without the `Admin` role outside Development. It has no sign-in page; its Development environment allows anonymous admin requests so you can try the endpoints locally. It also exposes Development-only `/demo/queries` and `/demo/reset` routes to count source reads and restore the demonstration data; those routes are not part of the MethodCache admin package. ## Health check `AddHealthChecks().AddMethodCache()` reports the selected `failureStatus` (default `Degraded`) when the distributed cache doesn't answer, invalidations are waiting to be retried, or the backplane is connecting or disconnected. The distributed cache and the backplane are reported separately. Reports include `managerCapability`, `statisticsAvailable`, `distributedCacheAvailable` when applicable, `backplaneStatus`, `queued` and `publicationQueued`, plus local storage statistics; the [package README](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#health-check) lists every key. Backend exception text is omitted. An incompatible distributed schema or retention contract reports `Unhealthy` with an actionable safe reason, uses local memory only, and retains invalidations. A safe established retention differing from the configured value reports `Degraded`. Admin mutations return 503 when distributed storage has not confirmed invalidation; the cache continues owning retries. An empty queue and a connected subscription do not acknowledge delivery to every node; backplane delivery remains best effort. ## OpenTelemetry The optional `MethodCache.OpenTelemetry` package provides `AddMethodCacheInstrumentation()` on meter and tracer builders. These extensions only subscribe to Core's instruments; they do not wrap, replace or take ownership of your manager. SDK setup may precede or follow `AddMethodCache()`, and repeated subscriptions do not multiply events. ```cs builder.Services.AddMethodCache(); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing .AddAspNetCoreInstrumentation() .AddMethodCacheInstrumentation() .AddOtlpExporter()) .WithMetrics(metrics => metrics .AddMethodCacheInstrumentation() .AddOtlpExporter()); ``` Each completed cache call has one `methodcache.requests` outcome, `methodcache.result`: `hit`, `miss`, `stale`, `revalidated`, `bypass` or `error`. `methodcache.kind` is `method`, `manual` or `http`, and `methodcache.method` (a method id) or `methodcache.http.client` (a client name) says which. A manual call carries `methodcache.name` when its options name it with `WithName("crm-token")`, and neither otherwise; give the calls that cache one kind of value one fixed name, since each name is its own series. Every attribute is in the `methodcache.` namespace, apart from `error.type`. `methodcache.load.duration` measures your method when it actually runs, background refreshes included; callers that join a running load and values read from the distributed cache record none. A bulk call has one outcome and measures its one batch factory call. Histograms use seconds, with bucket boundaries from 5 ms to 10 s. Local entry/HTTP byte instruments are observable up-down counters. `methodcache.evictions` counts the entries an instance removed because its memory cache was full (`MaxItems` or `WeightLimit`), by `methodcache.kind`; expired and invalidated entries aren't in it. Invalidation counters count distinct targets at each stage, not operation totals; do not add stages together. See the [full instrument table](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.OpenTelemetry/README.md#metrics). Spans cover runs of your method, individual distributed operations and invalidation. Pure hits have no spans. Keys and tags require explicit Core options; keys are hashed by default when enabled. Metrics never include keys, tags, URLs, user ids or tenant ids. MethodCache adds no baggage and copies no HTTP or URL attributes; your application's own activity context and baggage flow as usual. ### Hit ratio per method `methodcache.requests` carries the method and the outcome, so a dashboard computes the hit ratio of each method. With OpenTelemetry's Prometheus exporter, which writes the names with underscores: ```promql sum by (methodcache_method) (rate(methodcache_requests_total{methodcache_kind="method", methodcache_result="hit"}[5m])) / sum by (methodcache_method) (rate(methodcache_requests_total{methodcache_kind="method"}[5m])) ``` With prometheus-net ([Standard .NET listeners](#standard-net-listeners)), the series is `methodcache_methodcache_requests`, without `_total`. It is a gauge that holds the running total, so `rate` works on it as on a counter: ```promql sum by (methodcache_method) (rate(methodcache_methodcache_requests{methodcache_kind="method", methodcache_result="hit"}[5m])) / sum by (methodcache_method) (rate(methodcache_methodcache_requests{methodcache_kind="method"}[5m])) ``` `methodcache_method` is the full method id, such as `[MyApp.Api]MyApp.Api.Services.IPriceSource.GetRateAsync`, so that two methods with the same name in different assemblies never share a series. For a shorter name on a dashboard, copy the interface and method into a label of their own with `label_replace`: ```promql label_replace( sum by (methodcache_method) (rate(methodcache_requests_total{methodcache_kind="method"}[5m])), "method", "$1", "methodcache_method", `.*\.([^.]+\.[^.]+)`) ``` Or do it once when Prometheus scrapes, in the job's `metric_relabel_configs`: ```yaml metric_relabel_configs: - source_labels: [methodcache_method] regex: '.*\.([^.]+\.[^.]+)' target_label: method replacement: '$1' ``` A `bypass` (caching turned off for the call) counts as a request that wasn't a hit; leave it out with `methodcache_result!="bypass"` in the second sum to see the ratio of the calls the cache could answer. A `stale` result is an old value fail-safe returned because the method failed or took longer than `FailSafeTimeout`. A method whose ratio is low while `methodcache.evictions` rises needs a larger memory cache; one whose ratio is low without evictions is called with different arguments each time, or its entries expire before they are read again. ## Standard .NET listeners OpenTelemetry is optional. The meter and activity source are named `MethodCache` (`MethodCacheTelemetry.Name`), so `dotnet-counters monitor --counters MethodCache` and any `MeterListener` see them. For Prometheus, use OpenTelemetry's Prometheus exporter with `AddMethodCacheInstrumentation()`. prometheus-net 8 exports them too, with no MethodCache setup: its meter adapter puts the meter name in front, as in `methodcache_methodcache_requests{methodcache_result="hit"}`. It starts listening at the first scrape, exports counters as gauges and uses its own histogram buckets instead of the ones above; OpenTelemetry's exporter keeps both. With a `CollectorRegistry` of your own, start the meter adapter with the registry and a metric factory for it. With only `Registry` set, no MethodCache series appear. The adapter exports every meter in the process unless you filter it, so pass `InstrumentFilterPredicate` to export MethodCache's alone: ```cs // A registry of your own needs both settings: with only Registry, no MethodCache series appear var adapter = MeterAdapter.StartListening(new MeterAdapterOptions { Registry = registry, MetricFactory = Metrics.WithCustomRegistry(registry), // Without a filter the adapter exports every meter in the process, ASP.NET Core's and the runtime's too InstrumentFilterPredicate = instrument => instrument.Meter.Name == MethodCacheTelemetry.Name, }); ``` With prometheus-net's default registry, set the same filter at startup with `Metrics.ConfigureMeterAdapter(o => o.InstrumentFilterPredicate = ...)`. Start the adapter in `Program.cs` and keep what it returns. Started from a hosted service of your own instead, it exports nothing in a test host that removes hosted services, as some `WebApplicationFactory` setups do. A `MeterListener` subscribes like this; keep it alive for as long as you want measurements: ```cs builder.Services.AddMethodCache(); using var listener = new MeterListener(); listener.InstrumentPublished = (instrument, active) => { if (instrument.Meter.Name == MethodCacheTelemetry.Name) active.EnableMeasurementEvents(instrument); }; listener.SetMeasurementEventCallback((instrument, value, _, _) => Console.WriteLine($"{instrument.Name}: {value}")); listener.Start(); // keep the listener alive for as long as measurements are needed ``` The privacy options are set in `AddMethodCache` and apply whatever listens: ```cs // Core emits standard Meter and ActivitySource instruments builder.Services.AddMethodCache(mc => mc.Telemetry(options => { options.RecordCacheKeys = false; options.RecordCacheTags = false; })); ``` With your own `ICacheManager`, MethodCache still measures whether a cached method's factory ran; anything else your manager does is its own to instrument. --- # Memory cache The in-memory cache uses W-TinyLFU eviction: when it is full, it keeps the entries that are read often and evicts the rest, so a burst of one-off reads doesn't push out your hot data. Configure it with `mc.Memory(o => ...)`, which sets `MethodCacheMemoryOptions`: ```cs builder.Services.AddMethodCache(cache => cache .Defaults(o => o.WithDuration(TimeSpan.FromMinutes(10))) .Memory(o => { o.MaxItems = 50_000; // default 10,000 o.JitterMaxDuration = TimeSpan.FromSeconds(30); // spread out entries created together o.CacheNullValues = false; // a null result means "try again next time" })); ``` | Option | Default | What it does | |--------|---------|--------------| | `MaxItems` | 10,000 | The most entries kept, also when a `Weigher` is set | | `WeightLimit` | 1000 MB | The most total weight kept; needs a `Weigher` | | `Weigher` | none | Returns an entry's cost, for example its size in bytes | | `MaxExpiration` | 7 days | No entry lives longer: a longer `Duration` fails where it is set. At most 365 days | | `JitterMaxDuration` | zero | Adds a random extra lifetime up to this value, so entries created together don't expire together | | `CacheNullValues` | `true` | Caches `null` results like any other value | | `MaxHttpBytes` | 100 MiB | The most bytes the HTTP response cache keeps in memory, bodies and headers included. Shared by all HTTP clients and separate from `MaxItems` and `WeightLimit` | Each `mc.Memory` call changes only the options it sets, in the order of the calls. A host that shares its setup with others, such as through an extension method of your own, can add a call of its own after it, such as a `Weigher` and `WeightLimit` for its large reports, and keep the shared `MaxItems`. Method defaults are set with `Defaults.WithDuration`; unset defaults use five minutes. Cleanup, statistics and the generated fast path are always enabled. ## How a call is answered ```mermaid flowchart LR A([Call a cached method]):::dark --> B{In memory?} B -- yes --> R([Return the same instance]):::amber B -- no --> C[Concurrent callers with the
same key share one call]:::light C --> E[Run your method]:::dark E -- returns --> F[Store it, unless CacheWhen
or CacheNullValues rejects it]:::light --> R E -- throws --> X(["Nothing is stored: the caller gets
the exception or a fail-safe value"]):::dark classDef dark fill:#1E1B3A,stroke:#1E1B3A,color:#F5F3FF classDef amber fill:#FFB020,stroke:#FFB020,color:#1E1B3A classDef light fill:#F5F3FF,stroke:#1E1B3A,color:#1E1B3A ``` ## Bounding by size Object sizes can't be measured reliably at runtime, so to bound the cache by memory you say what an entry costs: ```cs builder.Services.AddMethodCache(cache => cache.Memory(o => { o.WeightLimit = 256 * 1024 * 1024; // bound the cache by total size as well as by count o.Weigher = MethodCacheWeigher.Bytes; // strings and arrays such as float[] by size, other values 64 })); ``` `MethodCacheWeigher.Bytes` gives an entry its approximate size in bytes: two per character of the key and of a string value, and the size of an array of numbers, `bool` or `char`, such as four bytes per `float` of a `float[]` embedding. Any other value weighs 64 (`MethodCacheWeigher.OtherValue`), and `null` nothing. When your results are mostly records of your own, give them about the size of a typical one: ```cs builder.Services.AddMethodCache(cache => cache.Memory(o => { o.WeightLimit = 256 * 1024 * 1024; // Results are mostly records of about 1 KB: weigh each as 1024, strings and arrays by size o.Weigher = MethodCacheWeigher.Bytes(otherValue: 1024); })); ``` The key is weighed on top of `otherValue`, as for every value, so a record weighs 1024 bytes plus two per character of its key. Allow for that when you choose `WeightLimit`. To weigh your own types more closely, weigh them yourself and leave the rest to it: ```cs builder.Services.AddMethodCache(cache => cache.Memory(o => { o.WeightLimit = 256 * 1024 * 1024; // Weigh your own types, and let MethodCacheWeigher weigh the rest o.Weigher = (key, value) => value is Report report ? report.Rows.Sum(row => row.Length * 2L) : MethodCacheWeigher.Bytes(key, value); })); ``` With a distributed cache, this is also how large, rarely read values, such as reports, stay out of memory without leaving the distributed cache: when the limit is reached, the entries read least often are evicted first, and the next read of one gets it from the distributed cache, not from your method. There is no separate duration for memory: the entry's `Duration` applies to both. The weigher must be fast, thread-safe and return a non-negative value. Both limits apply: an entry is evicted as soon as either `MaxItems` or `WeightLimit` is reached, so raise `MaxItems` too when many small entries should fit. Setting `WeightLimit` without a `Weigher` fails at startup, since there is nothing to weigh entries with. The first time the cache is full and removes an entry to make room, MethodCache logs one warning that names the limit it reached. A full cache is normal when the limit is what you want; when entries are removed before they expire, and the hit ratio in `GetStatsAsync` drops, raise `MaxItems` (or `WeightLimit`). The `methodcache.evictions` counter shows how many entries were removed to make room ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#opentelemetry)). ## Memory statistics `GetStatsAsync().TotalWeight` reports the resident method weight in the configured weigher's units. Without a weigher, every method entry weighs one; a large returned object does not turn this field into bytes. `LocalMethodEntries` reports the actual local entry count. Statistics never serialize results or inspect user properties, and there are no sampling/accurate-estimation modes. HTTP entries and bytes use separate fields and budgets. ## How strict the bound is Cache hits never wait for eviction. It runs in batches off the read path, so a new entry is stored at once and counted against `MaxItems` and `WeightLimit` when the next batch applies it. Under any load: - The counted size or weight is never more than one entry over the bound. - When writers get ahead of eviction, they wait for it and help with it, so at most `16 × processor count` (at least 64) inserts, plus two per writing thread, are stored but not yet counted. Moments after the writes stop, the cache is back within the bound. ## Null values `null` results are cached by default, so a method that returns `null` isn't run again on every call. Set `CacheNullValues = false` when `null` means "not there yet" and the next call should try again, or use [`CacheWhen`](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md) for one method. ## Cached objects are shared > [!WARNING] > The cache stores the object your method returned and hands the same instance to every caller. Don't change a cached > object; return immutable types such as records, or copies. Build warning [MC0043](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0043) names code that changes a cached result, and with a distributed cache, a warning in the Development log names the method whose cached value changed ([Results that don't change](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#results-that-dont-change)). --- # Native AOT MethodCache works in Native AOT and trimmed applications when your cached methods take arguments the decorator can write into the key itself (see [Keys](#keys) below). The source generator writes the decorators, their registration and those keys at build time. CI publishes a test application with Native AOT on every change and checks that caching (with simple, record, collection and `ICacheKeyProvider` arguments), explicit `AutoRegister(ServiceLifetime)` registration and `[assembly: CacheInterface]` work. CI also compiles the complete supported signature corpus with Native AOT. This checks generated signatures and ref safety across all key forms; reflection-based fallback cases retain the runtime limitations described below. ## In-memory caching Nothing to do: the in-memory cache stores your objects as they are, without serializing them. ## Distributed caching Values written to Redis, SQL Server or PostgreSQL are serialized with System.Text.Json. Under Native AOT it needs a `JsonSerializerContext` that lists every type your cached methods return: ```cs [JsonSerializable(typeof(Product))] [JsonSerializable(typeof(List))] // every type a cached method returns public sealed partial class ShopJsonContext : JsonSerializerContext; ``` ```cs builder.Services.AddMethodCache(mc => mc .UseRedis("localhost:6379") .UseJson(ShopJsonContext.Default)); ``` Select your context with `MethodCacheBuilder.UseJson(context)`. MethodCache cannot generate this context for you, because one source generator can't see another generator's output. ## Keys Under Native AOT, give cached methods arguments that the decorator writes into the key itself: - simple values (strings, numbers, `bool`, `Guid`, dates, enums), - records, classes and structs whose public properties and fields are simple values, passed as exactly the declared type (a sealed type is safest: an instance of a derived class goes through the key generator), - types that implement `ICacheKeyProvider`, - arrays, lists and sets of those (records and classes in them must be sealed), and dictionaries whose keys and values are simple values. Collection subclasses with their own public state also use the key generator; implement `ICacheKeyProvider` on these types when using Native AOT. Plain lists, arrays and sets keep their inline keys. Other arguments, such as interfaces, `object` or collections of collections, go through the key generator, which serializes them with reflection-based System.Text.Json. Publishing then reports trim and AOT warnings (IL2026, IL3050) from `MethodCache.Core`, and the call throws `InvalidOperationException` at runtime. Wrap such an argument in a type that implements `ICacheKeyProvider`, as `TenantId` does in [Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#types-whose-state-is-private). --- # Testing The implementation of a cached interface is a plain class: create it directly in unit tests and no caching is involved. ## Testing with caching To test the caching itself, such as invalidation tags, build a service provider the way the application does: ```cs var services = new ServiceCollection(); services.AddSingleton(); services.AddScoped(); services.AddMethodCache(); var provider = services.BuildServiceProvider(); // Resolved through the generated decorator, exactly as in the application var products = provider.CreateScope().ServiceProvider.GetRequiredService(); ``` `ICacheAdministrator` from the same provider lists the entries and their keys, which helps when a test needs to check what was cached ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). ## Replacing a cached service with a fake A `WebApplicationFactory` that swaps a cached service for a fake registers the fake after the application's `AddMethodCache()`. Call `AddMethodCache()` again after it, so the fake gets a decorator like the service it replaces: ```cs // In a WebApplicationFactory: ConfigureTestServices runs after the app's AddMethodCache() builder.ConfigureTestServices(services => { services.AddScoped(); services.AddMethodCache(); // again, so the fake gets a decorator like the service it replaces }); ``` Without the second call, the first cached service the test resolves fails with an error that says to register the service before `AddMethodCache()` or call it again. The fake's results are cached like the real service's; when a test changes what the fake returns, also register `NoOpCacheManager` ([Turning method caching off](#turning-method-caching-off)). ## Counting loads and invalidations The `MethodCache.Testing` package records what the cache does. Add it to the test project at the same version as `MethodCache`, and call `AddMethodCacheTesting()`: it registers a `CacheRecorder` and a `FakeTimeProvider` as the container's clock. ```cs var services = new ServiceCollection(); services.AddSingleton(); services.AddScoped(); services.AddMethodCache(); services.AddMethodCacheTesting(); // a fake clock and a recorder await using var provider = services.BuildServiceProvider(); var recorder = provider.GetRequiredService(); var time = provider.GetRequiredService(); var products = provider.CreateScope().ServiceProvider.GetRequiredService(); await products.GetAsync(42); await products.GetAsync(42); Assert.Equal(1, recorder.Loads(p => p.GetAsync(42, default))); // the second call was a hit await products.UpdateAsync(42, new Product(42, "Green tea", 5m)); Assert.Contains("product:42", recorder.InvalidatedTags); await products.GetAsync(42); Assert.Equal(2, recorder.Loads(p => p.GetAsync(42, default))); time.Advance(TimeSpan.FromMinutes(11)); // past the Duration of 10 minutes await products.GetAsync(42); Assert.Equal(3, recorder.Loads(p => p.GetAsync(42, default))); ``` `Loads` counts how many times one call, with these arguments, ran your implementation: its misses, refreshes and reloads after an invalidation. `InvalidatedTags` and `InvalidatedKeys` list what was invalidated, in order, by `[CacheInvalidate]` methods, `ICacheManager` calls and `MethodCache.EntityFrameworkCore`. `Clear()` forgets what the test's setup recorded. The recorder sees the built-in cache manager only: with `NoOpCacheManager` or your own `ICacheManager`, it records nothing. ## When a test writes to the database directly A test that changes data without going through a `[CacheInvalidate]` method, such as seeding rows or calling a repository, leaves the cached results as they were. Clear the cache after the write, or invalidate what it changed: ```cs await database.SaveAsync(changed); // the test changes the data behind the cache's back // Remove everything cached... await provider.GetRequiredService().ClearAsync(); // ...or only what the write changed var cache = provider.GetRequiredService(); var keys = provider.GetRequiredService(); await cache.InvalidateTagAsync(keys.Tag(p => p.GetAsync(changed.Id, default), "product:{id}")); ``` `ClearAsync` also removes the entries from a distributed cache and the other instances, so use a cache of the test's own (a new service provider, or its own `KeyPrefix`) when tests run in parallel against a shared Redis or database. ## Proving that a result is cached A test that changes a row and reads it again proves caching only when the change doesn't invalidate. With `MethodCache.EntityFrameworkCore`, a save through the connected context invalidates, so the second read is fresh whether or not it is cached. Count the runs of your implementation with `recorder.Loads` instead, as above. To test the stale value itself, change the row past MethodCache: with SQL, or through a context type that isn't connected to MethodCache, over the same database. With EF Core's in-memory provider, give both contexts the same `InMemoryDatabaseRoot`. ## Every cached service resolves A service registered after `AddMethodCache`, or one with a dependency the container lacks, fails when the application starts or on its first call. `CachedServices.ProblemsAsync` finds it in a test: it resolves each registered service with cached methods, in a scope of its own, and checks that it is the generated caching decorator: ```cs // Every service with cached methods resolves, and to its generated caching decorator Assert.Empty(await CachedServices.ProblemsAsync(provider)); ``` Each problem names the service, its key for a keyed registration, and what is wrong: registered after `AddMethodCache`, an exception when it is resolved, or an instance that isn't the decorator, so its calls aren't cached. Build the provider as the application does, with its own registrations, so the test resolves what the application resolves. A service registered with an open generic type, such as `typeof(IRepository<>)`, is skipped. When the provider has no service with cached methods, such as the wrong provider, it throws `InvalidOperationException` instead of returning an empty list, so the test can't pass without checking anything. When resolving the services needs a database, a key vault or other infrastructure the test doesn't have, `CachedServices.RegistrationProblems` checks the registrations only and resolves nothing: ```cs // Every service with cached methods is registered before AddMethodCache; resolves none of them Assert.Empty(CachedServices.RegistrationProblems(provider)); ``` It finds a service registered after `AddMethodCache`, the most common mistake, but not a dependency the container lacks. Both methods take the provider the application builds, so whatever its registration code does still runs: a client that connects to its database while it is registered needs that database in the test too. Neither method can see a service that is never registered: it has no registration to check. `CachedServices.Registered` lists the services with cached methods that the provider registers, each once and ordered by full name, so a test can compare it with the services the application should have: ```cs // The application registers exactly these services with cached methods, none forgotten Assert.Equal([typeof(IProductService)], CachedServices.Registered(provider)); ``` A list written by hand goes stale when someone adds a cached interface and forgets to register it, which is the mistake the test is there for. `CachedServices.Declared` lists the interfaces with cached methods in the assemblies you pass, in the same order, so the test covers a new interface without a change: ```cs // Every interface with cached methods in the application's project is registered Assert.Equal(CachedServices.Declared(typeof(IProductService).Assembly), CachedServices.Registered(provider)); ``` When the cached interfaces are in several projects, such as the modules of a modular monolith, pass the assembly of each project the application is built from: ```cs // The cached interfaces are in the modules the application is built from: pass each module's assembly Assert.Equal( CachedServices.Declared(typeof(TenancyModule).Assembly, typeof(BillingModule).Assembly), CachedServices.Registered(provider)); ``` `Declared` lists every interface with cached methods in an assembly, also those another application registers. When the application uses a few interfaces from a shared library that declares others, pass its own assemblies and add the interfaces it uses from the library: ```cs // The application's own cached interfaces, and the one it uses from a shared library that declares others var expected = CachedServices.Declared(typeof(IProductService).Assembly) .Append(typeof(ICurrencyRates)) .OrderBy(type => type.FullName, StringComparer.Ordinal); Assert.Equal(expected, CachedServices.Registered(provider)); ``` What a host already checks: when a host built with `WebApplicationFactory` or `Host.CreateApplicationBuilder` starts, `AddMethodCache` fails it for a service registered after `AddMethodCache`, so a test that starts the host finds that mistake without these methods. `ProblemsAsync` adds what starting the host doesn't check: it resolves every cached service, keyed ones too, so a missing dependency fails the test, and it works on a provider built without a host. A minimal API endpoint that takes a cached interface as a parameter fails the host first when that interface isn't registered ("Body was inferred but the method does not allow inferred body parameters"), so a test that starts the host fails with that error before it reaches `Registered`. ## Settings that conflict Some settings are allowed on their own but conflict with a setting from another place, and the host logs a warning when it starts instead of failing: a `RefreshAhead` or sliding window not shorter than the `Duration` it ends up with, such as `RefreshAhead` on the method and `Duration` in `Defaults`, or a group with settings that no cached method is in, usually a misspelt name. `CachedServices.Warnings` returns the same warnings, so a test fails on them instead of a log line nobody reads: ```cs // No setting conflicts with another, so the host logs no MethodCache warning when it starts Assert.Empty(CachedServices.Warnings(provider)); ``` Each warning is the message the host logs, with the method id or group filled in. Build the provider with the application's configuration, `appsettings.json` too, since the conflicts are between layers. It throws `InvalidOperationException` when the provider has no `AddMethodCache`. ## Every tag has an invalidation A tag that nothing invalidates keeps its entries until they expire. `TagCoverage.Uninvalidated` lists the tags of the cached methods, from attributes, startup code and configuration, that nothing invalidates. It counts the `[CacheInvalidate]` methods of the registered services, the entity mapping of [`MethodCache.EntityFrameworkCore`](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md), and the invalidations in the projects the test project references: ```cs // Every tag of a cached method has a [CacheInvalidate] method, an EF Core mapping or an invalidation in a referenced project Assert.Empty(TagCoverage.Uninvalidated(provider)); ``` When MethodCache builds a project, it writes the tags the project invalidates into its assembly: `[CacheInvalidate]` tags, and the tags its code passes to `InvalidateTagAsync`, `InvalidateTagsAsync`, `InvalidateAfterCommit`, the entity mapping or a helper marked `[InvalidatesCache]`, as constants, interpolated strings or `Tag(...)` calls. `TagCoverage` reads them from the assemblies next to the tests, so a tag the API caches and a worker invalidates is covered when the test project references the worker. The test project's own invalidations don't count. A tag marked `InvalidatedElsewhere` ([In another application](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#in-another-application)) is covered only when a referenced project invalidates it. Otherwise it is reported, with `MarkedInvalidatedElsewhere` set, so the mark can't hide a tag that nothing invalidates any more. Reference the project that invalidates it, or, when it is invalidated outside the solution, such as by another team's application or a database trigger, name it in `alsoInvalidatedBy`. A tag marked `InvalidatedManually` ([Cleared by hand](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#cleared-by-hand)) is covered without a check: an operator clears it, so there is no invalidation to find. Mark it on `[Cache]` rather than listing it in `alsoInvalidatedBy`, so analyzer MC0028 and the test read the same mark. Name the tags your code invalidates in ways no project shows, such as a tag built in a variable: `TagCoverage.Uninvalidated(provider, alsoInvalidatedBy: ["price:{provider}:{model}"])`. A placeholder matches any value, so `"product:{id}"` covers `"product:{Id}"` and `"product:42"`. Analyzer [MC0028](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0028) checks the same within one project while you build; this check sees the whole application, including the tags in configuration. ## How each method is cached `CachedServices.Method` returns how one method is cached: what `GetMethods()` reports for it ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)), found by a call instead of a `MethodId` string, so a renamed method or service still finds it. Assert on it, so a change to its duration, its key or where its values are kept fails a test: ```cs // How ListAsync is cached, from its attribute, startup code and configuration together var list = CachedServices.Method(provider, p => p.ListAsync(Guid.Empty)); Assert.Equal(TimeSpan.FromMinutes(5), list.Lifetime.Duration); Assert.Equal(["tenantId"], list.KeyParameters); Assert.Empty(list.ReplacedSources); // no source replaces what another one sets for it ``` The call runs on a stand-in, so the method never runs and the arguments don't matter: pass `""`, `0`, `Guid.Empty` or `default`. `ReplacedSources` is empty when no source replaces a setting another one sets for the method. When startup code replaces one on purpose, assert which source applies and which one it replaces, so a test fails when either changes. Here a `DurationFor` gives each result its own duration in place of the `Duration` of its `[Cache]`: ```cs // An archived project changes rarely: its own duration, in place of the 10 minutes of its [Cache] mc.Method((IProjects p) => p.GetAsync(Any.Value, Any.Value, default)) .DurationFor(project => project.Archived ? TimeSpan.FromHours(1) : TimeSpan.FromMinutes(10)); ``` The test: ```cs // GetAsync's duration comes from startup code, which replaces the Duration of its [Cache] on purpose var get = CachedServices.Method(provider, p => p.GetAsync(Guid.Empty, 0, default)); Assert.Equal(CacheSettingSource.Code, get.SettingSources["Duration"]); Assert.Equal([CacheSettingSource.Attribute], get.ReplacedSources["Duration"]); ``` `SettingSources` and `ReplacedSources` name each source with `CacheSettingSource`: `Attribute`, `Code`, `Configuration` or `RuntimeOverride`. The attribute's `Duration` then caps nothing: a cap belongs in the function. To see every change to how the application caches in review, write all the policies as JSON and compare them with a file kept in the repository, with a library such as Verify that compares output with an approved file, or by hand: ```cs // Every method's policy as JSON: compare it with a file in the repository, so a change shows up in review var policies = JsonSerializer.Serialize(provider.GetRequiredService().GetMethods(), new JsonSerializerOptions { WriteIndented = true }); ``` `NotShared` counts the values this instance kept in memory while it ran, so write the JSON before the test calls any cached method. ## A load for another tenant fails A cached method that takes the tenant as a parameter and checks it against the request's tenant with a `[ChecksRequestState]` method ([MC0026](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0026)) should fail for another tenant's id. Test it with the request set to one tenant and a call for another: ```cs await using var scope = provider.CreateAsyncScope(); scope.ServiceProvider.GetRequiredService().Id = tenantA; // the request is tenant A's var projects = scope.ServiceProvider.GetRequiredService(); // A load for tenant B fails in the check, so nothing is cached under B's key await Assert.ThrowsAsync(() => projects.ListAsync(tenantB)); ``` The check runs when the method loads a value, not on a hit, so this test proves that nothing wrong is cached under another tenant's key. That a caller takes the id from the request is the caller's part; test it where the id is taken, such as in the endpoint. Values of one tenant are kept apart from another's only when the tenant is part of the key. Check that for every cached method with `KeyParameters`, leaving out the few that serve every tenant, found by a call as above: ```cs // The methods that serve every tenant, such as the API key lookup, found by a call string[] everyTenant = [CachedServices.Method(provider, k => k.FindAsync("", default)).MethodId]; foreach (var method in provider.GetRequiredService().GetMethods()) { if (everyTenant.Contains(method.MethodId)) continue; Assert.True(method.KeyParameters is ["tenantId", ..], $"{method.MethodId} doesn't key on the tenant first."); } ``` A method added later without the tenant fails the test, and so does a parameter renamed from `tenantId`: rename it in the test too. ## Turning method caching off Register `NoOpCacheManager` after `AddMethodCache()` and every call reaches your implementation: ```cs var services = new ServiceCollection(); services.AddSingleton(); services.AddScoped(); services.AddMethodCache(); services.AddSingleton(); // after AddMethodCache: every call reaches ProductService ``` For code that uses [manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md), pass a `NoOpCacheManager` directly, or mock the four operations on `ICacheManager` (the short forms are extension methods that call them): ```cs ICacheManager cache = new NoOpCacheManager(); // never caches: the factory runs on every call var reader = new OrderReader(cache, repository); ``` `NoOpCacheManager` is in the `MethodCache` namespace. It turns off method caching only; responses of an `HttpClient` with `AddHttpCaching` are still cached. ## Time > [!TIP] > The cache reads the time from the `TimeProvider` registered in the container, if there is one. Register a fake > `TimeProvider`, such as the `FakeTimeProvider` that `AddMethodCacheTesting()` registers, to test expiration without > waiting. > This includes the background cleanup of the memory cache and, with `MethodCache.HttpCaching`, response freshness, > eviction and the background revalidation timeout. --- # Security What each package protects against, what it leaves to you, and the tests that hold it to that. ## MethodCache (keys, tags, invalidation) | Threat | What MethodCache does | |---|---| | A caller crafts an argument (`"1:orders"`, `"a)"`, a newline) so that their call gets another call's key and its cached result | Keys separate arguments unambiguously: string parts escape `\` and `:`, `null` is `\0`, records are `(a:b)` with escaped members, and hashed keys length-prefix every value and record the runtime type of values in `object`, base-class or interface slots (`1` and `1L` in an `object[]` differ). JSON and MessagePack key-provider parts and nested strings preserve exact UTF-16 code units, including lone surrogates. Building a key that itself builds keys (an `ICacheKeyProvider`, a getter) can't change another call's key. Arguments whose only state is private, including fields inherited from base classes, are rejected rather than hashed as an empty object. Framework types are written by their value (`BigInteger`, `IPAddress`, `JsonElement` and the others in [Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#framework-types)), not by public properties such as `BigInteger.Sign`, and any other type from .NET, ASP.NET Core or Microsoft.Extensions in a key, such as `StringBuilder`, is build error MC0019. Overloaded methods include the namespaces of their parameter types, so equally named types from different namespaces cannot share a method identity, and a method name that two interfaces of one hierarchy declare adds the parameter types (and the declaring interface for equal signatures) to the key, so `ILookup.Find(int)` and `ICatalog.Find(string)` cannot share an entry through the `ICatalog` decorator. A collection subclass's own public properties are part of the key, with its elements. No argument list produces another method's key or another argument list's key. Fluent versions have a separate namespace, with reserved user-key prefixes escaped, so a crafted raw key cannot reach a versioned entry. | | Two service libraries declare identical namespace/type names | Generated service keys and policy ids include the assembly simple name, without its version; keyed-service enum types, closed generic arguments and fallback runtime types (including nested object values) also include assembly identity. Assembly-name delimiters are escaped. `AssemblyKeySecurityTests` and the cross-assembly SignatureCorpus regression verify separate values and overrides. Libraries with the same assembly identity are trusted as the same logical library; this is not isolation between AssemblyLoadContexts. | | An argument that is a secret ends up readable | Keys contain argument values in plain text (hashed keys are not encryption) and appear in the admin endpoints and, if you turn them on, in traces. Don't cache methods that take passwords or tokens; pass an id, or wrap a token that identifies the result (a URL with a SAS token, say) in a type whose `ICacheKeyProvider` returns a hash of it ([Secrets in arguments](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#secrets-in-arguments)). | | A dynamic tag argument impersonates another argument | Dynamic placeholders use canonical key parts: null has its own marker, strings escape colons and backslashes, enums use invariant numbers, and dates keep their full precision. Static template text stays literal. Tags remain an application-defined shared invalidation namespace; they are not an authorization boundary. | | A load races invalidation and a newer write | Invalidated loads cannot publish over newer entries, even when custom weight calculation stalls or re-enters the cache. Existing callers may finish with their pre-invalidation result; later loads and writes retain their own entry. | | A tag built from user text clears the whole distributed cache | The distributed cache stores every character of a tag exactly, lone surrogates included, so a tag never turns into another one. A tag is only ever its own tag, whatever characters it holds; the internal "clear everything" marker can't be named by a tag. | | `*` or `?` in user text widens an invalidation | `InvalidateTagsAsync`, `InvalidateKeysAsync` and admin endpoints match exact keys and tags. Group invalidation uses an explicit common tag. | | A tenant ID is missing from the cache key or invalidation scope | The console tenant example passes an explicit `Guid` tenant ID in the method arguments and tag, and `DemoTenantSecurityTests` verifies distinct results and selective invalidation. Applications must derive and authorize that tenant from the caller's identity. | ## Distributed cache (Redis, SQL Server, PostgreSQL) | Threat | What MethodCache does | |---|---| | Corrupt, truncated or crafted bytes in the distributed cache | Read as a miss and loaded again: never an exception for the caller, never a `null` that wasn't stored, and lengths in the data are checked against its size before anything is allocated. | | Stored data names a type to create (deserialization gadgets) | `JsonCacheSerializer` reads the method's declared type and ignores `$type`. `MessagePackCacheSerializer` uses the contractless resolver with `MessagePackSecurity.UntrustedData` and refuses typeless payloads. Keep it that way if you pass your own options. | | Someone who can write to Redis, SQL Server or PostgreSQL | **Not prevented.** They can store any well-formed value, which every instance will serve. The distributed cache is trusted: protect it like your database (authentication, TLS, network rules), and give each application its own `KeyPrefix`. Different keys never share an entry: Redis escapes characters UTF-8 can't hold, and SQL Server hashes each exact key, so collation can't make two keys equal (casing, NULs, trailing spaces). SQL Server keeps each prefix's invalidations apart independently of collation too. PostgreSQL stores every key, and each prefix's backplane scope, as the SHA-256 of its exact UTF-16 code units, so NULs and lone surrogates (which PostgreSQL text can't hold) stay distinct. Its notifications carry only the sender's id; the invalidations themselves are read from the table. | | Invalidations evicted from the store | A store that evicts a tag or removal stamp under memory pressure makes the entries it invalidated valid again (for example data cached before a permission change). Run Redis with `maxmemory-policy noeviction` or a Redis of its own; see [Keep invalidations from being evicted](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#keep-invalidations-from-being-evicted). | | Runtime overrides stored in the distributed cache | With a backplane, runtime overrides are records in the distributed cache that every instance applies, so someone who can write to it can also change any cached method's duration, tags or settings on every instance, or turn its caching off. An override never holds code: records carry only settings, the functions (`CacheWhen`, `DurationFor`, `TagsFor`, `SlidingFor`) are refused, and a record an instance can't read or apply is skipped with a warning. `SharedRuntimeOverridesTests` checks both. | | Backplane messages | Carry keys and tags in lossless UTF-16 frames, so lone surrogates cannot change invalidation identity and newlines cannot forge another message type. Messages from another MethodCache version are rejected with one warning, without logging their contents. Anyone who can publish on the channel can invalidate entries, so the same trust applies. | ## MethodCache.AspNetCore (admin endpoints) | Threat | What MethodCache does | |---|---| | An endpoint reachable without authorization | `MapMethodCacheAdmin` requires an authorization policy name, and every endpoint it maps requires that policy: anonymous callers get 401, signed-in users without it 403. A test reads the app's route table and checks every mapped endpoint, so a new endpoint without the policy fails a test. | | The web demo is started outside Development | It requires cookie authentication and the `Admin` role, returning 401/403 for refused requests. Only Development permits anonymous admin access. `WebDemoSecurityTests` starts the actual sample and checks every admin route in both environments. The sample has no sign-in page; deployed applications must configure their own authentication. | | Demo data can be reset outside Development | `/demo/reset` and `/demo/queries` are mapped only in Development. The sample tests verify that Production returns 404 for both. | | A web demo price update omits a price or supplies null/negative input | The endpoint returns 400 before writing or invalidating. `WebDemoInputTests` verifies stored and cached products stay unchanged, and checks zero and the maximum decimal as valid boundaries. | | A cross-site form or `fetch` without preflight calls `invalidate`, `invalidate-method`, `clear` or `overrides` with the admin's cookie | The `POST` and `PUT` endpoints only accept an `application/json` body, which a browser sends cross-site only after a CORS preflight; forms and `text/plain` get 415, and a request without a body 400. `DELETE entry`, `DELETE overrides` and `PUT` need a preflight too. Don't add a CORS policy that allows these routes from other origins. | | An admin changes caching for every method or a group by mistake | `PUT overrides` must name exactly one of `MethodId`, `Group` or `"All": true`, a group must have cached methods, and an override is checked against every method it reaches before any of them changes, so a typo or a bad value is 400 and changes nothing. The body is read like a configuration file: unknown settings and empty values are 400. Each change goes to `audit` first. `DELETE overrides` needs exactly one of `methodId`, `group` or `all=true`. | | An override body as a denial of service | The body is read up to 64 KB; a longer one is 400. | | A filter in the wrong place empties the whole cache | Emptying everything is its own endpoint, `POST clear`, which takes only `{}`: a body with any property, such as `{ "tags": [...] }`, is 400. `invalidate` takes only `tags` and `invalidate-method` only `methodId`, and an unknown query parameter is 400 on every endpoint, so a misplaced filter is rejected instead of ignored. | | `invalidate-method` removes another method's entries | The `methodId` must be exactly the id of a cached method, as `methods` lists it; anything else is 400 and removes nothing. Entries are matched by the method they belong to, not by a key prefix, so `GetUser` never reaches `GetUsers`. | | An admin removes entries without a trace | Pass `audit` to `MapMethodCacheAdmin`: it gets the user, the action, its targets and the time for every change, before the change, and a throwing audit fails the request without changing anything. Reads and rejected requests aren't audited. Store the records where admins can't edit them. | | Cached values leak through the admin API | Entries are listed with stored key, method id, value type, age, time to live, tags and size, never the value. Keys contain argument values (see above), so the policy should admit only operators. | | Bad input | A missing `storedKey` or `methodId`, a `methodId` no cached method has, or an out-of-range `limit` is 400, an empty or blank tag list is 400, and keys, tags and method ids are matched literally, never as patterns. | The health check reports counts only. If you map it with a detailed response writer, put that endpoint behind authorization too. ## MethodCache.HttpCaching | Threat | What MethodCache does | |---|---| | Two users of one `HttpClient` get each other's responses (private cache, the default) | `Authorization` and `Cookie` are part of every response's key, including values that don't parse as a credential, so each caller only gets responses fetched with their own headers. `AddHttpCaching()` disables automatic cookies on known transports after all handler configuration; `KeepCookies=true` preserves the transport and bypasses response caching, validation and stale fallback completely; explicitly supplied cookie headers isolate callers. Unknown transports, and handlers inside the primary transport, bypass caching unless explicitly verified and opted in with `AllowUnverifiedTransport`. A directly constructed cache handler also bypasses known transports with automatic cookies enabled. An empty header and no header are different callers too. Header values are individually length-framed as exact UTF-16, so a comma cannot alias multiple values and isolated surrogates cannot collapse through replacement encoding. | | A 200 or 304 changes response privacy or variant selection | Revalidated representations are checked again: `no-store`, `Vary: *` or shared-cache `private` removes previous responses. An omitted `Vary` on a 304 keeps its previous value. A full response that can't be stored still removes the old one, and a change in which headers select a variant drops the URL's older responses without hiding a newer one. | | A shared cache (`IsSharedCache = true`) stores a personal response | Responses marked `private`, and responses to requests with any `Authorization` header, are not stored unless they say `public`, `s-maxage` or `must-revalidate` (RFC 9111 section 3.5). | | Stale content bypasses required validation | Response or request `no-cache` requires successful validation even with stale-while-revalidate or stale-if-error enabled; origin failures propagate. | | A cached response hands out a session | `Set-Cookie` is never stored. The caller the origin answered gets it, including on a `304`; nobody answered from the cache does. | | Responses that vary by a header (tenant, language) get mixed | `Vary` and `KeyHeaders` keep one response per value. `Vary: *` is never served from the cache. | | A write leaves another caller's stale copy, or serves one caller's copy to another after it | A successful `POST`, `PUT`, `PATCH` or `DELETE` invalidates the URL's stored responses in the shared cache before it returns, also for clients with `KeepCookies`, and a response that was loading at the time is never stored after it. This doesn't depend on the backplane. When the invalidation can't be confirmed, the call throws `HttpCacheInvalidationException` and the cache keeps retrying; the request may have succeeded at the origin, so don't repeat it automatically. A `GET` or `HEAD` that throws it is safe to retry. | | Two URLs share an entry | The key is the method and the full URL, with reserved characters kept escaped (`%2F`, `%3F` and `/`, `?` are different URLs). | | A followed redirect hands one caller's response to another | The transport drops `Authorization` on a redirect and changes the URL on the same message. A response that ended at another URL or method is never stored under the URL that was requested, and entries are keyed on the request as the caller sent it, before the transport changed it. | | A malformed `Cache-Control` hides `private` or `no-store` | A `Cache-Control` or `Vary` field the parser rejects, also next to a valid one, makes the response not storable instead of being ignored. | | Clients that get caching from `ConfigureHttpClientDefaults` share entries | Each client's handler gets its own name, so clients (often one per tenant or API key) never read each other's entries. | | Lost or replayed HTTP invalidation records | Invalidation records only move forward; a lost one only causes misses, and an older response never comes back. Two URLs that share a record can cause an extra miss, never a response for the wrong caller. | | Administration becomes a body or credential leak, or a false global inventory | Administration lists only what is in this instance's memory, plus at most 1024 recently seen distributed entries without their bodies. Ids are hashes: no query string, credentials or cookies. The distributed list doesn't claim the entries still exist. An unknown id is not found. | | An oversized response exhausts the local HTTP budget | Method and HTTP budgets evict independently. Body reads are bounded by response limits and remaining conservative HTTP cost; oversized responses remain available as streams and are not cached. | | Crafted entries in the distributed HTTP cache | Read as a miss, with every length checked against the data. As above, whoever can write that cache can store any response. | Not guaranteed, by design: - In a **shared** cache, a response stored for an anonymous request is served to authorized requests for the same URL too, and responses that depend on cookies are shared unless the origin sends `Vary: Cookie` or `private`. That is what RFC 9111 specifies for a shared cache. Add `Cookie` or `Authorization` to `KeyHeaders` when your origin personalises without saying so. - Anonymous callers of a private cache are one caller: they share responses. - HTTP key hashing preserves complete UTF-16 header frames; temporary pooled buffers are cleared before reuse. - HTTP cache diagnostics omit raw URLs, headers and exception payloads. Static configured client names remain visible. Application/transport instrumentation has its own logging configuration. ## MethodCache.OpenTelemetry Core owns the `MethodCache` Meter/ActivitySource. The OpenTelemetry package only subscribes to them. | Signal | Recorded by default | Opt-in | |---|---|---| | Spans | `methodcache.kind`, the static `methodcache.method` or `methodcache.http.client`, `methodcache.operation` or `methodcache.invalidation.type`, and `error.type`; no exception messages, stacks or copied HTTP/URL attributes | Core `MethodCacheTelemetryOptions.RecordCacheKeys` (SHA-256 by default, raw with `HashCacheKeys=false`); `RecordCacheTags` for application tags | | Baggage | No library-added baggage | The app controls normal ambient .NET baggage propagation/export | | Metrics | `methodcache.kind`, the static `methodcache.method` or `methodcache.http.client`, `methodcache.bulk`, `methodcache.result`, `methodcache.invalidation.type` and `.stage`, `methodcache.operation` and `error.type` | None: keys, tags, URLs, user ids and tenant ids never become metric dimensions | Hashing creates stable identifiers and does not make keys anonymous. Leave identity recording disabled unless the export destination is appropriate. Core, Redis, SQL and EF Core diagnostic logs omit backend exception text because it can contain credentials, keys or argument values, and a failed invalidation after an EF Core commit logs the number of tags, not the tags. An invalid configuration reload logs the path of the setting it rejected, never the value, and failed policy watchers log only the error type; both keep the last accepted policies. Health check failures expose exception types only. Standard application activity parentage and baggage remain intact, including when origin code uses its ambient authorization context; MethodCache neither adds identity baggage nor strips the application's context. ## The tests Each row above is pinned by a test: `AdminEndpointSecurityTests` (ASP.NET Core), `HttpCacheIsolationTests`, `HttpCacheEdgeCaseTests` and `UntrustedEntryTests` (HTTP caching), `CoreInstrumentationTests` (OpenTelemetry SDK) and `TelemetryPrivacyTests` (Core), `KeyInjectionPropertyTests`, `DistributedCacheSecurityTests` and `SharedRuntimeOverridesTests` (keys, tags and the distributed cache), and `InvalidationLoggingTests` (EF Core). The implementation-level guarantees behind these rows, and the CI and release boundaries, are in [security internals](https://github.com/eoniclabs/MethodCache/blob/main/docs/developer/security-internals.md). --- # Registration reference The exact rules for how `AddMethodCache()` finds and wraps cached services, for advanced users and coding agents. Start with [Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#3-register-it). ## Order - `AddMethodCache()` wraps every registration of an interface that has cached methods in its generated decorator, and keeps the lifetime and implementation you registered. Register cached services before it. - A cached service registered after `AddMethodCache()` fails when the host starts, or, without a host, when the first decorator is created. Other services can be registered later. - Calling `AddMethodCache()` again wraps the services added since, and leaves the existing decorators as they are. A test that replaces a cached service with a fake after `AddMethodCache()` calls it again; the fake is then cached. - The container disposes the implementations it creates, and leaves instances you registered yourself open, as without MethodCache. A decorator is disposable only when the interface is. ## Services you didn't register - A cached interface without a registration is registered only with `AutoRegister(lifetime)`: `AddMethodCache(mc => mc.AutoRegister(ServiceLifetime.Scoped))`. - It needs exactly one accessible class that implements the interface in the generated module. None, or several, is an error that names the service, the module and the candidates. - Registrations you made yourself always keep their implementation and lifetime. ## Several assemblies - Every assembly that references `MethodCache` generates decorators for its own cached interfaces, and all of them are used. - When two assemblies generate a decorator for the same interface, choose the one that wins with `FromAssemblyOf()` (or `FromAssembly(...)`). That only settles the tie: the services the other assemblies generate stay cached. There is no preference by entry assembly or name, under JIT and Native AOT alike. ## Keyed registrations - `AddKeyedScoped("primary")` is cached under the same key. An interface registered only keyed is not also registered without one. - The service key is part of the cache keys, so each keyed registration caches its own results. It must be a string, enum, `bool`, `char`, integer or `Guid` ([Keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#things-to-know)). - A catch-all registration with `KeyedService.AnyKey` is rejected, since its implementation is created for whichever key is requested; register concrete keys instead. - A constructor parameter marked `[ServiceKey]` receives your key, as without MethodCache. ## Several registrations of one interface - `AddScoped()` and `AddScoped()`, resolved as `IEnumerable`, each cache their own results: the implementation type is part of their keys. - Two registrations of the same implementation type share their results. - `IMethodCacheKeys.For` and `Tag` use the last registration, the one `GetService` returns. When that is a scoped or transient factory registration among several, they throw, since the factory may create another type in each scope; register the implementation type, give it a service key of its own, or invalidate by tag. ## Generic interfaces - `IRepository` is cached for every closed type a class in your project implements, such as `UserRepository : IRepository`. - An open generic registration, `AddScoped(typeof(IRepository<>), typeof(Repository<>))`, and a closed type without a generated decorator give an error that names the binding, at startup or on first use without a host. Register the closed types instead. ## Factory registrations A factory registration is cached like any other: register it before `AddMethodCache()`, and the decorator wraps what your factory returns, with the lifetime you chose. ## Your own cache manager - `services.AddSingleton()` after `AddMethodCache()` makes the decorators use your manager. `NoOpCacheManager` turns caching off ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md)). - A keyed `ICacheManager` registration is independent of the default one, and doesn't stop `AddMethodCache()` from registering its own. - Your manager stores an entry under `MethodCacheKeys.StoredKey(key, version)` of the key and version it gets, so a key and a version name the same entry in every operation. Keys from generated decorators already carry the method's version, with `version` set to `null`. - With your own manager, which has only async operations, synchronous `[Cache]` methods aren't cached (a warning is logged once per method), and a synchronous `[CacheInvalidate]` method fails with `NotSupportedException`. --- # Distributed cache reference The exact behavior of the Redis, SQL Server and PostgreSQL providers, for advanced users and coding agents. Start with [Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md) for how to use them. ## Which calls use the distributed cache - `[Cache]` methods that return `Task` or `ValueTask`, and `GetOrCreateAsync`, `GetOrCreateManyAsync` and `TryGetAsync` on `ICacheManager`. - **Synchronous `[Cache]` methods use the memory cache only.** None of the three providers has a synchronous API that can be bounded by `OperationTimeout`, so a synchronous method never blocks on the network. MethodCache logs this once per method. A synchronous `[CacheInvalidate]` method clears this instance's memory before it returns and stores the invalidation in the distributed cache and tells the other instances in the background; use an async method to wait for that. - `[Cache(Distributed = false)]`, `"Distributed": false` in `appsettings.json` and `WithDistributed(false)` keep a method or call in this instance's memory: its reads, loads and `SetAsync` make no call to the distributed cache or the backplane. Invalidations still go to every instance and the distributed cache. - `DistributedCacheOptions.StoreValuesByDefault = false` keeps values in memory: the value of a cached method or an `ICacheManager` call whose `Distributed` is unset is neither read from nor written to the distributed cache, and invalidations still go through it. `Distributed = true` (attribute, group, `Defaults`, `appsettings.json` or `WithDistributed(true)`) still shares a value, and `false` keeps it in memory whatever the option says. `SetAsync` without `WithDistributed(true)` then changes only this instance's memory. Responses of MethodCache.HttpCaching are still stored there. - `DistributedCacheOptions.VerifyUnchangedInDevelopment = false` turns off the check in Development that writes the values kept in memory and shared again every two seconds and warns about one that code changed. ## Policies and shared entries - Instances share a method's entries when they run it with the same settings from the attribute, startup code, `appsettings.json` and runtime overrides. - With a backplane, a runtime override (`IRuntimeCacheConfigurator`) applies on every instance. It is stored in the distributed cache, one record per method, before `UpsertAsync` returns, and expires with its `ExpiresAt`. Applying it invalidates the method on every instance, as any change of settings does; a change that invalidates nothing, such as one to `Owner`, `Reason` or `ExpiresAt` only, still sends the method's message. An instance that hears of the method reads its record again and drops only its own entries of the method. An instance that starts reads the records of all its cached methods: a generic host waits for them in `StartAsync`, at most `OperationTimeout` per eight methods, also when a cached service was resolved before the host started, and without a host the first cached call starts reading them without waiting. An instance that may have missed messages (when its backplane clears its memory cache) reads them all again. `ClearAsync` removes the records of every cached method, also ones the instance hasn't read yet. - Override records are kept in the distributed cache with the entries, and like the invalidation stamps they must not be evicted. With an LRU or LFU `maxmemory-policy`, Redis evicts the records, which are rarely read, among the first: running instances keep the override until they read the records again, and an instance that starts goes without it. Use `noeviction`, as for the stamps ([Keep invalidations from being evicted](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#keep-invalidations-from-being-evicted)). - An override that every instance applies can't set `CacheWhen`, `DurationFor`, `TagsFor` or `SlidingFor` (`ArgumentException`). A record an instance can't apply, because it contradicts that instance's own settings or was written by a later format, is skipped with a warning. When the distributed cache doesn't answer, `UpsertAsync` and `RemoveAsync` throw before anything changes on the instance, and an instance keeps the overrides it has and reads them all again after `CircuitBreakerDuration`. A write that timed out can still land; reading them again applies it on every instance. - Without a backplane, a runtime override that changes how a method caches gives that method entries of its own on that instance, which no other instance reads, even one with an equal override. Removing the override invalidates the method before the instance reads shared entries again. - A key from `IMethodCacheKeys.For` or a manual key invalidates the entry under every policy. - Invalidating a method (`ICacheAdministrator.InvalidateMethodAsync`) on one instance removes it on the others for every keyed registration and every closed generic type, without changing their settings. - A value loaded before an invalidation is never stored after it, also when the write lands after a timeout and retry. - Each entry remembers when its load started and when it expires. Reading it applies the reading instance's `CacheNullValues` and `CacheWhen`, and never keeps it longer than its own `Duration` (or the duration its `DurationFor` gives the value) from when it was first stored, or `MaxExpiration`. A slow method doesn't use up the entry's duration. - A value with a sliding window is stored for one window, or its `Duration` if that is shorter, from when it was stored. Reads in memory don't extend the stored copy, and an instance that reads it keeps it no longer than the stored copy. The instance that loaded it slides its own copy until a load on another instance replaces it, since every new value replaces the copies on other instances. Without a `Duration` the window alone sets the stored copy's life. - An instance that read a value from the distributed cache keeps it as a [fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md) fallback for the fail-safe window after the stored copy ended, like the instance that loaded it. ## Backplanes - **Redis** sends each invalidation with pub/sub, which reaches the instances connected at that moment. After a lost connection, an instance clears its memory cache once it is subscribed again. Reconnecting retries with a delay that doubles from one second to 30 seconds; the health check reports connected only once the subscription is confirmed. Shutdown stops pending retries, and a cancelled send or unsubscribe never fails shutdown. - **SQL Server** stores invalidations in a table that each instance polls (`BackplanePollingInterval`, one second). Identity values are handed out before a transaction commits, so a row can appear after later ones were read; an instance checks the ids it skipped again, without waiting on locks, so a long transaction never holds back newer invalidations. The table needs a `binary(32) NOT NULL` `Scope` column ([SQL Server guide](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.SqlServer/README.md#required-backplane-schema)). - **PostgreSQL** stores invalidations in a table as SQL Server does, and announces each one with `NOTIFY`, so the others read it at once. Ids are handed out in commit order, so there are no gaps to check. The listening connection reconnects with the same doubling delay and reads what it missed; until then polling delivers every invalidation. - With `EnableBackplane = false`, another instance keeps an invalidated value in memory until it expires. - Disposing the service provider unsubscribes. A backplane that doesn't answer delays shutdown by at most twice `OperationTimeout`. - Every 1.x version writes and reads the same backplane messages, so instances on different 1.x versions see each other's invalidations. A message an instance can't read, damaged or from a later major version, makes it clear its memory cache, with one warning that leaves out the message's contents. ## Invalidation results `InvalidateKeysAsync` and `InvalidateTagsAsync` check the whole batch first, and count each distinct key or tag once: - `Requested` and `Local` count every target, also ones that weren't cached. - With a distributed cache, `Distributed` (stored) plus `Queued` (to be retried) equals `Requested`. - With a backplane, `Published` counts sent messages and `PublicationQueued` the stored targets whose message will be sent again. A sent message doesn't confirm that every instance received it. ## Cancellation - Cancelling a call stops its wait while it reads the distributed cache, runs a slow method or waits for a fail-safe value, also in bulk reads. Work other callers share may finish for them. A cancelled call is not counted as a failure of the distributed cache. - Cancelling an invalidation before it starts changes nothing. Once it has started, cancelling stops the caller's wait; the cache finishes the invalidation and retries what it couldn't store. Storage and message retries have separate, bounded queues, which `ICacheAdministrator.GetInvalidationQueues()` and the health check report. ## Serialization - Every value an instance writes is first read back and written again. When that doesn't give the same bytes and types, that value and every later value of that method and type stay in memory only, and one warning names them. Each value is checked, since one with default data (an `Id` of 0 behind a private setter) can come back unchanged where the next one doesn't. - That happens with properties that have a private or protected setter, public readonly fields of a type that also has a parameterless constructor, a derived type MethodCache can't name to the serializer (see below), `object` anywhere in the value (it comes back as a `JsonElement`, so a `Dictionary` does too), a dictionary or set made with a comparer other than the default (it comes back with the default one), and values the serializer throws on (a cycle, a delegate), with JSON and MessagePack alike. - Derived types: the generator registers the classes that derive from a class or implement an interface a cached result declares (as the result, an element, or a property or field a serializer writes), found in the project with the cached interface, in the declared type's assembly and the referenced assemblies built on it, and in projects that reference the one with the cached interface. MethodCache's JSON writes such a value with a `$type` property holding the type's full name, and MessagePack as a two-item array of the name and the value; both restore the derived type. The application's own `JsonSerializerOptions` aren't changed, since MethodCache copies them. A base type with `[JsonDerivedType]`, `[JsonPolymorphic]` or `[Union]` keeps its own settings. With a `JsonSerializerContext`, a derived type the context has no contract for isn't registered, and one warning at startup names it. - A dictionary's or set's comparer is compared when the declared type shows it (`Dictionary<,>`, `HashSet`, `SortedDictionary<,>`, `SortedSet` and others with a public `Comparer`): `StringComparer.Ordinal` counts as the default for `string` keys. A collection declared as `IDictionary<,>`, `IReadOnlyDictionary<,>`, `ISet` or `IReadOnlySet` is compared the same way. - The types are compared through collections (a dictionary by key) and the public properties and fields a serializer writes: properties with a setter and auto-properties, not computed ones, and nothing marked `[JsonIgnore]`, `[IgnoreDataMember]`, `[IgnoreMember]` or `[NonSerialized]`, whose getters aren't called. A member that is null on either side isn't compared. A value whose declared type can't hold another type, such as an `int`, a `List` or a sealed record of strings, has nothing to compare and costs nothing extra. - State the serializer never writes (data only in private fields, which JSON writes as `{}`) reads back as the same bytes, so the check can't see that it is lost. Make such state serializable, or register a serializer that writes it, with `UseJson(options)` or `UseJson(context)` (`[JsonInclude]`, `[JsonDerivedType]`). - A collection declared as an interface (`IReadOnlyList`) may come back as another implementation, such as a `List` for an array, and is still shared. - A serializer that never writes the same bytes twice (encryption with a fresh nonce) can't be compared, so only the type is checked. `VerifyRoundTrip = false` turns the check off. - The options you pass to `UseJson` are copied, so changing them later has no effect. ## Storage, schemas and compatibility - `KeyPrefix` and the connection settings are fixed when the container is built; use a new container to change them. - The first instance that uses a prefix fixes its minimum `TagRetention`. A later instance may ask for longer, not shorter; a shorter setting fails at startup. Use a new prefix to lower it. - Entries are stored per value format and `SerializerVersion`, so switching between JSON and MessagePack, or raising `SerializerVersion`, makes old entries misses. Invalidations apply to every format. - A cached method's entries are also stored per result shape: a fingerprint the generator computes from the result type, the types in it, the names, types and serializer attributes (`[JsonPropertyName]`, `[JsonIgnore]`, `[JsonInclude]`, `[Key]` and others) of the members a serializer writes, the names and values of enum members, and the derived types registered for it. Framework types count by name. Reordering members, changing method bodies or adding computed properties keeps the fingerprint. Invalidations by key and tag reach entries of every shape. - An entry's expiry is fixed from when its load started, so a slow write can't extend it. - SQL Server and PostgreSQL create their tables on first use (`CreateTablesIfMissing`), and refuse a schema they don't know instead of changing it. SQL Server ships `migrations/0001-version-existing-schema.sql` for an invalidations table from before 1.0: stop the old instances, back up the database and run it before starting the new version. PostgreSQL ships `migrations/0001-create-schema.sql` for logins that may not create tables. - `ConnectionStringFactory` is resolved once from dependency injection. PostgreSQL's `ConfigureDataSource` logs in with a token from Microsoft Entra ID or AWS IAM ([Passwordless login](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/README.md#passwordless-login)). - How each provider stores its data and messages is described for contributors in [the storage format](https://github.com/eoniclabs/MethodCache/blob/main/docs/developer/distributed-wire-v1.md). --- # HTTP caching reference The exact behavior of `MethodCache.HttpCaching`, for advanced users and coding agents. Start with [HTTP response caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/http-caching.md). ## Variants - Responses are selected by the `Vary` header fields and the configured `KeyHeaders`, compared case-insensitively. A private cache always keeps `Authorization` and `Cookie` apart. - Every variant of a URL is kept for at most 365 days; each expires at its own lifetime. - When a response changes which headers select its variants, the URL's earlier variants are no longer used, once. The current response still reaches its caller, and the next request stores the new variant. If removing the old entry fails, a foreground request reports the error, and background revalidation logs it. ## Replacing a stored response - A full response replaces the stored one. When it can't be stored (`no-store`, `private` in a shared cache, a body over the size limit, or a failed write), the old one is removed, so the next caller never falls back to an older body. - Stale-while-revalidate respects the request's `max-age`, `min-fresh` and `max-stale`. - The `Age` header is corrected by the request and response delay, for first responses and for 304s, and very large values can't overflow. - Background revalidation sends the request with its HTTP version, version policy and a shallow copy of its request options. Use option values that stay valid after the original request has finished. ## Invalidation details - Invalidating a URL starts a new generation for it; responses stored under an older generation are no longer read. With Redis, SQL Server or PostgreSQL the generations are stored there, so they don't depend on the backplane. - URLs share 4096 generation slots per `KeyPrefix`, so the stored data stays bounded. Two URLs in one slot can cause an extra miss when either is invalidated. A lost generation record only causes misses, never an older response. - If reading the generation fails, the request goes to the origin. - Cancelling the caller stops its wait; the cache finishes the invalidation. Disposing the service provider asynchronously waits for pending invalidations and retries queued ones once. Any it can't confirm are logged as a count; other instances may then serve old responses until they expire. - Invalidating the client's own tag scans the responses in memory, so its cost grows with their number. URL and configured tags use indexes. ## Administration - `ICacheAdministrator` lists the responses in memory, or with a distributed cache up to 1024 responses this instance has seen there (`Storage = ObservedDistributed`): not proof that they are still stored, nor a list of everything stored. Ids are hashes; an unknown id returns NotFound. - Removing an id removes every variant of its URL. `ClearAsync` removes every response. - HTTP administration and byte statistics also work with `NoOpCacheManager` for methods. - A client's tag is `http:` followed by `MethodCacheKeys.Part(clientName)` for names up to 128 UTF-16 code units; longer names use `http:#:` followed by the SHA-256 of the name, and administration shows the start of the name and its hash. `HttpCacheOptions.Tags` takes at most 125 non-blank tags of at most 1024 code units; other values fail at startup. - HTTP entries have their own format: method serializers, durations, jitter and fail-safe settings don't apply to them. --- # Troubleshooting > [!TIP] > To see what is actually cached, list the entries with `ICacheAdministrator.ListEntries()` or `GET /methodcache/entries`, > and the effective policy of every method with `GetMethods()` or `GET /methodcache/methods` ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). ## The method runs on every call - **`AddMethodCache()` is never called.** Without it nothing caches. Warning [MC0030](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0030) reports a program with cached services that doesn't call it. - **The attribute is on the class.** `[Cache]` is read from the interface only. The analyzer reports [MC0001](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0001) and its code fix moves the attribute. - **A late or unsupported registration raises a named binding error.** Register cacheable services before `AddMethodCache()`. Open generic registrations such as `AddScoped(typeof(IRepository<>), ...)` are rejected; register generated closed types ([Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#3-register-it)). - **The caller doesn't use the interface.** The cache is a decorator around the interface. Resolving or injecting the class itself, creating it with `new`, or calling the method from inside the class (`this.GetAsync(...)`) skips it. Warning [MC0032](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0032) reports a class created with `new`, and [MC0031](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0031) a call from inside the class. - **The arguments differ between calls.** A `DateTime.Now`, a new `Guid` or a request object with a unique id in it makes every key different. List the keys to check ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md)). - **`StringBuilder`, `CultureInfo` or another framework type in an argument** is build error [MC0019](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0019): its key would not follow its value. Pass a string or an id instead ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#framework-types)). - **The result is not stored on purpose:** a `CacheWhen` predicate rejected it, `DurationFor` gave it zero or less, `SlidingFor` threw, `TagsFor` threw or gave an empty tag, the result is `null` with `CacheNullValues = false`, or the call threw. Exceptions are never cached. - **A test registered `NoOpCacheManager`**, which never caches ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md)). - **The memory cache is full**, so new entries remove less used ones before they expire. MethodCache logs a warning the first time that happens; raise `MaxItems` ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#bounding-by-size)). ## Old data after an update - **The tags don't match.** `[CacheInvalidate]` removes only the tags it lists. Compare them with the cached methods' tags. - **A tag template isn't filled in.** The name in braces must be a parameter of that method: [MC0010](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0010) warns about unknown names. A property path such as `"{product.Id}"` is not a template and stays literal ([MC0016](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0016)); pass the id as a parameter. - **The update method threw.** Invalidation runs only after the method completes successfully. - **The data changed outside the interface**, for example in another service or a database job. Invalidate from that code with `ICacheManager.InvalidateTagsAsync` ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#from-code)). - **You run several instances** with only the in-memory cache. Each instance has its own cache; add [Redis, SQL Server or PostgreSQL](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md) with its backplane, so invalidations reach all of them. The application's `IDistributedCache` is not a MethodCache provider. - **Fail-safe returned an expired value** because the method failed ([Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md)). ## Results stay out of the distributed cache A method whose result type is `object`, an interface or an abstract class with no implementations in the project or the projects it references (`Task`, `Task>`) has warning [MC0020](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0020). The serializer can't tell which class to create when it reads such a result back, so when a distributed cache is used the default round-trip check keeps these results in memory only, and each instance loads its own. Return a concrete type, such as `Task` or `Task>`, or name the implementations with `[JsonDerivedType]` on the interface. The same happens, with a warning in the log when the first such value is written, for `object` values such as those of a `Dictionary`, which come back as `JsonElement`, for a dictionary made with its own comparer, and for a derived type MethodCache can't name to the serializer ([MC0039](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0039)) or that the `JsonSerializerContext` passed to `UseJson` lacks ([MC0040](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0040)). Other derived types, such as a `Dog` in a `List`, come back as themselves ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)). ## Instances return different values for the same call - Code changed a cached result in place ([A caller changed a cached object](#a-caller-changed-a-cached-object-and-others-see-the-change)). - An invalidation hasn't reached the other instances yet, or an instance has no backplane ([What other instances see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#what-other-instances-see)). Instances that don't share entries or invalidations at all may use different settings: compare the line each one logs when its cache starts, which names the distributed cache, its `KeyPrefix` and the backplane ([Which layers an instance uses](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#which-layers-an-instance-uses)). ## Keys look different than expected List the keys with `ICacheAdministrator.ListEntries()` or `GET /methodcache/entries`, and get the key you expect from `IMethodCacheKeys.For(users => users.GetUserAsync(42))` to compare them. `ListEntries(methodId: ...)` lists the entries of one method only. [Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md) explains how each argument becomes part of a key. ## A change in appsettings.json has no effect - `AddMethodCache(mc => mc.FromConfiguration(builder.Configuration))` must be called. - The key under `Methods` must be the method id: the assembly name in brackets, the interface's full name, a dot and the method name, such as `[MyApp]MyApp.IUserService.GetUserAsync`. An unknown id fails at startup and suggests the closest one. `GET /methodcache/methods` lists the ids. - A group's settings go under `Groups`, by the exact (case-sensitive) group name. - A runtime override for the method wins over the file ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md)). - An invalid value in a reloaded file is logged as an error naming the setting, and the previous policies stay. ## Exceptions | Exception | Cause | |-----------|-------| | `InvalidOperationException` when building a key | An argument type has only private state, so every value would get the same key. Implement `ICacheKeyProvider` ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#types-whose-state-is-private)) | | `InvalidOperationException` from `AddMethodCache`: an interface has `[Cache]` methods, but MethodCache's source generator didn't run in its project | The project that declares the interface was built without MethodCache's source generator, so its calls would run uncached. Check that the project gets the `MethodCache` package, directly or through a project it references, and that `MethodCache.SourceGenerator` is among its analyzers (Dependencies > Analyzers in Rider or Visual Studio) | | `InvalidOperationException` from `AddMethodCache` naming two assemblies | Multiple generated modules contain the same interface; choose the one that wins with `FromAssemblyOf()` ([Caching third-party code](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/third-party.md)) | | `ArgumentOutOfRangeException` from `WithDuration` | Durations must be positive. Use `WithEnabled(false)` to disable caching, including in runtime overrides | | `InvalidOperationException` at startup naming a `MethodCache:` path | An invalid value, an unknown setting name (such as a `Services` section from 1.0.0-rc.1: it is now `Methods`), a single value for `Tags` or a section that holds settings, nested settings under a single setting, a setting or tag without a value, an invalid duration, an unknown method id, the same method listed twice, `Group` in `Defaults` or a group, `Notes` or `Metadata` anywhere (write a `//` comment instead), `ClearTags` in `Defaults`, `WithName` outside a manual call, or a tag template that names no parameter of a method it reaches; positive invariant unit durations such as `30s` are supported | | `InvalidOperationException` at startup about `CacheWhen` | `CacheWhen` was set in `Defaults` or a group; set it for one method with `mc.Method(...).CacheWhen(...)`. Or a `CacheWhen` is for a type the method can't return; a runtime override with one throws an `ArgumentException` ([Conditional caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/conditional-caching.md)) | | `InvalidOperationException` at startup: the `Duration` is longer than `MethodCacheMemoryOptions.MaxExpiration` | A `Duration` in `[Cache]`, code or `appsettings.json` is longer than the memory cache keeps an entry (7 days by default). Shorten it, or raise the limit with `mc.Memory(o => o.MaxExpiration = ...)`. A runtime override throws an `ArgumentException`, and a manual call an `ArgumentOutOfRangeException` before its factory runs ([Expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md)) | | `InvalidOperationException` from `IMethodCacheKeys.For` saying it can't tell which key to return | The interface has several registrations and the last is a scoped or transient factory, which may create another type in each scope. Register it with its implementation type, give it a service key of its own, or invalidate by tag ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#building-a-key-yourself)) | | `InvalidOperationException` from `GetOrCreateManyAsync`: the bulk cache factory returned null | Return a dictionary with the keys that have a value, an empty one when none has. A key the factory leaves out is not cached and not returned ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#many-keys-at-once)) | | `GetOrCreateManyAsync` returns fewer keys than it was given | The factory left those keys out, so they have no value and nothing was cached for them. Return a key with `null` to cache that it has no value ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md#many-keys-at-once)) | | `InvalidOperationException` from `AddMethodCache` naming an implementation type | An instance registration of a cached interface has the same type as another registration under the same service key. Give each its own service key ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#things-to-know)) | | `InvalidOperationException` from `AddMethodCache` naming two distributed caches | More than one of `UseRedis`, `UseSqlServer` and `UsePostgreSql` was called; use one | ## A caller changed a cached object, and others see the change > [!WARNING] > The cache hands the same instance to every caller. Return immutable types such as records, or copies > ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#cached-objects-are-shared)). Code such as `orders.Add(...)` on a list a cached method returned changes it for every later caller on that instance, while the other instances read the stored copy. Build warnings [MC0043](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#mc0043) name such code, and in Development a warning in the log names the method whose cached value changed ([Results that don't change](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#results-that-dont-change)). ## Build errors and warnings Every `MC` diagnostic, with what to do about it, is in [Build diagnostics](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md). --- # Build diagnostics MethodCache checks your attributes when you build. An error stops the build: the attribute asks for something MethodCache can't do, such as caching a `void` method, or a setting is invalid. A warning lets the build go on: the attribute is ignored, such as `[Cache]` on a class member or on a `static` interface member, or it probably doesn't do what you meant, such as a tag placeholder that matches no parameter. Every diagnostic links to its section below, and the ones marked **Code fix** can be fixed from the light bulb in Visual Studio, Rider or VS Code. When both the generator and the analyzer run, each problem is reported once. Information, such as MC0037, shows in the editor and never stops a build. | Id | Severity | Summary | Code fix | |----|----------|---------|----------| | [MC0001](#mc0001) | Warning | `[Cache]` or `[CacheInvalidate]` on a class member | Move to the interface | | [MC0004](#mc0004) | Error | A duration that is not a positive number and a unit, such as `"10m"` | Write a `TimeSpan` with a unit | | [MC0003](#mc0003) | Error | `[Cache]` on a `void` method | Remove `[Cache]` | | [MC0022](#mc0022) | Error | `[Cache]` on `Task`/`ValueTask` without a result | Remove `[Cache]` | | [MC0005](#mc0005) | Error | `[Cache]` with reference parameters or returns | Remove `[Cache]` | | [MC0006](#mc0006) | Error | `[Cache]` and `[CacheInvalidate]` on the same method | | | [MC0007](#mc0007) | Warning | `[CacheInvalidate]` without tags | | | [MC0008](#mc0008) | Error | `[Cache]` with pointer or function pointer parameters or returns, including arrays of them | Remove `[Cache]` | | [MC0009](#mc0009) | Error | `[Cache]` with ref struct or potentially ref-like parameters or returns | Remove `[Cache]` | | [MC0010](#mc0010) | Warning | A tag names a parameter the method does not have | Use the closest parameter | | [MC0011](#mc0011) | Error | `[assembly: CacheInterface]` names a type it can't decorate | | | [MC0012](#mc0012) | Error | `[assembly: CacheInterface]` lists a method it can't cache | | | [MC0013](#mc0013) | Error | The same interface in more than one `[assembly: CacheInterface]` | | | [MC0014](#mc0014) | Error | An interface with static or non-public abstract members | | | [MC0015](#mc0015) | Error | `[Cache]` on a lazy sequence | Remove `[Cache]` | | [MC0016](#mc0016) | Warning | A tag placeholder that is not a parameter name, such as `{product.Id}` | | | [MC0017](#mc0017) | Warning | A tag placeholder matches several parameter names without an exact spelling match | | | [MC0018](#mc0018) | Warning | `[Cache]` or `[CacheInvalidate]` on a `static`, non-public or `sealed` interface member | | | [MC0019](#mc0019) | Error | A key argument, element or member has a framework type without a key form, such as `StringBuilder` | | | [MC0020](#mc0020) | Warning | A cached result type of `object`, an interface or an abstract class, which a distributed cache can't restore | | | [MC0021](#mc0021) | Error | An explicitly negative cache version | | | [MC0023](#mc0023) | Error | `RefreshAhead` not shorter than `Duration` or `SlidingExpiration` on the same attribute | | | [MC0024](#mc0024) | Warning | A value in a hand-built tag is written differently from MethodCache's tags | Wrap the tag in `MethodCacheKeys.Tag`, or format the value with `MethodCacheKeys.Part` | | [MC0025](#mc0025) | Warning | A cached result type that isn't safe to share between callers, such as `JsonObject`, `DataTable` or `Stream` | | | [MC0026](#mc0026) | Warning | The implementation of a cached interface takes per-request state, such as `IHttpContextAccessor` or `ClaimsPrincipal`, or a class that does | | | [MC0027](#mc0027) | Warning | `ExecuteUpdate`, `ExecuteDelete` or raw SQL writes past EF Core's change tracker without an invalidation | | | [MC0028](#mc0028) | Warning | A tag on a cached method that nothing in the project invalidates | | | [MC0029](#mc0029) | Warning | A tag in `InvalidatedElsewhere` or `InvalidatedManually` that matches none of the method's `Tags` | | | [MC0030](#mc0030) | Warning | A program with cached services that never calls `AddMethodCache` | | | [MC0031](#mc0031) | Warning | A class calls its own cached method, which skips the cache | | | [MC0032](#mc0032) | Warning | A class that implements a cached interface is created with `new`, so its calls aren't cached | | | [MC0033](#mc0033) | Error | `CacheWhen`, `DurationFor`, `SlidingFor` or `TagsFor` for a type the call's result can never be | | | [MC0034](#mc0034) | Error | A key argument, or a value inside one, of a type whose state is all private | | | [MC0035](#mc0035) | Warning | A cache factory uses a cancellation token from outside it that the call doesn't pass | Use the factory's token and pass yours as `cancellationToken` | | [MC0036](#mc0036) | Warning | A name in `methodcache.request_state_types` matches no type | | | [MC0037](#mc0037) | Info | A cache key that is written when the call runs, because an argument's actual type decides it | | | [MC0038](#mc0038) | Warning | `SlidingExpiration` not shorter than `Duration` on the same attribute, so reads never extend an entry | | | [MC0039](#mc0039) | Warning | A class that derives from a type a cached result holds, but that MethodCache can't name to the distributed cache, such as a generic or private one | | | [MC0040](#mc0040) | Warning | A derived type the `JsonSerializerContext` passed to `UseJson` has no contract for, while it has one for the base type | Add `[JsonSerializable]` to the context | | [MC0041](#mc0041) | Warning | A cached result holds EF Core entities with virtual navigation properties in a project that uses lazy-loading proxies | | | [MC0042](#mc0042) | Warning | A cached result type, or a type in it, whose state is all non-public, so serializers write it as an empty object | | | [MC0043](#mc0043) | Warning | Code changes a cached result | | ## Rules of a later version A new version of MethodCache can bring new analyzer rules, and with warnings treated as errors a new warning stops the build. To upgrade first and turn the new rules on later, set `MethodCacheAnalysisLevel` to the version whose rules you want, in the project file or in `Directory.Build.props`: ```xml 1.0 ``` The rules that came after that version are then off. Turn one of them on in `.editorconfig`, such as `dotnet_diagnostic.MC0060.severity = warning`, and raise the level when you have looked at the rest. Every rule of 1.0 stays on at any level, and without the property every rule is on. A value that isn't a version, such as `latest`, fails the build with MCB001. Every rule up to 1.0.0 counts as a rule of 1.0, so `1.0` turns nothing off in 1.0.0. Set the level only when warnings are errors. Without that, leave it unset, so an upgrade shows its new warnings. ## MC0001 `[Cache]` or `[CacheInvalidate]` is on a class, struct or record member. MethodCache generates a decorator for the interface, so it only reads attributes on interface methods, and this one is ignored. ```csharp public interface IUserService { [Cache(Duration = "5m")] // here Task GetAsync(int id); } public class UserService : IUserService { public Task GetAsync(int id) => ...; // not here } ``` **Code fix:** moves the attribute to the interface method the member implements (adding the `using` if needed), or removes it when the member implements no interface. To cache an interface you don't own, see the [third-party caching page](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/third-party.md). ## MC0004 `Duration`, `SlidingExpiration`, `RefreshAhead`, `FailSafe`, `FailSafeTimeout` or `FailSafeRetryAfter` on `[Cache]` or `[assembly: CacheInterface]` is not a duration. Write a positive number and a unit: `"30s"`, `"5m"`, `"1.5h"` or `"7d"` ([Writing a duration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#writing-a-duration)). `SlidingExpiration`, `RefreshAhead` and `FailSafe` also accept `"off"`. A `TimeSpan` such as `"00:10:00"` is reported with the same value in units, `"10m"`. **Code fix:** writes a `TimeSpan` with a unit. ## MC0003 `[Cache]` on a `void` method: there is no result to cache. Return the value, or remove `[Cache]`. If the method changes data, you probably want `[CacheInvalidate(Tags = ...)]` instead. ## MC0022 `[Cache]` on a method returning `Task` or `ValueTask` without a result. Return `Task` or `ValueTask`, or remove `[Cache]`. A write method usually wants `[CacheInvalidate(Tags = ...)]` instead. ## MC0005 `[Cache]` on a method with `ref`, `out` or `in` parameters, or a `ref` / `ref readonly` return. A cached value cannot preserve references or set an `out` value. Pass and return values by value, for example as a record. ## MC0006 `[Cache]` and `[CacheInvalidate]` on the same method. A method either reads (cached) or writes (invalidates); keep the one that matches what it does. ## MC0007 `[CacheInvalidate]` without tags removes nothing. List the tags of the cached methods it should clear: ```csharp [Cache(Tags = new[] { "users", "user:{id}" })] Task GetAsync(int id); [CacheInvalidate(Tags = new[] { "users", "user:{id}" })] Task UpdateAsync(int id, User user); ``` ## MC0008 `[Cache]` on a method with pointer or function pointer parameters or returns, including arrays of them such as `int*[]`. These cannot be stored as cached values or keys; use a value or an array of values. Unsupported methods, and any other member of the interface that uses a pointer, are still forwarded through an unsafe implementation. ## MC0009 `[Cache]` on a method with `Span`, `ReadOnlySpan` or other ref struct parameters or returns. These cannot be stored in a cache; use an array, `Memory` or a string. This also applies to a type parameter with `allows ref struct` when that parameter is used as an argument or return value. ## MC0010 A tag such as `"user:{userId}"` names a parameter the method does not have, so the braces stay literal text and every call shares that tag. The name between the braces must match a parameter name: the exact spelling first, otherwise a single case-insensitive match. A name that matches several parameters only by case is [MC0017](#mc0017). A template takes a parameter name only; a property path such as `"{product.Id}"` is reported as [MC0016](#mc0016). **Code fix:** offers the closest parameter names, so `"user:{usrId}"` becomes `"user:{userId}"`. ## MC0011 `[assembly: CacheInterface]` names a type MethodCache can't decorate: a class, a generic interface, an interface that is not accessible, one with static abstract or non-public abstract members, or one declared in your own project (put `[Cache]` on its methods instead). It is also reported when the attribute lists no methods. See the [third-party caching page](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/third-party.md). ## MC0012 `[assembly: CacheInterface]` lists a method that is missing, overloaded or static, or one that `[Cache]` would reject: it returns nothing to cache, has `ref`, `out`, `in`, pointer or ref struct parameters, a framework type without a key form ([MC0019](#mc0019)), or returns a lazy sequence. Use `nameof(IClient.Method)` so a rename is caught by the compiler. See the [third-party caching page](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/third-party.md). ## MC0013 The same interface is listed in more than one `[assembly: CacheInterface]`. List each interface once, with all its methods in the same attribute. ## MC0014 The interface has static abstract members, or non-public abstract members that cannot be forwarded to the decorated instance. Move the cached methods to an interface without them. Non-public default methods are supported because they remain on the interface, and so are nested helper types declared inside the interface. ## MC0015 `[Cache]` on a method returning `IEnumerable`, `IAsyncEnumerable` or `IQueryable`. The cached value would be the lazy sequence itself, which runs the query again on every enumeration. Return a materialized collection, such as `Task>`, `Task>` or `T[]`, and call `ToListAsync()` (or similar) in the implementation. ## MC0016 A tag has braces that look like a template but don't hold a plain parameter name: a property path such as `"product:{product.Id}"`, spaces such as `"{ id }"`, or a format such as `"{day:yyyy-MM-dd}"`. Templates take a parameter name only, so the braces stay literal text and every call shares the same tag. Write `"product:{id}"` and add the value as its own parameter, as `UpdateAsync(int id, Product product)` does in [Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md). For `[assembly: CacheInterface]` both MC0010 and MC0016 are reported on the attribute. ## MC0017 The placeholder has no exact parameter match and more than one case-insensitive match, such as `{NAME}` for parameters `name` and `Name`. Use the intended parameter's exact spelling. Until corrected, the placeholder remains literal in both cached tags and invalidation. ## MC0018 `[Cache]` or `[CacheInvalidate]` is on an interface member the decorator can't intercept: a `static` member, a `private` or other non-public member with a body, or a `sealed` one. The decorator implements the interface for a class, and a class can't implement those members, so calls to them never reach the cache and the attribute does nothing. Put the attribute on a public interface method without `static`, `private` or `sealed` (one without a body, or a public default method), or remove it. ## MC0019 A key argument has a type from .NET itself, ASP.NET Core or Microsoft.Extensions (an assembly named `System.*`, `Microsoft.AspNetCore.*` or `Microsoft.Extensions.*`) that the cache key can't be written from: the argument itself, an element of a collection or tuple, or a public property or field of your own type, such as `StringBuilder`, `CultureInfo`, `Stream`, `Type` or a `Func`. Their public properties don't hold their value, or the value can change after the call (a `StringBuilder`), so two different arguments could share a key and one caller would get another's result. The message names the value, such as `'note.Text' is a 'StringBuilder'`. Pass a value that identifies it instead, such as a string, an id or a culture name, or wrap it in a type that implements `ICacheKeyProvider` (see [Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#framework-types)). Every argument must have a supported key form. Framework types with a key form are written by their value: `Guid`, `DateTime`, `DateTimeOffset`, `TimeSpan`, `DateOnly`, `TimeOnly`, `Half`, `Int128`, `UInt128`, `BigInteger`, `Complex`, `Uri`, `Version`, `IPAddress` and `JsonElement` (as its JSON, so whitespace doesn't count), `Index`, `Range`, `Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Plane`, `Matrix3x2`, `Matrix4x4`, and ASP.NET Core's `PathString`, `QueryString` and `HostString`, as well as arrays, collections, `Memory`, tuples and `KeyValuePair` of those. Models from other libraries, such as an SDK's classes in a `Microsoft.*` namespace, are not framework types: they are written by their public properties like your own. ## MC0020 The cached method's result type, after `Task` or `ValueTask`, is `object`, an interface such as `IComparable` or `IShape`, or an abstract class, or has one as an element (`List`). A distributed cache stores results as JSON or MessagePack of the declared type, which can't say which class to create when it reads them back. When a distributed cache is used, the default round-trip check finds that such a result doesn't read back, and keeps it in the in-memory cache only. Collection interfaces such as `IReadOnlyList` are fine; they are read back as a list. Not reported when the project, or a project it references, has classes that implement the interface or derive from the abstract class: MethodCache's generator then names them to its serializers, so they come back as themselves ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)). Return a concrete type, such as `Task` or `Task>`, to share the results through the distributed cache, or name the types that implement it with `[JsonDerivedType(typeof(Square), "square")]` on the interface or abstract class (`[Union]` with MessagePack), which also silences this warning. When only the in-memory cache is used, or memory-only is what you want, suppress the warning with `#pragma warning disable MC0020` or `` in the project. ## MC0021 An explicitly supplied `Version` is negative. Omit it to inherit the configured version or use a non-negative integer. ## MC0023 `RefreshAhead` on `[Cache]` or `[assembly: CacheInterface]` is as long as the `Duration` or `SlidingExpiration` next to it, or longer. The refresh window starts that long before an entry expires, so every hit would reload the value. Use a window shorter than both, such as `Duration = "10m", RefreshAhead = "1m"`, or `"off"` to turn refresh-ahead off. ## MC0024 A tag built with string interpolation for `InvalidateTagAsync`, `InvalidateTagsAsync` or `InvalidateAfterCommit` contains a value that interpolation writes differently from the tags MethodCache stores, so the invalidation can match nothing and the old value stays cached, without an error: ```cs // The cached entry is tagged price:ollama:gemma3\:4b, so this removes nothing await cache.InvalidateTagAsync($"price:{provider}:{model}"); ``` Tag templates write values in one canonical way: `:` and `\` escaped in strings, a `Guid` as 32 digits without hyphens, an enum as its number, `true` and `false` in lower case, and numbers and dates in the invariant culture (dates in ISO 8601). Whole numbers come out the same, so `$"user:{id}"` with an `int` is not reported. Build the tag from a call to the cached method instead, so the template and the formatting come from the method: ```cs await cache.InvalidateTagAsync(keys.Tag(s => s.GetRateAsync(provider, model), "price:{provider}:{model}")); ``` Or wrap the interpolated string in `MethodCacheKeys.Tag`, which writes every value the way tags do: `MethodCacheKeys.Tag($"price:{provider}:{model}")`. A value of a type tags can't hold, or with a format, doesn't compile there. **Code fix:** wraps the tag in `MethodCacheKeys.Tag` when every value in it can go there, and otherwise formats the reported value with `MethodCacheKeys.Part`: `$"price:{MethodCacheKeys.Part(provider)}:{id}"`. A value with a format such as `{price:F2}` has no fix, since the tag MethodCache stores has no format. ## MC0025 The cached method returns a type whose instances change while they are read or used, or has one as an element: `JsonNode` and its subclasses (`JsonObject`, `JsonArray`), `DataTable`, `DataSet`, `DataRow`, `DataView`, a `Stream` or a `StringBuilder`. The cache hands the same instance to every caller, at the same time. A `JsonNode` parses its content lazily the first time it is read, and isn't thread-safe while it does, so two requests reading one cached `JsonObject` at once can get an empty or broken result. A stream's position moves as one caller reads it. ```cs [Cache(Duration = "5m")] Task GetLayoutAsync(string locale); // MC0025: every caller shares one JsonObject ``` Return an immutable type instead: a record, a string (`node.ToJsonString()`), a `byte[]` you never change, or a `JsonElement` (`JsonDocument.Parse(json).RootElement.Clone()`), which is read-only and safe to share. Collections such as `List` and arrays are not reported: they are safe to read from several threads, but don't change a cached one ([cached objects are shared](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#cached-objects-are-shared)). ## MC0026 A class implements an interface with `[Cache]` methods and takes per-request state in its constructor: `IHttpContextAccessor`, `HttpContext`, `HttpRequest`, `ClaimsPrincipal` or another `IPrincipal`. It is reported too when it takes a class whose constructor takes that state, such as a `DbContext` that filters rows by the signed-in user, directly or through a factory such as `IDbContextFactory`. The analyzer follows constructors two levels down (the class the implementation takes, and a class that class takes), and follows an interface to the classes that implement it, in the same project and in the projects it references ([what the analyzers read from referenced projects](#what-the-analyzers-read-from-referenced-projects)). It doesn't see a setting that an interceptor makes on the connection. Name your own request-state types, such as an `ICurrentUser` service or a tenant context, in `.editorconfig`, comma separated, with namespace. A class that takes one, or takes a class that does, is reported too: ```ini [*.cs] methodcache.request_state_types = MyApp.ICurrentUser, MyApp.TenantContext ``` A name that matches no type, such as one left behind when the type was renamed, is reported as [MC0036](#mc0036). The cache key is built from the method's arguments only. A result that depends on the current request or user, such as a query filtered by row-level security on a connection set up for that user, is stored under a key that doesn't name the user, and the next caller gets it, whoever they are. Refresh-ahead and fail-safe also load values outside the request, in a new scope with no `HttpContext`. ```cs public sealed class Orders(IHttpContextAccessor http, AppDb db) : IOrders // MC0026 { public Task> MineAsync() => db.Orders.Where(o => o.UserId == http.HttpContext!.User.Id()).ToListAsync(); } ``` ```cs public sealed class TenantDb(DbContextOptions options, IHttpContextAccessor http) : DbContext(options) { ... } public sealed class Catalog(TenantDb db) : ICatalog // MC0026: TenantDb's constructor takes IHttpContextAccessor ``` Make what the result depends on a parameter of the cached method, so it becomes part of the key: `Task> ForUserAsync(int userId)`, called with the current user's id. Or don't cache the method. For a context set up for the signed-in user, give the cached reads a context of their own ([Row-level security](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#row-level-security)). See [Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#per-user-data). ### A tenant parameter checked against the request When the cached method already takes the tenant or user as a parameter, and reads through a context that filters by the request's tenant, check that the two match. Mark your check method `[ChecksRequestState]` and call it with the parameter at the start of each cached method. A class whose cached methods all do isn't reported: ```cs public sealed class TenantDb(DbContextOptions options, ITenantContext tenant) : DbContext(options) { [ChecksRequestState] public void EnsureActsFor(Guid tenantId) { if (tenantId != tenant.Id) throw new UnauthorizedAccessException("Not the request's tenant."); } } public sealed class Projects(TenantDb db) : IProjects { public Task> ListAsync(Guid tenantId) // [Cache] on IProjects.ListAsync { db.EnsureActsFor(tenantId); // a load for another tenant throws, so nothing wrong is cached under its key return db.Projects.Select(p => new ProjectDto(p.Id, p.Name)).ToListAsync(); } } ``` The check runs when the method loads a value, not on a hit. What is cached under a tenant's key was loaded for that tenant, but a caller that passes another tenant's id gets that tenant's cached result without the check. So take the id from the request, or authorize it, before the call, as for any cached method that takes a tenant or user id. Refresh-ahead runs without a request, so the check fails there and the entry is loaded on the next call instead; don't combine the pattern with `RefreshAhead`. The attribute changes nothing at run time. The analyzer reads the attribute on the method the cached method calls. When you call the check through an interface, such as `ITenantContext.EnsureActsFor(tenantId)`, mark the interface method; the attribute on the class that implements it isn't seen through the interface. ### A table the request doesn't filter Some cached reads go through a context that holds request state but read a table that doesn't depend on it, such as looking up an API key before the tenant is known, from a table without row-level security. The result depends only on the arguments, but the analyzer can't tell which tables a method reads, so it still reports the class. Suppress the warning there, with the reason, so it stays next to the code it is about: ```cs [SuppressMessage("Security", "MC0026", Justification = "api_keys has no row-level security; the key is the argument")] public sealed class ApiKeys(TenantDb db) : IApiKeys { public Task FindAsync(string keyHash) // [Cache] on IApiKeys.FindAsync => db.ApiKeys.SingleOrDefaultAsync(k => k.Hash == keyHash); } ``` Suppress it on the class, not for the project, so a new cached method in another class is still checked. A context of its own for such reads, without the request state, avoids the warning as well. ## MC0027 Reported in a project that uses `MethodCache.EntityFrameworkCore`, on `ExecuteUpdate`, `ExecuteDelete`, `ExecuteSql`, `ExecuteSqlRaw` or `ExecuteSqlInterpolated` (and their `Async` versions). They change rows without loading them, so EF Core's change tracker never sees the rows, and no entity tags are invalidated for them. Cached results that read those rows stay until they expire. - `ExecuteUpdate` and `ExecuteDelete` are reported on the entity types that the project maps with `ef.Entity(...)`, and on their base and derived types. A type mapped only with `WhenDeleted(...)` is reported for `ExecuteDelete` alone. A project that references the one with the mapping, such as its tests or a worker, checks its writes against that mapping too: MethodCache writes the mapping into the assembly as `AssemblyMetadata` attributes ([where to see them](#what-the-analyzers-read-from-referenced-projects)). When neither the project nor a project it references maps a type, as in a data layer that the startup project references, every type is reported. - Raw SQL is reported when it names the table of such a type, runs code (`call`, `exec`, `execute` or `do`), or can't be read: SQL in a variable, or `ExecuteSqlRaw` with an interpolated value that is neither a constant nor a number, such as a string, which could hold any SQL. A table is known by its class name, the name of its `DbSet` and a name given with `ToTable` or `[Table]`, compared without case and underscores and with or without a plural ending, so `ai_model_prices` matches `AiModelPrice`. A name given with `ToTable` in a project that maps no type isn't recognized. When no mapping is visible, all raw SQL is reported. - Statements that only `select`, such as `select pg_advisory_xact_lock(...)`, or `set` a session setting, such as `SET LOCAL lock_timeout = '5s'`, are never reported. That holds for `ExecuteSqlRaw` with interpolated constants and numbers too, such as `$"SET LOCAL lock_timeout = '{waitMs}ms'"` with an `int`. ```cs await db.Products.Where(p => p.CategoryId == id).ExecuteUpdateAsync(s => s.SetProperty(p => p.Price, 0m)); // MC0027 ``` Invalidate the tags of the rows it changes, in the same method or in a method around it, such as the one that runs an execution strategy: inside a transaction with `db.InvalidateAfterCommit(...)`, or after a write that is already committed with `ICacheManager.InvalidateTagsAsync(...)` ([Writes the change tracker doesn't see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#writes-the-change-tracker-doesnt-see)). A call to a `[CacheInvalidate]` method of a cached interface counts as an invalidation, and so does a call to a method of your own marked `[InvalidatesCache]`, such as a helper that invalidates through the app's own plumbing. The warning is not reported inside either kind of method, since they invalidate themselves. When nothing cached reads the rows of a mapped type, turn it off for that line with `#pragma warning disable MC0027`. A generic helper, such as a retention job's `PurgeAsync()`, is reported, since any type could reach it. When some of the types it gets are cached, have it take the tags of what it changes, invalidate them, and mark it `[InvalidatesCache]`, so each call to it counts as the invalidation ([Generic helpers](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#generic-helpers)). When the types it gets are never cached, turn the warning off in the helper and say why: ```cs public static class Retention { // Called for audit and log types only, which nothing caches #pragma warning disable MC0027 public static Task PurgeAsync(DbSet rows, DateTime before) where TEntity : class, IStamped => rows.Where(r => r.CreatedAt < before).ExecuteDeleteAsync(); #pragma warning restore MC0027 } ``` ## MC0028 A tag on a `[Cache]` method that nothing in the project invalidates, in a project that invalidates something. Its entries stay until they expire, so a change to the data they hold isn't seen until then. ```cs public interface ICatalog { [Cache(Duration = "1h", Tags = ["catalog"])] // MC0028 when nothing invalidates "catalog" Task> ListAsync(); } ``` These invalidations count, wherever they are in the project: - A `[CacheInvalidate]` tag in the project, or on a method of an interface in a project it references, such as a shared invalidation interface that another project calls. - An entity mapping of `MethodCache.EntityFrameworkCore`: `Entity("...")`, and `Tags("...")` or `WhenDeleted("...")` in `Entity(e => ...)`. - A call to `InvalidateTagAsync`, `InvalidateTagsAsync` or `InvalidateAfterCommit`, or to a method of your own marked `[InvalidatesCache]`, with the tag as a constant, an interpolated string or `IMethodCacheKeys.Tag(..., template)`. - A tag in `InvalidatedElsewhere` on any `[Cache]` in the project, for a tag that another application invalidates. - A tag in `InvalidatedManually` on any `[Cache]` in the project, for a tag that only an operator clears. A placeholder matches any value: `"product:{id}"` is covered by `InvalidateTagAsync($"product:{id}")` and by `"product:42"`, not by `"products"`. A tag built in a variable, tags in configuration and other invalidations in other projects aren't seen; `TagCoverage` in `MethodCache.Testing` checks the whole application in a test, and checks that a referenced project invalidates each tag marked `InvalidatedElsewhere` ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-tag-has-an-invalidation)). Invalidate the tag where the data changes ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md)). When another application or process invalidates it, such as a worker that writes the data, list it in `InvalidatedElsewhere` ([In another application](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#in-another-application)): ```cs // The import worker invalidates "catalog" [Cache(Duration = "1h", Tags = ["catalog"], InvalidatedElsewhere = ["catalog"])] Task> ListAsync(); ``` When no code invalidates it and an operator clears it by hand after a change, such as with `POST invalidate` of `MapMethodCacheAdmin`, list it in `InvalidatedManually` instead ([Cleared by hand](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#cleared-by-hand)): ```cs // An operator clears "catalog" after the yearly update [Cache(Duration = "1d", Tags = ["catalog"], InvalidatedManually = ["catalog"])] Task> ListAsync(); ``` Both replace a `SuppressMessage` on each method and keep the reason next to the tag. A project that invalidates nothing, such as a library that only declares the cached interfaces, isn't reported. ## MC0029 A tag in `InvalidatedElsewhere` or `InvalidatedManually` on `[Cache]` that matches none of the method's `Tags`, such as a misspelled one. It marks nothing on the method, so the real tag still counts as never invalidated. ```cs [Cache(Duration = "1h", Tags = ["catalog"], InvalidatedElsewhere = ["catalogue"])] // MC0029 Task> ListAsync(); ``` Write the tag as it is written in `Tags`. A placeholder matches any value, so `"recipe:{Id}"` matches `"recipe:{id}"`. Not reported when the attribute has no `Tags`, because the method's tags then come from configuration. ## MC0030 A program has cached services, in its own code or in a project it references, but its code calls neither `AddMethodCache` nor a method of a referenced project that calls it. Nothing of MethodCache runs then, so every `[Cache]` method runs uncached, and nothing at run time can tell. ```cs var builder = WebApplication.CreateBuilder(args); builder.Services.AddScoped(); // IProducts has [Cache] methods var app = builder.Build(); // MC0030: no AddMethodCache ``` Call `AddMethodCache()` after registering the services ([Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md)): ```cs builder.Services.AddScoped(); builder.Services.AddMethodCache(); ``` A setup method of your own in a referenced project counts when the program calls it, such as `builder.Services.AddData()` whose code calls `AddMethodCache`. MethodCache marks such methods when it builds that project, also when they reach `AddMethodCache` through other setup methods of the project named `Add...`, `Use...`, `Configure...` or `Register...`. A program that references the project but never calls the method is reported, since nothing sets the cache up for it. ([What the analyzers read from referenced projects](#what-the-analyzers-read-from-referenced-projects) shows where these marks are.) Test projects aren't reported, since tests may use the implementations without the cache. A program that references a project with cached services but doesn't use them, such as a migration tool, or that reaches its setup some other way, such as through reflection, can turn the warning off with `$(NoWarn);MC0030`. ## MC0031 A class calls one of its own `[Cache]` methods. The cache is a generated decorator in front of the service, so a call from inside the class goes straight to the method and runs every time, also through `this` or a cast of `this` to the interface. ```cs public sealed class Prices(IPriceApi api) : IPrices { public Task GetAsync(int id) => api.GetAsync(id); // [Cache] on IPrices.GetAsync public async Task TotalAsync(int[] ids) { var total = 0m; foreach (var id in ids) total += await GetAsync(id); // MC0031: not cached return total; } } ``` Move the cached method to a service of its own and call it through that service's interface, so the call passes the cache: ```cs public sealed class Totals(IPrices prices) : ITotals { public async Task TotalAsync(int[] ids) { var total = 0m; foreach (var id in ids) total += await prices.GetAsync(id); // cached return total; } } ``` When the call doesn't need the cache, such as a method that calls itself to walk a tree, let the cached method call a private method that does the work, and recurse in that one. The private method isn't cached, and nothing suggests it is: ```cs public sealed class Paths(IFolders folders) : IPaths { public Task ResolveAsync(int folderId) => ResolveCoreAsync(folderId); // [Cache] on IPaths.ResolveAsync private async Task ResolveCoreAsync(int folderId) { var folder = await folders.GetAsync(folderId); return folder.ParentId is { } parent ? await ResolveCoreAsync(parent) + "/" + folder.Name : folder.Name; } } ``` A class created with `new` has no decorator either, so its calls aren't cached; [MC0032](#mc0032) reports it. ## MC0032 A class that implements a cached interface is created with `new`. The cache is a decorator that dependency injection puts in front of the service when `AddMethodCache` runs, so an instance made with `new` has none, and its `[Cache]` methods run every time. ```cs var rates = new EcbRates(http); // MC0032: not cached var rate = await rates.GetAsync("SEK"); ``` Get the interface from dependency injection instead. When you need several instances of one class, such as one per provider or tenant, register each as a keyed service before `AddMethodCache`; each caches its own results: ```cs builder.Services.AddKeyedSingleton("ecb", (sp, _) => new EcbRates(sp.GetRequiredService())); builder.Services.AddKeyedSingleton("fed", (sp, _) => new FedRates(sp.GetRequiredService())); builder.Services.AddMethodCache(); public sealed class Converter([FromKeyedServices("ecb")] IRates rates) { /* rates is cached */ } ``` Creating the instance inside a registration, as above or as `services.AddSingleton(new EcbRates(http))`, isn't reported, since `AddMethodCache` wraps what the registration gives. Passing it to another constructor first, as in `new Converter(new EcbRates(http))`, is. For code that can't get its services from dependency injection, cache the call with [`ICacheManager`](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md) instead. Test projects aren't reported, since tests create implementations to test them without the cache. Where you want the uncached class on purpose, suppress the warning there with `#pragma warning disable MC0032`. ## MC0033 `CacheWhen`, `DurationFor`, `SlidingFor` or `TagsFor` on `CacheEntryOptions.Builder` is for a `T` that the call's result can never be, such as `string` for a method that returns `int`. It would get no result to check, so MethodCache rejects it when the application starts or the call runs; this error finds it while building. ```cs mc.Method((IPrices p) => p.CountAsync(0)).Configure(o => o.CacheWhen(s => s.Length > 0)); // MC0033 await cache.GetOrCreateAsync("count", LoadCountAsync, o => o.CacheWhen(s => s != null)); // MC0033 ``` Use the call's result type, or for one method the typed `Method(...).CacheWhen(...)`, `Method(...).DurationFor(...)`, `Method(...).SlidingFor(...)` and `Method(...).TagsFor(...)`, which take the result type from the method: ```cs mc.Method((IPrices p) => p.CountAsync(0)).CacheWhen(count => count > 0); ``` A base type, an interface or the nullable form of the result type is fine: `CacheWhen`, `CacheWhen>` for a `List`, or `CacheWhen` for an `int`. A numeric type the result converts to isn't, since a boxed `int` is not a `long`. Reported in `Method(...).Configure(...)`, `GetOrCreateAsync`, `GetOrCreateManyAsync` and `SetAsync`; options built elsewhere and passed in are checked when the call runs. ## MC0034 A key argument of a `[Cache]` method, or a value inside it (a property of a record, an element, a tuple item), has a type of your own whose state is all private: private fields or properties, also inherited ones, and no public property or field. Every value of it would be written the same, so all calls would share one key and callers would get each other's results. MethodCache refuses it with an `InvalidOperationException` when the call runs; this error finds it while building. The message names the value, such as `'query.Owner' is a 'UserId'`. ```cs public readonly struct UserId(int value) { private readonly int _value = value; } public interface IUsers { [Cache] Task GetAsync(UserId id); } // MC0034 ``` Implement `ICacheKeyProvider` on the type, or give it public properties that identify the value ([Types whose state is private](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#types-whose-state-is-private)). A type with a `[JsonConverter]` and an abstract type aren't reported. ## MC0035 The factory of `GetOrCreateAsync` or `GetOrCreateManyAsync` uses a cancellation token from outside it, such as the method's own `ct` or `HttpContext.RequestAborted`, that the call doesn't pass as its `cancellationToken`. Callers of one key share one run of the factory, which gets the token of the caller that started it: when that caller cancels, the others run the factory again. A token the cache doesn't know fails the run for all of them instead, and they get the cancellation, or a fail-safe value when there is one. ```cs public ValueTask GetAsync(int id, CancellationToken ct) => cache.GetOrCreateAsync($"order:{id}", async _ => await orders.GetAsync(id, ct)); // MC0035 ``` Use the factory's own token, and pass yours as `cancellationToken`. The code fix does both, and names a discarded parameter after your token, so inside the factory `ct` is the factory's: ```cs public ValueTask GetAsync(int id, CancellationToken ct) => cache.GetOrCreateAsync($"order:{id}", async ct => await orders.GetAsync(id, ct), cancellationToken: ct); ``` A token the call passes as its `cancellationToken`, `CancellationToken.None` and a token the factory makes itself aren't reported. ## MC0036 A name in the `.editorconfig` option `methodcache.request_state_types` matches no type, although its namespace has types. [MC0026](#mc0026) then doesn't look for that type, without a sign: this happens when the type is renamed or moved and the option isn't. ```ini [*.cs] methodcache.request_state_types = MyApp.ICurrentUser # MC0036 after ICurrentUser was renamed IUserContext ``` Write the type's full name as it is now, with its namespace, such as `MyApp.IUserContext`. A nested type is written `MyApp.Outer.Inner`, and a generic type `MyApp.IRepository`. A name is checked only in a project that sees types in its namespace, so a solution-wide `.editorconfig` that names a type of the web project doesn't warn in a library that doesn't reference it, even one whose own namespace, such as `MyApp.Data`, starts with the type's namespace. The warning has no location in a file; it names the option and the type. ## MC0037 Information, not a warning: the decorator can't write the method's key when you build, so the key generator writes it when the call runs, from the actual type of the argument, and hashes it. That is the case for an argument of type `object`, an interface the decorator can't write, or a collection of collections ([How arguments become keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#how-arguments-become-keys)). The key is right, but it takes longer to build and isn't readable in the admin list. ```cs [Cache(Duration = "5m")] Task> SearchAsync(object filter); // MC0037: the key is written when the call runs ``` To have it written when you build, pass simple values or a sealed record of them: ```cs public sealed record OrderFilter(string? Customer, OrderStatus? Status, int Page); [Cache(Duration = "5m")] Task> SearchAsync(OrderFilter filter); // SearchAsync:(alice:Open:2) ``` ## MC0038 `SlidingExpiration` on `[Cache]` or `[assembly: CacheInterface]` is as long as the `Duration` next to it, or longer. An entry never lives past its `Duration`, so reads can never extend it, and it expires as if the sliding window weren't set: ```cs [Cache(Duration = "5m", SlidingExpiration = "1d")] // MC0038: each entry expires 5 minutes after it was loaded Task GetAsync(int id); ``` Use a window shorter than the `Duration`, such as `Duration = "1d", SlidingExpiration = "5m"` to keep an entry while it is read at least every five minutes, for at most a day. Or remove `SlidingExpiration`. It is a warning, not an error: the method is cached, only the window does nothing. The two settings often come from different places, such as a sliding window on the method and the duration of `Defaults`, which the build can't see together. The host logs the same warning when it starts, once for each such method, whether the settings come from `[Cache]`, startup code or `appsettings.json` ([Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration)). ## MC0039 A class derives from a type that a cached result holds, such as a `Dog` where a method returns `List`, but MethodCache can't name it to the distributed cache's serializer: the class is generic, private or nested in a private type, `file`-local, or not public in a referenced assembly. A value that holds one can't be restored as a `Dog` from the distributed cache, so the check before sharing keeps it in each instance's memory, with a warning in the log: ```cs public class Animal { public string Name { get; set; } = ""; } public class Box : Animal { public T Value { get; set; } = default!; } // MC0039: it is generic public interface IZoo { [Cache] Task> AnimalsAsync(); } ``` Make the class public or internal, not generic and not nested in a private type, and MethodCache registers it, so it comes back from the distributed cache as itself. Or name it with `[JsonDerivedType(typeof(Box), "box-int")]` on the base type (`[Union]` with MessagePack). When such values only need the in-memory cache, suppress the warning. A test project gets no MC0039, since its private test doubles don't reach a shared cache ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)). ## MC0040 Under Native AOT the distributed cache's JSON can only write the types the `JsonSerializerContext` passed to `UseJson` has contracts for. The context has one for a type a cached result holds, such as `Animal`, but not for a class that derives from it, such as `Dog`, so a value holding a `Dog` stays in each instance's memory: ```cs [JsonSerializable(typeof(List))] internal partial class AppJsonContext : JsonSerializerContext { } builder.Services.AddMethodCache(mc => mc.UseJson(AppJsonContext.Default)); // MC0040: no contract for Dog ``` Add `[JsonSerializable(typeof(Dog))]` to the context; the code fix does it for you. The derived types that classes in referenced projects register count too. The host also logs the derived types the context lacks when it starts, for a context the build can't see, such as one built at run time. ## MC0041 The project references Microsoft.EntityFrameworkCore.Proxies, and a cached result holds a class with public `virtual` navigation properties, such as an entity that `UseLazyLoadingProxies` loads as a proxy: ```cs public class Customer { public int Id { get; set; } public virtual List Orders { get; set; } = []; } public interface ICustomers { [Cache] Task> GetAllAsync(); // MC0041 } ``` EF Core returns a proxy class made at run time instead of a `Customer`. The distributed cache can't restore a proxy, so the check before sharing keeps these results in each instance's memory, and writing one for the cache reads its navigation properties, which loads them from the database, or throws once the `DbContext` is gone. Return a type without virtual navigations instead, such as a record the query projects with `Select`: ```cs public sealed record CustomerSummary(int Id, string Name, int OrderCount); public Task> GetAllAsync() => db.Customers.Select(c => new CustomerSummary(c.Id, c.Name, c.Orders.Count)).ToListAsync(); ``` ## MC0042 A cached result type, an element of it or a type of its public properties, is one of your own types that keeps all its state in non-public fields or properties. JSON and MessagePack write public properties and fields, so such a value is written as an empty object. The check before sharing can't tell, since the empty object reads back and writes the same, so the other instances would get an empty value from the distributed cache: ```cs public sealed class Money { private readonly decimal _amount; public Money(decimal amount) => _amount = amount; public decimal Rounded() => Math.Round(_amount, 2); } [Cache] Task GetBalanceAsync(int accountId); // MC0042: Money is written as {} ``` Give the type public properties, such as `public decimal Amount { get; }` set by the constructor, or a record such as `public sealed record Money(decimal Amount)`. Or mark the fields `[JsonInclude]`, or give the type a JSON converter with `[JsonConverter]`. A converter registered only in the options passed to `UseJson` can't be seen by the build; suppress the warning then. ## MC0043 Code changes a result that a cached method or `ICacheManager.GetOrCreateAsync` returned: it sets a property or field of the result or of an object in it, adds to, removes from or sorts a collection in it, or writes to an array in it. The memory cache keeps the instance the method or call returned and hands that same instance to every later caller on this instance, so they all see the change. The other instances read the copy in the distributed cache, which doesn't have it, so instances give different answers until the entry expires: ```cs var orders = await _orders.GetForCustomerAsync(customerId); orders.Add(draft); // MC0043: every later caller on this instance gets the draft too foreach (var order in orders) order.Status = OrderStatus.Shown; // MC0043 ``` Change a copy instead: `new List(orders)` or `orders.ToList()` for the collection, and a record's `with` expression, such as `order with { Status = OrderStatus.Shown }`, for an object in it. A list copy still holds the same objects, so setting a property of one of its elements is reported too. Better still, return types that can't be changed, such as records with `init` properties and `IReadOnlyList`, so the compiler stops such code. See [results that don't change](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#results-that-dont-change). For an array, such as a `float[]` embedding, copy it before you change it: `(float[])vector.Clone()` or `vector.ToArray()`. Writing through a `Span` over the cached array, such as `vector.AsSpan()` or `Span span = vector`, or copying into it with `Array.Copy`, `Buffer.BlockCopy` or `CopyTo`, is reported too. A `ReadOnlySpan` only reads, so it isn't. It's reported for the result of a cached method, and of `GetOrCreateAsync`, `GetOrCreateManyAsync` and `TryGetAsync` on `ICacheManager`, kept in a local or read in a `foreach`. It follows objects reached from it through properties, fields, indexers, `First`, `Single`, `Last`, `ElementAt` and `Find`, through LINQ copies such as `ToList`, `ToArray` and `Where`, and through spans over its arrays. It looks only at the method that holds the result, so a method of yours that changes an object isn't seen: neither one on the object, such as `order.Close()`, nor a helper you pass it to, such as `AddDraft(orders)` with `static void AddDraft(List list) => list.Add(Draft)`. A value you change after passing it to `SetAsync` isn't seen either. For those, in Development, MethodCache also compares cached values with what it stored now and then, and logs a warning naming the method when one has changed. Not reported in test projects. ## What the analyzers read from referenced projects MC0026, MC0027 and MC0030 also look at the projects yours references, and so does `TagCoverage` in MethodCache.Testing. MethodCache writes what they need into each project's assembly when it builds that project, as `[assembly: AssemblyMetadata(...)]` attributes in these generated files: | Generated file | Key | Written when | Read by | |----------------|-----|--------------|---------| | `MethodCacheHostMarkers.g.cs` | `MethodCache.CachedServices` | the project has cached services | [MC0030](#mc0030) | | `MethodCacheHostMarkers.g.cs` | `MethodCache.AddsMethodCache` | once for each method of the project that calls `AddMethodCache`, directly or through its own setup methods | [MC0030](#mc0030) | | `MethodCacheEntityMapping.g.cs` | `MethodCache.EntityFrameworkCore.Mapping` | the project maps entities with `ef.Entity(...)` | [MC0027](#mc0027) | | `MethodCacheInvalidatedTags.g.cs` | `MethodCache.InvalidatedTags` | once for each tag the project invalidates, with `{}` for a placeholder or an interpolated value; not in test projects | `TagCoverage` | | `MethodCacheRequestState.g.cs` | `MethodCache.RequestState` | once for each interface of a class whose constructor takes per-request state, or takes a class that does, such as `Data.IStats\|RavenStats\|\|IHttpContextAccessor` | [MC0026](#mc0026) | To see them, open the referenced project's generated files: under Dependencies, .NET, Source Generators, MethodCache.SourceGenerator in Rider, or Dependencies, Analyzers, MethodCache.SourceGenerator in Visual Studio. When one of these warnings looks wrong, check that file first. A project built with an older MethodCache, or not rebuilt since its setup or mapping changed, has old values: rebuild it. --- # Migrating from IMemoryCache With `IMemoryCache`, every cached method holds the same pattern: build a key, try the cache, load, store, and remember every key to remove when data changes. MethodCache moves that into an attribute on the interface.
Before: IMemoryCacheAfter: MethodCache
```cs public async Task GetUserAsync(int id) { var key = $"user:{id}"; if (_cache.TryGetValue(key, out User? user)) return user!; // Two callers can both miss and both hit the database user = await _db.LoadUserAsync(id); _cache.Set(key, user, TimeSpan.FromMinutes(10)); return user; } public async Task RenameAsync(int id, string name) { await _db.RenameAsync(id, name); _cache.Remove($"user:{id}"); // ...and every other key that held this user } ``` ```cs [Cache(Duration = "10m", Tags = ["user:{id}"])] Task GetUserAsync(int id); [CacheInvalidate(Tags = ["user:{id}"])] Task RenameAsync(int id, string name); ```
## Steps 1. Add the `MethodCache` package and call `builder.Services.AddMethodCache()` after your registrations ([Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md)). 2. If the class has no interface, extract one. Callers must use the interface, because the cache is a decorator around it. 3. Move the caching settings to `[Cache]` on the interface method, and delete the cache code from the implementation. 4. Replace each `Remove(key)` with `[CacheInvalidate(Tags = ...)]` on the method that changes the data, and give the cached methods matching tags ([Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md)). 5. Code that can't move to an attribute, such as a cached call in the middle of a method, uses `ICacheManager.GetOrCreateAsync` with the key it already has ([Manual caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/manual-caching.md)). Migrate one service at a time; both caches can run side by side. ## What maps to what | IMemoryCache | MethodCache | |--------------|-------------| | `TryGetValue` + `Set` | `[Cache]`, or `GetOrCreateAsync` with your key | | `SetAbsoluteExpiration` | `Duration` | | `SetSlidingExpiration` | `SlidingExpiration`, capped by `Duration` | | `Remove(key)` | `[CacheInvalidate]` with tags, or `InvalidateKeysAsync` | | `Size` and `SizeLimit` | `Weigher` and `WeightLimit` ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md)) | | `Priority` | Not needed: W-TinyLFU keeps the entries that are read often | | `GetOrCreateAsync`, which may run the factory several times at once | Concurrent misses share one call | | A separate `IDistributedCache` | `AddMethodCache(mc => mc.UseRedis(...))`, with the memory cache kept in sync ([Distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md)) | ## Differences to know - **Keys are generated** from the method and its arguments ([Cache keys](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md)). Check that every argument that changes the result is a parameter, not a field of the class. - **`null` is cached** by default. Set `MethodCacheMemoryOptions.CacheNullValues = false` ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#null-values)) if your old code skipped `null`. - **Exceptions are never cached**, as before. ## State that isn't a cache `IMemoryCache` often holds more than results that can be loaded again: a marker that a notification was sent, a throttle counter, a lock, a record of a request that was already handled, an "in progress" flag. Leave those where they are, or move them to a store with atomic writes, such as a database row or Redis `SET NX`. MethodCache treats every entry as something it may lose: - An entry can disappear at any time: it expires, is evicted when memory is full, is invalidated, or is cleared when an instance loses its backplane connection. - A write to the distributed cache that fails is logged, and the caller still gets its value. - Concurrent callers share one load per instance; two instances that miss at once both load. So a lost "already sent" marker sends again, and a lock kept in a cache doesn't lock. Cache what a read returns, and keep anything that decides whether an action runs where a missing value is an error rather than a miss. --- # MethodCache.Redis Redis as MethodCache's distributed cache. Results are shared between application instances, and invalidations reach every instance's in-memory cache over Redis pub/sub. Install it at the same version as `MethodCache`. ## Usage ```cs builder.Services.AddMethodCache(mc => mc.UseRedis("localhost:6379")); ``` With options: ```cs builder.Services.AddMethodCache(mc => mc .UseRedis(options => options.Configuration = "redis1:6379,redis2:6379,password=...") .Distributed(options => options.KeyPrefix = "orders-api:")); // data and backplane use the same final prefix ``` To share a connection your app already has instead: ```cs builder.Services.AddMethodCache(mc => mc.UseRedis(options => options.ConnectionMultiplexerFactory = sp => sp.GetRequiredService())); ``` - Set `Configuration` or `ConnectionMultiplexerFactory`. Startup fails when neither is set, so a missing configuration section never makes MethodCache connect to `localhost`. - MethodCache keeps its own cache and connection, so your app's `IDistributedCache` and Redis settings are left alone. - The connection opens on first use, on the thread pool, so the application starts while Redis is down and a slow connect never holds up a call. - MethodCache doesn't dispose a shared connection. Disposing the service provider removes MethodCache's own subscriptions. ### Invalidations only When each process should keep its own values and only hear about invalidations, such as a worker that changes data an API caches, set `StoreValuesByDefault = false` in every process. Values stay in each process's memory, for cached methods and manual calls alike, only those that set `Distributed` to `true` are written to Redis, and an invalidation in one process reaches all of them through pub/sub: ```cs builder.Services.AddMethodCache(mc => mc .UseRedis("localhost:6379") .Distributed(o => o.StoreValuesByDefault = false)); // values stay in memory; invalidations reach every process ``` See [Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only). ## How it works - MethodCache reads Redis on an in-memory miss and writes new results to both. - Invalidating a tag stores the time of the invalidation, and entries with that tag written before it are treated as missing, so no tag sets are kept in Redis. An older invalidation that arrives late never undoes a newer one. - Every invalidation is also published on the `invalidations` channel, so every instance drops its in-memory copies at once. - Pub/sub delivers nothing while a connection is down. When the instance is subscribed again, it clears its in-memory cache. Reconnecting retries after 1 second, then twice as long each time, up to 30 seconds. ## Memory and eviction Invalidations are stored as keys beside the entries. If Redis evicts one under memory pressure, the entries it invalidated are served again until they expire. Set `maxmemory-policy noeviction` on the Redis MethodCache uses (or give it a Redis of its own) and give it enough memory. The `volatile-*` policies, the default of some managed Redis services, can evict them too. A full Redis with `noeviction` refuses writes, which MethodCache handles like an outage. See [Keep invalidations from being evicted](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#keep-invalidations-from-being-evicted). ## When Redis is down MethodCache keeps answering from memory and your methods; Redis never fails or stalls a call. Each call is capped at `OperationTimeout` (1 second), Redis is skipped for `CircuitBreakerDuration` (10 seconds) after a failure, and invalidations are queued and retried instead of throwing. The first failure and the recovery are logged. The [distributed cache guide](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md) covers outages, consistency between instances, serialization and the `DistributedCacheOptions` that tune all of this. The exact behavior is in the [distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md). ## Options | Option | Default | Description | |--------|---------|-------------| | `Configuration` | none | StackExchange.Redis configuration string | | `ConnectionMultiplexerFactory` | none | Returns an existing connection to share instead of opening one | | `EnableBackplane` | `true` | Send invalidations to other instances over pub/sub | `DistributedCacheOptions.KeyPrefix` applies to values, invalidations and the channel, so applications under one prefix share their entries and invalidations, and a prefix of its own keeps an application apart in both. Keys you pass to `ICacheManager` carry no type, so under a shared prefix the same key is one entry in every application ([Several applications on one store](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#several-applications-on-one-store)). The first instance that uses a prefix fixes its minimum `TagRetention`; a shorter setting fails at startup, so use a new prefix to lower it. --- # MethodCache.SqlServer SQL Server as MethodCache's distributed cache. Results are shared between application instances, and invalidations reach every instance's in-memory cache through a table that each instance polls. Install it at the same version as `MethodCache`. ## Why this package - **One shared cache for every instance.** Results live in each instance's memory and in SQL Server, so a result one instance computed is a hit for the others, and survives restarts. - **Invalidation reaches every instance.** Invalidating a key or tag removes it from SQL Server, and every other instance drops its in-memory copy on its next poll (every second by default). - **Tags work across instances**, without tag tables: invalidating a tag stores when it happened, stored atomically so a late, older invalidation never undoes a newer one. - **No new infrastructure.** If you already run SQL Server, the schema and tables are created when the application starts. - **SQL Server never breaks your app.** Calls are capped at one second, a circuit breaker skips SQL Server while it is down, and invalidations are queued until it is back. Microsoft's `AddDistributedSqlServerCache()` (`SqlServerCache`) can't be used for this: it has no atomic invalidation timestamps, so MethodCache rejects it at startup, and it has no way to tell other instances to drop their in-memory copies. This package uses the same table layout, adds both, and keeps its own cache instance so your app's `IDistributedCache` is left alone. ## SQL Server or Redis? | | SQL Server | Redis | |---|---|---| | Infrastructure | The SQL Server you already have | A Redis server | | Other instances drop their in-memory copy | On their next poll (every second by default) | At once (pub/sub) | | Load when idle | Every instance polls the invalidations table | None | | Each distributed cache read or write | A SQL Server query | A Redis command | Choose SQL Server when you already run it and a delay of about a second before other instances see an invalidation is fine; choose [Redis](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.Redis/README.md) when invalidations must reach other instances at once, or many instances would poll the database. Only Microsoft SQL Server is supported: the package uses T-SQL locking hints and `Microsoft.Data.SqlClient`. For PostgreSQL, use [MethodCache.PostgreSql](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/README.md), whose backplane also reaches other instances at once; MySQL and other databases are not supported. ## Usage ```cs builder.Services.AddMethodCache(mc => mc.UseSqlServer(builder.Configuration.GetConnectionString("Cache")!)); ``` With options: ```cs builder.Services.AddMethodCache(mc => mc.UseSqlServer(options => { options.ConnectionString = connectionString; options.SchemaName = "cache"; options.BackplanePollingInterval = TimeSpan.FromMilliseconds(500); })); ``` ### Invalidations only When each process should keep its own values and only hear about invalidations, such as a worker that changes data an API caches, set `StoreValuesByDefault = false` in every process. Values stay in each process's memory, for cached methods and manual calls alike, only those that set `Distributed` to `true` are written to SQL Server, and an invalidation in one process reaches all of them on their next poll: ```cs builder.Services.AddMethodCache(mc => mc .UseSqlServer(builder.Configuration.GetConnectionString("Cache")!) .Distributed(o => o.StoreValuesByDefault = false)); // values stay in memory; invalidations reach every process ``` The tables are the same as for a full distributed cache. See [Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only). ## Tables By default the schema and three tables are created when the application starts, if they do not exist. Startup waits at most three seconds for that; if SQL Server is down, creation is retried in the background and methods run uncached until it succeeds. - `MethodCache` holds the entries, in the layout `Microsoft.Extensions.Caching.SqlServer` uses (the same as `dotnet sql-cache create`). - `MethodCacheSchema` contains the schema version (currently 1). Existing unversioned or unknown schemas are rejected. - `MethodCacheInvalidations` holds recent invalidations for the backplane. Applications that share it are kept apart by `KeyPrefix` (compared exactly, whatever the SQL collation). If the application's login may not create tables, set `CreateTablesIfMissing = false` and create them in a migration instead. ### Required backplane schema The invalidations table needs a `Scope binary(32) NOT NULL` column and the indexes `Index_Scope_Id (Scope, Id)` and `Index_Scope_CreatedAt (Scope, CreatedAt)`. MethodCache refuses a table without them instead of changing it, and logs the error; an error found during the startup wait also fails startup. With `CreateTablesIfMissing = false`, create the current schema yourself. ## When SQL Server is down MethodCache keeps answering from memory and your methods; SQL Server never fails or stalls a call. - Every SQL Server call is capped at `OperationTimeout` (1 second). - After a failure or timeout, MethodCache skips SQL Server for `CircuitBreakerDuration` (10 seconds), then one call checks whether it is back. The first failure and the recovery are logged. - Invalidations that SQL Server doesn't accept are queued and retried until it does. They never throw. Until they are stored, this instance doesn't read entries from SQL Server, so an invalidated value can't come back. - A value set directly while SQL Server is down stays in this instance's memory; the value it replaced is removed from SQL Server and the other instances once SQL Server is back. - `ClockSkewTolerance` (2 seconds) covers servers whose clocks differ: a tag invalidation also applies to entries created up to that long after it. ```cs builder.Services.AddMethodCache(mc => mc.Distributed(options => { options.OperationTimeout = TimeSpan.FromMilliseconds(500); options.CircuitBreakerDuration = TimeSpan.FromSeconds(30); })); ``` ## Options | Option | Default | Description | |--------|---------|-------------| | `ConnectionString` | (required) | SQL Server connection string | | `SchemaName` | `dbo` | Schema of the cache, invalidations and schema-version tables | | `TableName` | `MethodCache` | Table for cache entries | | `InvalidationsTableName` | `MethodCacheInvalidations` | Table the backplane uses | | `ConnectionStringFactory` | none | Resolves a connection string once from DI at binding | | `CreateTablesIfMissing` | `true` | Create the schema and tables at startup | | `EnableBackplane` | `true` | Share invalidations with other instances | | `BackplanePollingInterval` | 1 second | How often each instance reads new invalidations | | `BackplaneRetention` | 1 hour | How long invalidations are kept; at least one minute. Instances that share a `KeyPrefix` keep them as long as the longest retention any of them has used | ## How it works - Cache commands never join your `TransactionScope`: MethodCache sets `Enlist=false` on its connection string, so a scope that rolls back doesn't undo cache writes or invalidations, and never becomes a distributed transaction. - MethodCache reads SQL Server on an in-memory miss and writes new results to both. - Expired rows are removed by one `DELETE` every 5 minutes on each instance. With a very large table, keep an index on `ExpiresAtTime` (`dotnet sql-cache create` and `CreateTablesIfMissing` add one). - Values are JSON by default. A method whose results don't read back unchanged stays in memory only, with one warning ([Serialization](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#serialization)). For MessagePack, add `MethodCache.Serialization.MessagePack` and call `UseMessagePack()`. - Keys are stored as a SHA-256 hash of the exact key, so keys that SQL collation would treat as equal (casing, trailing spaces) stay distinct, and keys of any length fit. - Invalidating a tag stores the time of the invalidation, and entries with that tag written before it are treated as missing, so no tag tables are needed. An older invalidation that arrives late never undoes a newer one. - Every invalidation also adds a row to the invalidations table. Other instances read new rows every `BackplanePollingInterval` and drop their in-memory copies. A long-running transaction elsewhere never holds back newer invalidations. - An instance that couldn't read the invalidations table for half of `BackplaneRetention` may have missed invalidations, so it clears its in-memory cache. - Each instance deletes its prefix's old invalidation rows every minute. Rows are kept for the longest `BackplaneRetention` any instance of the prefix has used, so a rolling deployment never deletes rows another instance still needs. Rows of a prefix that no application uses any more are never deleted; delete them by hand. - `DistributedCacheOptions.KeyPrefix` keeps applications that share the tables apart. The first instance that uses a prefix fixes its minimum `TagRetention`; a shorter setting fails at startup. The exact behavior is in the [distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md). ## Upgrading from before 1.0 An invalidations table from before 1.0 has no schema version, and MethodCache refuses it. Stop every old instance, back up the database and run [`0001-version-existing-schema.sql`](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.SqlServer/migrations/0001-version-existing-schema.sql) before starting the new version. --- # MethodCache.PostgreSql PostgreSQL as MethodCache's distributed cache. Results are shared between application instances, and invalidations reach every instance's in-memory cache through a table, announced at once with `LISTEN`/`NOTIFY`. Install it at the same version as `MethodCache`. ## Why this package - **One shared cache for every instance.** Results live in each instance's memory and in PostgreSQL, so a result one instance computed is a hit for the others, and survives restarts. - **Invalidation reaches every instance at once.** Invalidating a key or tag removes it from PostgreSQL, and a notification tells every other instance to drop its in-memory copy, typically within milliseconds. A poll every second catches anything a notification missed. - **Tags work across instances**, without tag tables: invalidating a tag stores when it happened, stored atomically so a late, older invalidation never undoes a newer one. - **No new infrastructure.** If you already run PostgreSQL, the schema and tables are created when the application starts. - **Built for speed.** One round trip per read and per new value, prepared statements, new cache values and backplane messages committed without waiting for the disk, and values up to about 8 KB kept in the row. Small values read about as fast as from Redis ([measurements](#performance)). - **PostgreSQL never breaks your app.** Calls are capped at one second, a circuit breaker skips PostgreSQL while it is down, and invalidations are queued until it is back. ## PostgreSQL, SQL Server or Redis? | | PostgreSQL | SQL Server | Redis | |---|---|---|---| | Infrastructure | The PostgreSQL you already have | The SQL Server you already have | A Redis server | | Other instances drop their in-memory copy | At once (`NOTIFY`), with a poll every second as a safety net | On their next poll (every second by default) | At once (pub/sub) | | Load when idle | One small query per instance and second | One small query per instance and second | None | | Each distributed cache read or write | One prepared statement (two to replace a live value) | A SQL Server query | A Redis command | Choose PostgreSQL when you already run it; choose [Redis](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.Redis/README.md) for the lowest latency with large values or a very high write rate, or when you would rather keep cache traffic away from your database. Requires PostgreSQL 13 or later. Provider, atomic metadata and serializer contracts are internal. ## Usage ```cs builder.Services.AddMethodCache(mc => mc.UsePostgreSql(builder.Configuration.GetConnectionString("Cache")!)); ``` With options: ```cs builder.Services.AddMethodCache(mc => mc.UsePostgreSql(options => { options.ConnectionString = connectionString; options.SchemaName = "cache"; options.CreateTablesIfMissing = false; // tables created by migrations/0001-create-schema.sql })); ``` MethodCache keeps its own connection pool (an `NpgsqlDataSource`), so your app's data sources, `DbContext` and `IDistributedCache` are left alone. ### Invalidations only When each process should keep its own values and only hear about invalidations, such as a worker that changes data an API caches, set `StoreValuesByDefault = false` in every process. Values stay in each process's memory, for cached methods and manual calls alike, only those that set `Distributed` to `true` are written to PostgreSQL, and an invalidation in one process reaches all of them through `NOTIFY`: ```cs builder.Services.AddMethodCache(mc => mc .UsePostgreSql(connectionString) .Distributed(o => o.StoreValuesByDefault = false)); // values stay in memory; invalidations reach every process ``` The tables are the same as for a full distributed cache. See [Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only). ### Passwordless login A database that logs in with a token instead of a password, such as Azure Database for PostgreSQL with Microsoft Entra ID or Amazon RDS with IAM, gets the token through `ConfigureDataSource`. MethodCache calls it for its connection pool and for the connection that listens for invalidations: ```cs builder.Services.AddMethodCache(mc => mc.UsePostgreSql(options => { // No password: each new connection logs in with a token, refreshed before it expires options.ConnectionString = "Host=mydb.postgres.database.azure.com;Database=app;Username=app-identity;SSL Mode=Require"; options.ConfigureDataSource = dataSource => dataSource.UsePeriodicPasswordProvider( (_, cancellationToken) => getAccessToken(cancellationToken), successRefreshInterval: TimeSpan.FromMinutes(55), failureRefreshInterval: TimeSpan.FromSeconds(5)); })); ``` With Azure.Identity, `getAccessToken` can be `async ct => (await credential.GetTokenAsync(new(["https://ossrdbms-aad.database.windows.net/.default"]), ct)).Token`. `ConfigureDataSource` also sets client certificates or a custom server certificate check, anything an `NpgsqlDataSourceBuilder` takes. MethodCache then sets again the few settings it relies on, such as no pooling for the listening connection. ## Tables By default the schema and four tables are created when the application starts, if they do not exist. Startup waits at most three seconds for that; if PostgreSQL is down, creation is retried in the background and methods run uncached until it succeeds. Instances that start together create the tables once, under an advisory lock. - `methodcache` holds the entries: a 32-byte id, the value and its expiry time. - `methodcache_schema` contains the schema version (currently 1). Unknown versions are rejected. - `methodcache_invalidations` holds recent invalidations for the backplane. Applications that share it are kept apart by `KeyPrefix`. - `methodcache_invalidations_cursor` holds one row per `KeyPrefix` that hands out the invalidations' ids in commit order and keeps the longest `BackplaneRetention` of its instances. It is unlogged: recovery from a crash empties it, which tells every instance that the last invalidations may be lost. If the application's login may not create tables, run the package's [`migrations/0001-create-schema.sql`](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.PostgreSql/migrations/0001-create-schema.sql) once as a role that may, grant the login `SELECT, INSERT, UPDATE, DELETE` on the four tables, and set `CreateTablesIfMissing = false`. The script is written for the default names; replace them throughout if you configured others. Existing tables are checked at startup: an incompatible schema is logged as an error and never converted. An error found during the startup wait also fails startup. ## Connection poolers Cache reads and writes work through any pooler, PgBouncer in transaction mode included. Notifications need a session: each instance holds one extra, unpooled connection for `LISTEN`. Behind PgBouncer in transaction mode a `LISTEN` doesn't survive the transaction, so other instances' invalidations arrive by polling instead, within `BackplanePollingInterval`; MethodCache logs one warning when it sees this. To get them at once, use a session-mode pool or a direct connection string for MethodCache. ## When PostgreSQL is down MethodCache keeps answering from memory and your methods; PostgreSQL never fails or stalls a call. - Every PostgreSQL call is capped at `OperationTimeout` (1 second). - After a failure or timeout, MethodCache skips PostgreSQL for `CircuitBreakerDuration` (10 seconds), then one call checks whether it is back. The first failure and the recovery are logged. - Invalidations that PostgreSQL doesn't accept are queued and retried until it does. They never throw. Until they are stored, this instance doesn't read entries from PostgreSQL, so an invalidated value can't come back. - A value set directly while PostgreSQL is down stays in this instance's memory; the value it replaced is removed from PostgreSQL and the other instances once PostgreSQL is back. - The `LISTEN` connection reconnects with a delay that doubles from one second to at most 30 seconds; until then, invalidations arrive by polling. - `ClockSkewTolerance` (2 seconds) covers servers whose clocks differ: a tag invalidation also applies to entries created up to that long after it. ```cs builder.Services.AddMethodCache(mc => mc.Distributed(options => { options.OperationTimeout = TimeSpan.FromMilliseconds(500); options.CircuitBreakerDuration = TimeSpan.FromSeconds(30); })); ``` ## Options | Option | Default | Description | |--------|---------|-------------| | `ConnectionString` | (required) | PostgreSQL connection string, in the format Npgsql reads | | `SchemaName` | `public` | Schema of the four tables | | `TableName` | `methodcache` | Table for cache entries; the schema-version table is named after it | | `InvalidationsTableName` | `methodcache_invalidations` | Table the backplane uses; the cursor table is named after it | | `ConnectionStringFactory` | none | Resolves a connection string once from DI at binding | | `ConfigureDataSource` | none | Configures MethodCache's `NpgsqlDataSourceBuilder`s: a password provider for [passwordless login](#passwordless-login), client certificates or a server certificate check | | `CreateTablesIfMissing` | `true` | Create the schema and tables at startup | | `EnableBackplane` | `true` | Share invalidations with other instances | | `BackplanePollingInterval` | 1 second | How often each instance reads new invalidations when no notification arrived | | `BackplaneRetention` | 1 hour | How long invalidations are kept; at least one minute. Instances that share a `KeyPrefix` keep them as long as the longest retention any of them has used | Names are used exactly as written (quoted), at most 63 bytes, less the suffix of the tables and indexes named after them. ## Performance Medians on one machine (4 vCPU, PostgreSQL 17, Redis 7.4 and SQL Server 2022 in containers next to the app): | | PostgreSQL | Redis | SQL Server | |---|---:|---:|---:| | Read, 256 B | 0.30 ms | 0.27 ms | 1.09 ms | | Write a new key, 256 B | 0.32 ms | 0.30 ms | 2.61 ms | | Replace a live value, 256 B | 1.08 ms | 0.29 ms | 2.60 ms | | `[Cache]` method, hit in the distributed cache | 0.71 ms | 0.64 ms | 1.65 ms | | `[Cache]` method, miss | 1.85 ms | 1.09 ms | 6.29 ms | | Tag invalidation until another instance runs the method again | 9.3 ms | 2.6 ms | 984 ms | Replacing a live value waits for the disk, so a crash can't bring back the value it replaced; a miss writes a new key, which doesn't. Redis stays ahead with large values and many concurrent callers. See [benchmarks](https://github.com/eoniclabs/MethodCache/blob/main/docs/benchmarks.md#distributed-cache-providers) for value sizes, throughput and how they were measured. ## How it works - Every operation is one statement, one round trip, except replacing a live value (below). Statements are prepared automatically on each connection (`Max Auto Prepare=32`), a connection that goes back to the pool isn't reset (`No Reset On Close=true`: MethodCache changes no session state), and connections are named `MethodCache` in `pg_stat_activity`. A setting your connection string makes itself is kept, except one: cache commands never join your `TransactionScope` (`Enlist=false`), so a scope that rolls back doesn't undo cache writes or invalidations. - New cache values (and values that replace an expired one) and backplane messages are written with `synchronous_commit = off`, for that statement only: PostgreSQL acknowledges the write before flushing it to disk. If the server itself crashes, the last fraction of a second of them can be lost. A lost new value is only a miss. A lost message would leave other instances' in-memory copies, but recovery also empties the unlogged cursor table, so every instance sees a new cursor and clears its in-memory cache. A value that replaces a live one takes a second statement, committed as the server's `synchronous_commit` says, like invalidations, which keep the shared cache correct: a crash never brings back a value that was replaced or invalidated. - Values are stored as `bytea`, not `jsonb`: they are already serialized (JSON or MessagePack) and never queried, so PostgreSQL stores the bytes without parsing them. Values up to about 8 KB stay in the row, so a read needs no second lookup in the TOAST table; values from about 2 KB are compressed, with lz4 where the server supports it (PostgreSQL 14 and later). - Values are JSON written with System.Text.Json (public fields included); a method whose results don't read back unchanged stays in memory only, with one warning ([Serialization](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#serialization)). Add `MethodCache.Serialization.MessagePack` and call `UseMessagePack()` on the `AddMethodCache` builder for MessagePack. - Keys are stored as the SHA-256 of their exact UTF-16 code units, so keys PostgreSQL text can't hold (NUL characters, lone surrogates) and keys of any length get a fixed-size id. - Invalidating a tag stores the time of the invalidation, and entries with that tag written before it are treated as missing, so no tag tables are needed. A read checks the value and its invalidation in one query. - Both also add a row to the invalidations table and `NOTIFY` a channel named after the `KeyPrefix` and table. The notification carries only the sender's id: the table is the truth, and the notification only tells other instances to read it now instead of at their next poll. - The cursor row hands out ids in commit order, so a reader never sees a later id before an earlier one commits, and needs no gap tracking. - A message that fails to apply is retried on the next poll. If it still fails after five polls, the instance clears its in-memory cache in its place and moves on, so one bad message can't hold back the ones after it. - An instance that couldn't read the invalidations table, or catch up with it, for half of `BackplaneRetention` (since it last did, or since it started), or that sees a new cursor (after a crash, a failover or a restore) or the cursor go back, may have missed invalidations, so it clears its in-memory cache. - Every instance deletes expired entries every 5 minutes, and its own prefix's invalidations older than the longest `BackplaneRetention` of that prefix every minute, in small batches with `FOR UPDATE SKIP LOCKED`, so instances never wait for each other. Rows of a prefix that no running application uses any more are never deleted; delete them by hand. - `DistributedCacheOptions.KeyPrefix` keeps applications that share the tables apart. The first instance that uses a prefix fixes its minimum `TagRetention`; a shorter setting fails at startup. The exact behavior is in the [distributed cache reference](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md). --- # MethodCache.AspNetCore Admin endpoints and a health check for MethodCache's in-memory cache. Install it at the same version as `MethodCache`. ## Setup ```cs builder.Services.AddScoped(); builder.Services.AddMethodCache(); builder.Services.AddHealthChecks().AddMethodCache(); builder.Services.AddAuthorization(o => o.AddPolicy("CacheAdmins", p => p.RequireRole("Admin"))); var app = builder.Build(); app.UseAuthentication(); app.UseAuthorization(); app.MapMethodCacheAdmin("CacheAdmins"); app.MapHealthChecks("/health"); ``` The authorization policy is required, because the endpoints expose cache keys and can empty the cache; a signed-in user without the policy gets 403. ## Endpoints All paths are relative to the prefix, `/methodcache` by default. `MapMethodCacheAdmin("CacheAdmins", "/ops/cache")` maps them under `/ops/cache` instead. | Method | Path | What it does | |--------|------|--------------| | `GET` | `stats` | This instance's hits, misses, evictions, method and HTTP entries, HTTP bytes and memory weight | | `GET` | `methods` | Every cached method: its `methodId`, effective policy and where each setting comes from | | `GET` | `entries?storedKeyPrefix=&tag=&methodId=&limit=` | Live entries in the memory of the instance that answers, each with its `storedKey` and `methodId`, ordered by `storedKey` (default limit 100, max 1000). `methodId` must be an id that `methods` lists. Values are not returned | | `GET` | `entry?storedKey=` | One entry, by the `storedKey` that `entries` lists, in the memory of the instance that answers, or 404 | | `DELETE` | `entry?storedKey=` | Removes one entry, also from Redis, SQL Server or PostgreSQL and the other instances when configured. 404 only without a distributed cache, when the key isn't in memory | | `POST` | `invalidate` | Removes entries by tag. Body: `{ "tags": ["users"] }` | | `POST` | `invalidate-method` | Removes every entry of one cached method, also from the distributed cache and the other instances. Body: `{ "methodId": "[MyApp]MyApp.IUserService.GetUserAsync" }`, an id that `methods` lists | | `POST` | `clear` | Removes every entry. Body: `{}` | | `GET` | `overrides` | The runtime overrides in effect, one per method, in the format `PUT overrides` takes, with `updatedAt` | | `PUT` | `overrides` | Sets a runtime override for one method, every method in a group or every cached method. Body: a method's `appsettings.json` entry plus what it applies to, see below | | `DELETE` | `overrides?methodId=`, `?group=` or `?all=true` | Removes the override of one method, of a group's methods, or all of them | ### Runtime overrides over HTTP The body of `PUT overrides` is written like a method's entry in `appsettings.json` and read by the same code, so it takes the same settings with the same formats, and a mistake gets the same message as in a configuration file. It names what it applies to with exactly one of `MethodId`, `Group` or `"All": true`, and can say who made it and why: ```bash curl -X PUT https://localhost:5001/methodcache/overrides -H "Content-Type: application/json" \ -d '{ "Group": "pricing", "Enabled": false, "Owner": "ops", "Reason": "Incident 4211", "ExpiresAt": "2026-11-12T08:00:00Z" }' curl -X DELETE "https://localhost:5001/methodcache/overrides?group=pricing" ``` | Body property | Value | |---|---| | `MethodId`, `Group` or `All` | One method id as `methods` lists it, a group name (case-sensitive), or `true` for every cached method | | `Duration`, `SlidingExpiration`, `RefreshAhead`, `FailSafe`, `FailSafeTimeout`, `FailSafeRetryAfter`, `Tags`, `ClearTags`, `Version`, `Enabled`, `Distributed` | As in `appsettings.json` ([Configuration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson)) | | `Owner`, `Reason`, `Ticket`, `ExpiresAt` | Who made it and why, and when it is removed by itself (an ISO 8601 time; UTC when it has no offset) | A group or `"All": true` puts the same override on each method, as `IRuntimeCacheConfigurator.UpsertGroupAsync` and `UpsertAllAsync` do. With a backplane the override applies on every instance; without one, on the instance that answers. The `POST` endpoints take a JSON body, also `clear`, whose body is `{}`: ```bash curl -X POST https://localhost:5001/methodcache/clear -H "Content-Type: application/json" -d "{}" ``` That is on purpose: a browser sends a JSON request to another site only after a CORS preflight, so a page on another site can't make a signed-in admin's browser empty the cache. A request without a JSON body is answered with 415 or 400. Answers other than 200, 204 and 404: - **400**, and nothing changes: a query parameter the endpoint doesn't take, a missing or empty `storedKey` or `methodId`, a `methodId` that no cached method has, a `limit` out of range, an empty tag list, or a body with a property the endpoint doesn't take (`invalidate` takes only `tags`, `invalidate-method` only `methodId`, `clear` none). A `POST` without a body is 400 too. For `overrides`: a body that isn't a JSON object, names no target or more than one, has a setting it doesn't know or an invalid value, or doesn't fit a method it reaches (no method changes then); a `DELETE` without exactly one of `methodId`, `group` or `all=true`; a method or group that isn't cached. The message says what is wrong, as for a configuration file. - **415**: a `POST` or `PUT` whose body isn't `application/json`. - **503**: the removal is done in this instance's memory but the distributed cache hasn't confirmed it yet. The cache retries on its own; don't repeat the call. - **401** and **403**: the caller isn't signed in, or doesn't satisfy the policy. ## Audit Pass `audit` to record who changes the cache. It runs for `DELETE entry`, `invalidate`, `invalidate-method`, `clear`, `PUT overrides` and `DELETE overrides`, after authorization and validation and before the change: ```cs var audit = app.Services.GetRequiredService().CreateLogger("CacheAdminAudit"); app.MapMethodCacheAdmin("CacheAdmins", audit: (action, cancellationToken) => { // OverrideMetadata is the Owner, Reason, Ticket and ExpiresAt of an override; null for the other kinds audit.LogInformation("{User} ran {Action} on {Targets} at {Time}, reason {Reason}", action.User.Identity?.Name, action.Kind, action.Targets, action.Time, action.OverrideMetadata?.Reason); return ValueTask.CompletedTask; }); ``` `MethodCacheAdminAction` has: | Property | Value | |---|---| | `Kind` | `RemoveEntry`, `InvalidateTags`, `InvalidateMethod`, `Clear`, `UpsertOverride` or `RemoveOverride` | | `Targets` | The stored key, the tags or the method id; empty for `Clear`. For an override: the method id, `group:`, or `*` for every method | | `User` | The signed-in user, `HttpContext.User` | | `Time` | When the request arrived, from the app's `TimeProvider` | | `OverrideMetadata` | For `UpsertOverride`: the `Owner`, `Reason`, `Ticket` and `ExpiresAt` from the body, or `null` when it gives none. `null` for the other kinds | | `HttpContext` | The request, for anything else you record, such as the client's address or the trace id | The record says who asked for what; it holds no before and after. The function runs before the change, so to record the overrides a change replaces, read them there with `IRuntimeCacheConfigurator.GetOverrides()` from `action.HttpContext.RequestServices`. `GET overrides` shows the state after it. To test an audit function, build the action yourself: `new MethodCacheAdminAction(MethodCacheAdminActionKind.UpsertOverride, ["group:pricing"], new DefaultHttpContext { User = admin }, now, new RuntimeOverrideMetadata { Reason = "Incident 4211" })`. When the function throws, the request fails and nothing changes, so no change goes unrecorded. Reads and rejected requests (400, 401, 403, 415) aren't passed to it. A change answered with 503 is recorded, since it has removed the entries from this instance's memory. Write the record somewhere the admins can't edit, such as your log pipeline or an append-only table. The same operations are available in code through `ICacheAdministrator` in the `MethodCache` namespace (see [Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md)). ## Health check `AddMethodCache()` on the health checks builder reports: | Key | Value | |---|---| | `managerCapability` | `built_in`, `noop` or `custom` (your own `ICacheManager`) | | `statisticsAvailable` | Whether the statistics below are reported | | `methodStatisticsAvailable` | Whether method statistics are reported: only for the built-in manager | | `httpCapability` | `not_configured`, `local` or `distributed`: whether `AddHttpCaching` is registered, and where it stores responses | | `localMethodEntries`, `totalWeight`, `evictions` | Built-in manager only. Weight uses the configured weigher's units, or one per method entry | | `localHttpEntries`, `localHttpBytes`, `observedDistributedEntries` | When statistics are available | | `queued`, `publicationQueued` | Invalidations waiting for the distributed cache, and for the backplane | | `backplaneStatus` | `not_configured`, `connecting`, `connected`, `disconnected` or `unknown` | | `distributedCacheAvailable` | Whether the distributed cache answers; only when one is configured | | `error.type` | Only when the check itself failed: the exception type | The check reports the registration's `failureStatus` (default `Degraded`) when the distributed cache doesn't answer, invalidations are waiting to be retried, or the backplane is connecting or disconnected. The distributed cache and the backplane are reported separately. The check waits at most `OperationTimeout`, and reports exception types, never exception messages. ## Limits - Works with the default in-memory cache manager. With your own `ICacheManager`, the endpoints need the `ICacheAdministrator` that `AddHttpCaching` registers, and it covers HTTP responses only: `methods` is empty, `clear` removes HTTP responses only, and `invalidate-method` answers 400. - `overrides` needs MethodCache's own `IRuntimeCacheConfigurator`; with one the application registers instead, it answers 501. --- # MethodCache.OpenTelemetry MethodCache produces standard .NET metrics and traces. This package adds `AddMethodCacheInstrumentation()` to the OpenTelemetry tracer and meter builders, which subscribes to them (`AddMeter` and `AddSource` with `MethodCacheTelemetry.Name`). Your app supplies the OpenTelemetry SDK and exporters. Install it at the same version as `MethodCache`. ## Setup ```bash dotnet add package MethodCache.OpenTelemetry dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol ``` ```cs builder.Services.AddMethodCache(); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing .AddAspNetCoreInstrumentation() .AddMethodCacheInstrumentation() .AddOtlpExporter()) .WithMetrics(metrics => metrics .AddMethodCacheInstrumentation() .AddOtlpExporter()); ``` `AddOpenTelemetry()` and `AddMethodCache()` can come in either order. The meter and activity source are named `MethodCache` (`MethodCacheTelemetry.Name`), so any `MeterListener` or `dotnet-counters monitor --counters MethodCache` sees them without this package. For Prometheus, use OpenTelemetry's Prometheus exporter with `AddMethodCacheInstrumentation()`. ## Privacy options Configure `MethodCacheTelemetryOptions` in `AddMethodCache`: ```cs builder.Services.AddMethodCache(mc => mc.Telemetry(options => { options.RecordCacheKeys = true; // hashes by default; raw keys can contain secrets options.RecordCacheTags = false; })); ``` | Option | Default | Meaning | |---|---|---| | `RecordCacheKeys` | `false` | Include keys on operation spans | | `HashCacheKeys` | `true` | Record a SHA-256 hash of each key instead of the key | | `RecordCacheTags` | `false` | Include application tags on operation spans | A hash is a stable identifier, not anonymization, and keys and tags can contain secrets. These options never add metric dimensions. MethodCache adds no baggage, copies no HTTP or URL attributes, and records no exception messages or stack traces; your application's own activity context and baggage flow as usual. See [Security](https://github.com/eoniclabs/MethodCache/blob/main/docs/security.md). ## Spans | Span | Kind | Attributes | |---|---|---| | `MethodCache.load` | Internal | `methodcache.kind`, `methodcache.method` or `methodcache.http.client`, `methodcache.bulk`; `error.type` on failure | | `MethodCache.distributed` | Internal | `methodcache.operation`; `error.type` on failure | | `MethodCache.invalidate` | Internal | `methodcache.invalidation.type` | `MethodCache.load` covers a run of your method, background refreshes included. Callers that join a running load, values read from the distributed cache and memory hits create none. A failure sets the Error status without the exception's message. With the privacy options above, keys and tags are recorded as `methodcache.key`, `methodcache.keys` and `methodcache.tags`. `MethodCache.distributed` is an internal span, so the client spans of the Redis and SqlClient instrumentations nest under it. Every attribute is in the `methodcache.` namespace, apart from the standard `error.type`: | Attribute | Values | |---|---| | `methodcache.kind` | `method` (a cached method), `manual` (an `ICacheManager` call by key), `http` (an `HttpClient` response) | | `methodcache.method` | The method id, for `kind=method` | | `methodcache.http.client` | The `HttpClient` name, for `kind=http` | | `methodcache.bulk` | `true` on a manual `GetOrCreateManyAsync` batch | | `methodcache.result` | `hit`, `miss`, `stale`, `revalidated`, `bypass` or `error` | | `methodcache.invalidation.type` | `key`, `tag`, `method` or `clear` | | `methodcache.invalidation.stage` | `local`, `distributed`, `queued`, `published` or `publication_queued`; on the queue gauge `storage` or `publication` | | `methodcache.operation` | `get`, `set`, `remove` or `invalidate` | A manual call has no attribute naming what was cached, so it adds no series per key. ## Metrics | Instrument | Type / unit | Dimensions | |---|---|---| | `methodcache.requests` | Counter / `{request}` | `methodcache.kind`, `methodcache.method` or `methodcache.http.client`, `methodcache.bulk`, `methodcache.result` | | `methodcache.load.duration` | Histogram / `s` | `methodcache.kind`, `methodcache.method` or `methodcache.http.client`, `methodcache.bulk`, `error.type` on failure | | `methodcache.entries` | ObservableUpDownCounter / `{entry}` | `methodcache.kind=method/http`; entries in this instance's memory | | `methodcache.evictions` | ObservableCounter / `{entry}` | `methodcache.kind=method/http`; entries this instance removed to make room since it started | | `methodcache.http.size` | ObservableUpDownCounter / `By` | Bytes of HTTP responses in this instance's memory; 0 when they are stored in the distributed cache | | `methodcache.invalidations` | Counter / `{invalidation}` | `methodcache.invalidation.type`, `methodcache.invalidation.stage` | | `methodcache.distributed.duration` | Histogram / `s` | `methodcache.operation`, `error.type` on failure | | `methodcache.distributed.queue` | ObservableUpDownCounter / `{invalidation}` | `methodcache.invalidation.stage=storage/publication`; distinct pending targets | The two histograms advise bucket boundaries in seconds, from 5 ms to 10 s (0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10), like ASP.NET Core's `http.server.request.duration`. A view in your SDK setup can replace them. - Each call records one outcome. A background refresh records a load duration but no request. A bulk call counts once and times its one batch factory call. A cached `null` is a hit. - `methodcache.method` is the method id (generic methods once, not per type argument); arguments never create series. - Invalidation stages count the same targets at each stage; don't add them together. - Entry gauges count this instance's memory only, not the distributed cache. - `methodcache.evictions` counts entries removed because the memory cache reached `MaxItems` or `WeightLimit`, not entries that expired or were invalidated. A rising rate while the hit ratio drops says the cache is too small. - There is no hit-ratio instrument: compute it from `methodcache.requests`, per method with `methodcache.method` ([Hit ratio per method](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#hit-ratio-per-method)). Memory weight is `TotalWeight` on `ICacheAdministrator`. ## Troubleshooting If no spans appear, call `AddMethodCacheInstrumentation()` on the tracer builder and check the SDK's sampler. If no metrics appear, call it on the meter builder. MethodCache works with any `MeterListener` or `ActivityListener` without this package. Counters start when a listener subscribes; gauges show the current state at once. ## License MIT. See [LICENSE](https://github.com/eoniclabs/MethodCache/blob/main/LICENSE). --- # 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](https://github.com/eoniclabs/MethodCache/tree/main/samples/MethodCache.Demo#httpclient-caching) to see cache hits, ETag validation, `no-store` and PUT invalidation against a real local HTTP server. ```cs builder.Services.AddMethodCache(); builder.Services.AddHttpClient() .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`, `PATCH` or `DELETE` removes the cached responses for that URL (and for same-origin `Location` / `Content-Location`) for every caller, language and key header value, so nobody reads stale data after a write. - Cached responses carry an `Age` header, as the standard requires. - `Set-Cookie` is 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 `GET` with a body goes to the origin. - Request directives are honored: `no-cache` (revalidates and stores the answer), `no-store`, `max-age`, `max-stale`, `min-fresh` and `only-if-cached`. - `Range` requests go to the origin, and `206 Partial Content` is never stored. - Requests that carry their own `If-None-Match` or `If-Modified-Since` go to the origin, so your `304` reaches you. - Statuses that are cacheable by default (`200`, `203`, `204`, `301`, `404`, ...) are stored; other `2xx` responses only when they say how long they stay fresh (`max-age` or `Expires`). ## Settings Settings are per HttpClient: ```cs builder.Services.AddHttpClient() .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](https://github.com/eoniclabs/MethodCache/blob/main/docs/security.md#methodcachehttpcaching)) | | `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](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/http-caching.md) 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: ```cs 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. ```cs 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](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/http-caching.md) 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. --- # MethodCache.Serialization.MessagePack Stores MethodCache's distributed cache values (Redis, SQL Server or PostgreSQL) as compact MessagePack instead of the default System.Text.Json: smaller entries and faster reads. Install it at the same version as `MethodCache`. ## Install ```bash dotnet add package MethodCache.Serialization.MessagePack ``` ## Register ```cs builder.Services.AddMethodCache(mc => mc .UseRedis("localhost:6379") .UseMessagePack()); // MethodCache.Serialization.MessagePack ``` Call `UseMessagePack()` with `UseRedis(...)`, `UseSqlServer(...)` or `UsePostgreSql(...)`, in any order; without one it does nothing and logs a warning at startup. Entries written in the other format read as misses and are replaced, so switching needs no flush. ## When to use it - Values are large or read often from the distributed cache. It has no effect on the in-memory cache, which stores your objects as they are. - Types serialize without attributes (contractless resolver). The defaults use LZ4 compression, keep `DateTime` values as they are, and read stored data with `MessagePackSecurity.UntrustedData`. - Like JSON, the contractless resolver doesn't restore private setters. A derived type where its base type is declared, such as a `Dog` in a `List`, comes back as itself, since MethodCache names the derived types it finds to the serializer ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)). A base type with `[Union]` keeps its own settings. With the default `VerifyRoundTrip = true`, MethodCache reads every value back before sharing it, and keeps values that don't survive that in memory only, with one warning per method and type. - To change them, start from MethodCache's defaults: `UseMessagePack(o => o.WithCompression(MessagePackCompression.None))` gets the defaults above and returns the options to use, so the rest stays as it was. Keep `UntrustedData` and don't enable typeless payloads: the distributed cache must not choose which types get created (see [Security](https://github.com/eoniclabs/MethodCache/blob/main/docs/security.md#distributed-cache-redis-sql-server)). - `UseMessagePack` changes how values are stored, never cache keys. Use `ICacheKeyProvider` for custom argument parts. The check cannot detect lost nested derived/private state that was absent from the first serialized representation. Configure the serializer for your model. Increment method `Version` or `DistributedCacheOptions.SerializerVersion` when changing the representation. --- # MethodCache.EntityFrameworkCore Invalidates MethodCache tags when Entity Framework Core commits a change. Map an entity type to the tags of the cached methods that read it, and every save that adds, changes or deletes one of its rows invalidates them, after the data is committed, never before. Install it at the same version as `MethodCache`. ## Why this package - **No invalidation code in your writes.** An endpoint that loads an entity, changes it and calls `SaveChangesAsync` invalidates the right tags by itself. - **Never too early.** Inside a transaction the tags wait for the commit, so no reader caches the old rows in between, and a rollback drops them. `TransactionScope` works too. - **Old and new values.** Moving a row to another category invalidates both categories, also when you update or delete the row without loading it first. - **The same tags as your methods.** `"product:{Id}"` on the entity matches `"product:{id}"` on a `[Cache]` method, formatted the same way, and a name that is not a property stops the host at startup. - **Rows the database deletes for you.** `Entity(user => user.WhenDeleted("posts"))` invalidates tags only when a user is deleted, for rows that `ON DELETE CASCADE` removes with it, while a user saved on every sign-in clears nothing. - **A warning where it can't help.** `ExecuteUpdate` and `ExecuteDelete` on a mapped type and raw SQL go past the change tracker; analyzer MC0027 reports them when the method doesn't invalidate. Mark your own invalidation helpers `[InvalidatesCache]` and a call to them counts. MC0028 reports a tag on a cached method that nothing in the project invalidates. ## Usage ```cs builder.Services.AddDbContext(o => o.UseSqlite(connectionString)); builder.Services.AddScoped(); builder.Services.AddMethodCache(mc => mc.UseEntityFrameworkCore(ef => ef .Entity("product:{Id}", "category:{CategoryId}") .Entity("top-sellers"))); ``` ```cs public static async Task ChangePriceAsync(int id, decimal price, ShopDb db, CancellationToken ct) { var product = await db.Products.SingleAsync(p => p.Id == id, ct); product.Price = price; // Invalidates product:{id} and category:{CategoryId} once the save succeeded await db.SaveChangesAsync(ct); } ``` For a write the change tracker doesn't see, queue the tags yourself: ```cs public static async Task RecalculateAsync(ShopDb db, IMethodCacheKeys keys, int categoryId, CancellationToken ct) { await using var transaction = await db.Database.BeginTransactionAsync(ct); await db.Products .Where(p => p.CategoryId == categoryId) .ExecuteUpdateAsync(s => s.SetProperty(p => p.Price, p => p.Price * 1.1m), ct); // ExecuteUpdateAsync goes past the change tracker: name the tags it changes db.InvalidateAfterCommit(keys.Tag(r => r.ListAsync(categoryId), "category:{categoryId}")); await transaction.CommitAsync(ct); } ``` Works with SQL Server, PostgreSQL, SQLite and the other relational providers, and on `SaveChanges` also with Cosmos DB and MongoDB. The full guide, with when exactly each tag is invalidated, is [Entity Framework Core](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md). With row-level security, cached reads need a context of their own: see [Row-level security](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/entity-framework-core.md#row-level-security). --- # MethodCache.Testing Helpers for tests of the caching itself: a fake clock, a recorder that counts how often your implementation ran and what was invalidated, a check that every cached service resolves to its caching decorator, and a check that every cache tag has something that invalidates it. Install it in the test project, at the same version as `MethodCache`. ```bash dotnet add package MethodCache.Testing ``` ## Recorder and fake clock `AddMethodCacheTesting()` registers a `FakeTimeProvider` as the container's `TimeProvider` and a `CacheRecorder`. Build the provider as the application does and resolve both: ```cs var services = new ServiceCollection(); services.AddSingleton(); services.AddScoped(); services.AddMethodCache(); services.AddMethodCacheTesting(); // a fake clock and a recorder await using var provider = services.BuildServiceProvider(); var recorder = provider.GetRequiredService(); var time = provider.GetRequiredService(); var products = provider.CreateScope().ServiceProvider.GetRequiredService(); await products.GetAsync(42); await products.GetAsync(42); Assert.Equal(1, recorder.Loads(p => p.GetAsync(42, default))); // the second call was a hit await products.UpdateAsync(42, new Product(42, "Green tea", 5m)); Assert.Contains("product:42", recorder.InvalidatedTags); await products.GetAsync(42); Assert.Equal(2, recorder.Loads(p => p.GetAsync(42, default))); time.Advance(TimeSpan.FromMinutes(11)); // past the Duration of 10 minutes await products.GetAsync(42); Assert.Equal(3, recorder.Loads(p => p.GetAsync(42, default))); ``` `Loads` counts the runs of one call, with its arguments; a hit doesn't count. `InvalidatedTags` and `InvalidatedKeys` list what `[CacheInvalidate]` methods, `ICacheManager` calls and MethodCache.EntityFrameworkCore invalidated, in order. `Clear()` forgets what a test's setup recorded. The clock starts at 2000-01-01 and only moves when the test advances it, so nothing expires on its own. The recorder sees the built-in cache manager: with `NoOpCacheManager` or your own `ICacheManager` it records nothing. ## Every cached service resolves `CachedServices.ProblemsAsync` resolves each registered service with cached methods and checks that it is the generated caching decorator, so a service registered after `AddMethodCache` or one with a missing dependency fails a test instead of the application's startup: ```cs // Every service with cached methods resolves, and to its generated caching decorator Assert.Empty(await CachedServices.ProblemsAsync(provider)); ``` When resolving the services needs a database or a key vault the test doesn't have, `CachedServices.RegistrationProblems` checks the registrations only and resolves nothing: ```cs // Every service with cached methods is registered before AddMethodCache; resolves none of them Assert.Empty(CachedServices.RegistrationProblems(provider)); ``` Both throw `InvalidOperationException` when the provider has no service with cached methods, so a test with the wrong provider can't pass without checking anything. Neither can see a service the application never registers. `CachedServices.Registered` lists the registered services with cached methods, ordered by full name, for a test to compare with the services the application should have: ```cs // The application registers exactly these services with cached methods, none forgotten Assert.Equal([typeof(IProductService)], CachedServices.Registered(provider)); ``` A list written by hand goes stale when someone adds a cached interface and forgets to register it, which is the mistake the test is there for. `CachedServices.Declared` lists the interfaces with cached methods in the assemblies you pass, in the same order, so the test covers a new interface without a change: ```cs // Every interface with cached methods in the application's project is registered Assert.Equal(CachedServices.Declared(typeof(IProductService).Assembly), CachedServices.Registered(provider)); ``` ## How each method is cached `CachedServices.Method` returns how one method is cached, as `ICacheAdministrator.GetMethods()` reports it, found by a call instead of a method id string: ```cs // How ListAsync is cached, from its attribute, startup code and configuration together var list = CachedServices.Method(provider, p => p.ListAsync(Guid.Empty)); Assert.Equal(TimeSpan.FromMinutes(5), list.Lifetime.Duration); Assert.Equal(["tenantId"], list.KeyParameters); Assert.Empty(list.ReplacedSources); // no source replaces what another one sets for it ``` The call runs on a stand-in, so the method never runs and the arguments don't matter: pass `""`, `0`, `Guid.Empty` or `default`. [Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#how-each-method-is-cached) shows how to assert on a setting that startup code replaces on purpose. ## Every tag has an invalidation `TagCoverage.Uninvalidated` lists the tags of the cached methods, from attributes, startup code and configuration, that nothing invalidates. It counts the `[CacheInvalidate]` methods of the registered services, the entity mapping of MethodCache.EntityFrameworkCore, and the invalidations in the projects the test project references: ```cs // Every tag of a cached method has a [CacheInvalidate] method, an EF Core mapping or an invalidation in a referenced project Assert.Empty(TagCoverage.Uninvalidated(provider)); ``` MethodCache writes the tags each project invalidates into its assembly, and `TagCoverage` reads them from the assemblies next to the tests, so reference the projects that invalidate, such as a worker, from the test project. A tag marked `InvalidatedElsewhere` is covered only when one of them invalidates it; otherwise it is reported with `MarkedInvalidatedElsewhere` set. A tag marked `InvalidatedManually`, which an operator clears by hand, is covered without a check. Name the tags invalidated where no referenced project shows it, such as by another application: `TagCoverage.Uninvalidated(provider, alsoInvalidatedBy: ["price:{provider}:{model}"])`. A placeholder matches any value, so `"product:{id}"` covers `"product:{Id}"` and `"product:42"`. Analyzer MC0028 checks the same within one project while you build; this check sees the whole application. See [Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md) for more. --- # Changelog Changes that a user of the packages notices. The release steps are in [docs/developer/RELEASE.md](https://github.com/eoniclabs/MethodCache/blob/main/docs/developer/RELEASE.md); when you tag a release, copy its section into the GitHub release. ## 1.0.0 (2026-11-21) The first stable release. From this release a change that breaks the public API needs a new major version. ### Upgrading from 1.0.0-rc.20 Nothing to change: the cache keys are the same as in 1.0.0-rc.20, and the public API only grows. Install without `--prerelease`. ### Added - `CachedServices.Warnings(provider)` in MethodCache.Testing returns the warnings the host logs at startup, such as a `RefreshAhead` not shorter than the `Duration` from another layer or a group with settings but no cached method, so a test can fail on them ([Settings that conflict](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#settings-that-conflict)). - MethodCache.AspNetCore: `MethodCacheAdminAction.OverrideMetadata` gives the audit function the `Owner`, `Reason`, `Ticket` and `ExpiresAt` of an override set over HTTP, and `MethodCacheAdminAction` has a public constructor, so a test can call an audit function ([Audit](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#audit)). ### Fixed - With a distributed cache, a value another instance had just stored could be loaded from the source again instead of read from the distributed cache, when that instance's notice of the new value arrived as the load started. The load now reads the distributed cache first, as it does otherwise. ### Documentation - Configuration has a recipe for switching all caching off during an incident and on again ([Switching all caching off and on again](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#switching-all-caching-off-and-on-again)). - The audit section says what the record holds, that it has no before and after, and how to read the overrides a change replaces. ## 1.0.0-rc.20 (2026-11-11) ### Upgrading from 1.0.0-rc.19 The cache keys are the same as in 1.0.0-rc.19. A few settings that were quietly ignored are now errors, so check these if startup or an override fails after upgrading: - `Notes` and `Metadata` in `appsettings.json` fail startup. MethodCache never read them; keep notes as a `//` comment next to the entry ([appsettings.json](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#appsettingsjson)). - A setting in `appsettings.json` written without a value, such as `"Enabled": ""`, or an empty tag fails startup instead of being read as unset. - `WithName` in `mc.Defaults(...)`, `mc.Group(...)` or `mc.Method(...).Configure(...)` fails startup, as it already did in `appsettings.json`. A name belongs to a manual call. - `ClearTags()` in `mc.Defaults(...)` fails startup, as it already did in `appsettings.json`. - `IRuntimeCacheConfigurator.UpsertAsync` throws `ArgumentException` for an override that sets nothing, uses `WithName`, has an `ExpiresAt` that has already passed, or has a `RefreshAhead` that is not shorter than the `Duration` it ends up with. Before, such an override was stored anyway and did nothing, or something else than it said. ### Added - `IRuntimeCacheConfigurator.UpsertGroupAsync`, `UpsertAllAsync` and `RemoveGroupAsync` change every method in a group, or every cached method, in one call. Each method gets the same override of its own; when the override doesn't fit one of them, none is changed, and an unknown group name throws with the closest group in use ([Runtime overrides](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#runtime-overrides)). - MethodCache.AspNetCore: `MapMethodCacheAdmin` adds `GET`, `PUT` and `DELETE` on `/overrides`, so an operator can change a method, a group or every method while the app runs. The body takes the same settings as `appsettings.json`, and each change is audited as `UpsertOverride` or `RemoveOverride` ([Runtime overrides over HTTP](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#runtime-overrides-over-http)). - `CachedMethodInfo.Group` names the group a method is in. - Startup warnings for a `RefreshAhead` that is not shorter than the `Duration` once all sources are combined, and for a group with settings but no cached method in it, usually a typo or a difference in case. - `SettingSources["Tags"]` names the highest source that adds tags, such as `RuntimeOverride`. ### Performance - Entries of a method with a `{param}` tag, and manual calls that reuse one `CacheEntryOptions`, share the method's settings instead of each keeping their own copy. With a million such entries, a garbage collection no longer has to walk a million extra objects. ### Documentation - Configuration starts with a table of what `[Cache]`, startup code, `appsettings.json` and runtime overrides can each set, and why some settings are missing from one of them ([What each surface can set](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-each-surface-can-set)). The README describes all four. ## 1.0.0-rc.19 (2026-11-10) ### Upgrading from 1.0.0-rc.18 Nothing to change: the code and the cache keys are the same as in 1.0.0-rc.18. ### Documentation - Testing: the arguments of the call passed to `CachedServices.Method` don't matter, so pass `""`, `0` or `default`; a test of a setting that startup code replaces on purpose, compared with `CacheSettingSource`; and the tenant check finds the methods that serve every tenant by a call instead of method id strings ([How each method is cached](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#how-each-method-is-cached)). - Memory cache: each `mc.Memory` call changes only the options it sets, so a host can add its own after the setup it shares with others ([Memory cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md)). ## 1.0.0-rc.18 (2026-11-10) ### Upgrading from 1.0.0-rc.17 - `CachedMethodInfo.IsDistributedNamespaceShared` is replaced by `Storage.Shared`, which is true only when other instances read the values this instance stores. The old property was true for a method with no distributed cache too. Read `method.Storage.Shared` instead. - A `SlidingExpiration` longer than `MaxExpiration` (7 days unless you set it) now fails where it is set, as a longer `Duration` already did: at startup from `[Cache]`, startup code or configuration, and with an `ArgumentOutOfRangeException` from a manual call. Before, such a window was cut to `MaxExpiration` without a word, so reads never extended the entry. Shorten the window, or raise `MaxExpiration` with `mc.Memory(o => o.MaxExpiration = ...)` ([How long an entry lives](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#how-long-an-entry-lives)). ### Added - `CachedMethodInfo.ReplacedSources` lists a setting that two of a method's own sources set, with the ones the higher source replaced, such as a `DurationFor` in startup code that replaces the `Duration` of the method's `[Cache]` ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)). - The first value of each method, or of each `WithName` name for manual caching, that asks to be shared for longer than the distributed cache keeps values (`TagRetention`, one day, less `ClockSkewTolerance`) logs a warning that says how long it is shared and how to share it longer. It was cut short without a word ([How long an entry lives](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#how-long-an-entry-lives)). - MethodCache.Testing: `CachedServices.Method(provider, s => s.Call(...))` returns how one method is cached, found by a call instead of a method id string ([How each method is cached](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#how-each-method-is-cached)). ### Documentation - The doc comments of `GetMethods()` say what each part is: `Options` what the method's sources set, `Lifetime` and `Storage` what applies with defaults filled in; a setting missing from `SettingSources` has the library's default, and `MaxExpiration` is a limit for the whole cache. - Expiration: a `DurationFor` in startup code replaces the `Duration` of the method's `[Cache]`, so a cap belongs in the function ([A duration from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-duration-from-the-result)). - Testing: a test of one method's policy, every method's policy as JSON to compare in review, and a check that every tenant method has the tenant in its key ([Testing](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#how-each-method-is-cached)). - Memory cache: large, rarely read values stay out of memory with `WeightLimit` and a `Weigher`, and are read back from the distributed cache ([Bounding by size](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#bounding-by-size)). ## 1.0.0-rc.17 (2026-11-10) ### Upgrading from 1.0.0-rc.16 - A value with a sliding window is now kept in the distributed cache for one window from when it was stored, or its `Duration` if that is shorter, instead of its whole `Duration` (five minutes when it set none). Reads in one instance's memory don't reach the distributed cache, so other instances used to serve a value nobody had read for longer than its window. A short window now means more loads on other instances; to share a value for its whole `Duration`, leave the window out ([Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration)). - `WithDistributed(false)`, and a call that keeps its value in memory because of `StoreValuesByDefault = false`, now touches only this instance's memory: `SetAsync` no longer removes the key from the distributed cache, writes no removal stamp and sends nothing on the backplane, so the other instances keep what they hold. To change a value every instance sees, use `WithDistributed(true)` or invalidate the key. This replaces the rc.16 note about removal stamps ([Memory by default, shared where you say so](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#memory-by-default-shared-where-you-say-so)). - An instance that read a value from the distributed cache now keeps it as a fail-safe fallback, like the instance that loaded it. With `FailSafe` on, every instance that has the value serves it when a reload fails, where only the instance that loaded it did before ([Fail-safe](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/fail-safe.md)). ### Added - `ICacheAdministrator.GetMethods()`, and `/methodcache/methods` with MethodCache.AspNetCore, show what each method does on this instance: `Lifetime` (how long its entries live with defaults filled in, and how long the copy in the distributed cache lives), `Storage` (whether its values reach the distributed cache, and why not when they don't), `KeyParameters` (the arguments its keys are made of) and `NotShared` (result types kept in memory because they don't read back unchanged from the serializer, with how many and since when) ([What applies on this instance](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#what-applies-on-this-instance)). - `WithName("crm-token")` on a manual call names it in metrics, traces and logs as `methodcache.name`, where a manual call reported only that it was one ([Monitoring](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#opentelemetry)). ### Fixed - A slow first contact with the distributed cache, such as a cold Redis connection or SQL Server or PostgreSQL creating its tables, no longer opens the circuit breaker. With a generic host the connection opens in the background once the host has started; until the distributed cache first answers, a call waits for it up to `OperationTimeout` and then uses memory, and once one call has waited that long the rest don't wait. A contact that fails, or hasn't answered after 30 seconds, still opens the breaker ([When the distributed cache is down](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#when-the-distributed-cache-is-down)). ### Documentation - Expiration: how long an entry lives in memory and in the distributed cache, with every default filled in, and a recipe for a cache that only slides, such as an `IMemoryCache` entry with only `SlidingExpiration` ([How long an entry lives](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#how-long-an-entry-lives), [Kept as long as it is read](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#kept-as-long-as-it-is-read)). - Cache keys: an argument that holds a secret, such as a URL with a SAS token, wrapped in a type whose `ICacheKeyProvider` returns a hash ([Secrets in arguments](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/keys.md#secrets-in-arguments)). - Migrating from IMemoryCache: locks, idempotency records and "already sent" markers aren't a cache and stay where a missing value is an error ([State that isn't a cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/migration-from-imemorycache.md#state-that-isnt-a-cache)). - Refresh-ahead and sliding windows with a distributed cache: what the other instances read. - MC0043's description in the IDE says that a method of yours the result is passed to isn't seen. ## 1.0.0-rc.16 (2026-11-08) No code changes from rc.15; upgrade by changing the version number. ### Documentation - MC0043: changes made in a method of your own that the result is passed to, such as a helper that adds to a cached list, aren't reported; the check in Development finds them at run time for values shared through the distributed cache. - Distributed cache: a `SetAsync` that keeps its value in memory writes a removal stamp, `methodcache:r:` with the default `KeyPrefix`, that holds no value and expires after `TagRetention` ([Memory by default, shared where you say so](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#memory-by-default-shared-where-you-say-so)). ## 1.0.0-rc.15 (2026-11-08) ### Upgrading from 1.0.0-rc.14 - `DistributedCacheOptions.StoreValues` is now `StoreValuesByDefault`: replace `o.StoreValues = false` with `o.StoreValuesByDefault = false`. A method with `[Cache(Distributed = true)]`, or `Distributed = true` from its group, `Defaults` or `appsettings.json`, and a call with `WithDistributed(true)` now store their values in the distributed cache with it, where rc.14 kept every value in memory. One that sets nothing still stays in memory. - MC0043 now also reports code that changes the result of `GetOrCreateAsync`, `GetOrCreateManyAsync` or `TryGetAsync` on `ICacheManager`, writes through a `Span` over a cached array, or copies into one with `Array.Copy`, `Buffer.BlockCopy` or `CopyTo`. It may fail a build that treats warnings as errors. ### Added - `StoreValuesByDefault = false` keeps values in memory by default, and a method or call that sets `Distributed` to `true` still shares its value through the distributed cache: values that are expensive or rate-limited to load, such as an access token, are shared and the rest stay in each instance's memory ([Memory by default, shared where you say so](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#memory-by-default-shared-where-you-say-so)). - `DistributedCacheOptions.VerifyUnchangedInDevelopment = false` turns off the check in Development that writes the values kept in memory again every two seconds, for applications whose values are so large that it slows down development. - MC0043 covers the results of manual calls on `ICacheManager`, writes through a `Span` or `Memory` over a cached array (`vector.AsSpan()`, `Span span = vector`, `CollectionsMarshal.AsSpan(list)`), and `Array.Copy`, `Buffer.BlockCopy` and `CopyTo` with a cached array as the destination. ### Documentation - Testing: `CachedServices.Declared` with the cached interfaces in several projects, and with a shared library that declares interfaces other applications register. ## 1.0.0-rc.14 (2026-11-08) ### Upgrading from 1.0.0-rc.13 - Every cached method's entries in the distributed cache are now kept apart by the shape of its result (see Added), so each method loads once more after the upgrade. During a rolling upgrade, instances on rc.13 and rc.14 don't read each other's entries; invalidations by key and by tag reach both. - A result that holds `object` values, such as those of a `Dictionary`, or a derived type MethodCache can't name to the serializer (MC0039), now stays in memory with a warning instead of reaching the other instances without its data. Other derived types, such as a `Dog` in a `List`, are now shared as themselves. Under Native AOT, add them to the `JsonSerializerContext` you pass to `UseJson`; MC0040 and its code fix point them out. - New build warnings MC0039 to MC0043 may appear (see Added). `MethodCache` now depends on `Microsoft.Extensions.Hosting.Abstractions`, for the check in Development. - If you followed "Invalidations only" with `Defaults(o => o.WithDistributed(false))`, switch to `Distributed(o => o.StoreValues = false)`. `Defaults` applies to cached methods only, so `GetOrCreateAsync` and `SetAsync` still stored their values in the distributed cache. ### Added - `DistributedCacheOptions.StoreValues = false` keeps every value in memory, for cached methods and manual calls alike, whatever their options say, and uses Redis, SQL Server or PostgreSQL for invalidations only ([Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only)). - `CachedServices.Declared(assemblies)` in `MethodCache.Testing` lists the interfaces with cached methods in the assemblies you pass, ordered as `Registered` orders them. Compare the two, and a test covers a new cached interface without a change ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)). - Derived types come back from the distributed cache as themselves. The generator finds the classes that derive from a type a cached result declares (a `Dog` in a `List`, in an `Animal` property, or returned as an `Animal`), in the project, in the declared type's assembly and the ones built on it, and in projects that reference the one with the cached interface, and names them to MethodCache's JSON and MessagePack serializers. The application's own JSON doesn't change, and `[JsonDerivedType]`, `[JsonPolymorphic]` and `[Union]` keep their settings. The startup log lists the derived types the distributed cache restores ([Derived types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#derived-types)). - MC0039 names a derived type the generated code can't name (private, file-local, generic, or not public in another assembly), so it isn't restored. Not reported in test projects. - MC0040 names a derived type the `JsonSerializerContext` passed to `UseJson` has no contract for while it has one for the base type, and its code fix adds `[JsonSerializable(typeof(Dog))]` to the context. At startup, MethodCache also logs a warning naming such types. - MC0041 reports a cached result holding EF Core entities with virtual navigation properties in a project that uses lazy-loading proxies, which come back without their navigations. - MC0042 reports a cached result type, or a type in it, whose state is all non-public, so serializers write it as `{}`. - MC0043 reports code that changes a result a cached method returned, such as `orders.Add(draft)` or `order.Status = ...`: the memory cache hands that instance to later callers, while other instances read the stored copy. In Development, MethodCache also writes the values it keeps in memory again every two seconds and logs a warning naming the method whose value has changed. It never runs when a call is answered from memory ([Results that don't change](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#results-that-dont-change)). - A cached method's entries are kept apart by a fingerprint of its result's shape, which the generator computes from the members a serializer writes, their types and serializer attributes, enum members and registered derived types. A renamed property or renumbered enum member no longer reads entries the previous build wrote, with no `Version` bump, while invalidations still reach both builds ([Changing result types](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#changing-result-types-and-upgrading)). ### Fixed - The check before a value is shared through the distributed cache compares the types inside it too, through its collections, properties and fields. A `Dog` in a `List` came back as a plain `Animal` on the other instances, and an `int` in a `Dictionary` as a `JsonElement`; such a value now stays in memory with the warning ([Serialization](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md#serialization)). - The check before sharing also compares the comparer of a dictionary or set. A `Dictionary` made with `StringComparer.OrdinalIgnoreCase` came back with the default comparer on the other instances, so `dict["KEY"]` found a value on one instance and not on the others; such a value now stays in memory with the warning. - MC0020 no longer reports an interface or abstract class with `[JsonDerivedType]`, `[JsonPolymorphic]` or `[Union]`, or one the project or a project it references has implementations of, whose results the serializer restores. - Setting `MethodCacheAnalysisLevel` failed every build with MSB4184 since 1.0.0-rc.11. It builds again. ### Documentation - Distributed cache: new sections on derived types and on results that don't change, with what to return and how to change a copy. - Testing: a minimal API endpoint that takes a cached interface fails the host before `Registered` runs when the interface isn't registered. - The agent instructions no longer ask a coding agent to draft feedback by itself: it mentions a problem in its report and offers to draft feedback, and drafts and files it only when its user asks. They say we appreciate it. ## 1.0.0-rc.13 (2026-11-07) ### Added - `CachedServices.Registered(provider)` in `MethodCache.Testing` lists the registered services with cached methods, so a test can compare it with the services the application should have and catch one that is never registered, which `ProblemsAsync` and `RegistrationProblems` can't see ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)). ### Documentation - Expiration and manual caching: `Defaults` and groups apply to cached methods, not to manual calls. A manual call without a `Duration` lives five minutes, and one with only a sliding window is limited by `MaxExpiration`. - Getting started: use one version of every MethodCache package (NuGet warns with NU1608 when they differ), and pin `MethodCacheAnalysisLevel` only when warnings are errors. Every rule up to 1.0.0 counts as a rule of 1.0. - Memory cache: `MethodCacheWeigher.Bytes(otherValue)` weighs the key on top of `otherValue`. - Testing: `RegistrationProblems` runs the application's registration code, so infrastructure registered eagerly is still needed, and a recipe for testing that a cached method refuses another tenant's id ([A load for another tenant fails](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#a-load-for-another-tenant-fails)). ## 1.0.0-rc.12 (2026-11-07) ### Upgrading from 1.0.0-rc.11 - `CachedServices.ProblemsAsync` and `TagCoverage.Uninvalidated` throw `InvalidOperationException` when the provider has no service with cached methods, instead of returning an empty list. Pass the application's provider. - New warning MC0038 fails a build that treats warnings as errors when `SlidingExpiration` on `[Cache]` or `[assembly: CacheInterface]` is not shorter than the `Duration` next to it. Such a window never extended anything; shorten it or remove it. ### Added - `CachedServices.RegistrationProblems(provider)` in `MethodCache.Testing` checks that every service with cached methods is registered before `AddMethodCache`, without resolving any of them, for services that need a database or a key vault to resolve. The testing guide says what `ProblemsAsync` adds beyond the check a host makes when it starts ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)). - `MethodCacheWeigher.Bytes(otherValue: 1024)` weighs values it can't measure, such as records of your own, as the weight you give instead of 64 ([Bounding by size](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/memory-cache.md#bounding-by-size)). - `[Cache(InvalidatedManually = [...])]` marks tags that only an operator clears by hand, such as through `MapMethodCacheAdmin`, and that otherwise expire. MC0028 and `TagCoverage` count them as invalidated, so they need neither a `SuppressMessage` nor `alsoInvalidatedBy` ([Cleared by hand](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#cleared-by-hand)). - Warning MC0038 for a `SlidingExpiration` that is not shorter than the `Duration` on the same attribute, and a warning in the log when the host starts for each method whose sliding window and duration, from any place such as a method's `WithSlidingExpiration` and `Defaults`, combine that way ([Sliding expiration](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#sliding-expiration)). ### Documentation - Getting started: a recommended project setup (`MethodCacheAnalysisLevel` in `Directory.Build.props`, the `MethodCache.Testing` checks, and evictions and hit ratio to watch). - Monitoring: the prometheus-net example filters to MethodCache's meter, the hit-ratio query for prometheus-net's series names, `label_replace` and relabeling for a short method name, and why an adapter started from a hosted service exports nothing in some test hosts. - Expiration: what `DurationFor` gets for a null result, and how to keep "nothing yet" until a known time. - MC0026: suppress it on the class for cached reads of a table that the request doesn't filter. - Distributed cache: the worker and API recipe links to the PostgreSQL tables and grants, and says the API's test project references the worker for `TagCoverage`. ## 1.0.0-rc.11 (2026-11-07) ### Upgrading from 1.0.0-rc.10 - `TagCoverage.Uninvalidated` counts a tag marked `InvalidatedElsewhere` only when a project the test project references invalidates it. Reference the project that invalidates it, such as the worker, from the test project, or name a tag that is invalidated outside the solution in `alsoInvalidatedBy`. `UninvalidatedTag` has a third parameter, `MarkedInvalidatedElsewhere`. - MC0026 also follows an interface to its implementations in referenced projects, once those projects are built with this version, so it can report a cached implementation it didn't report before. - New warning MC0036 fails a build that treats warnings as errors when a name in `methodcache.request_state_types` matches no type. - With a distributed cache and its backplane, runtime overrides apply on every instance and outlive restarts. Such an override can't set `CacheWhen`, `DurationFor`, `TagsFor` or `SlidingFor` (`ArgumentException`); set them in `AddMethodCache`. `UpsertAsync`, `RemoveAsync` and `ClearAsync` throw an `InvalidOperationException` when the distributed cache doesn't store the change, and `GetOverrides()` lists the overrides of every instance. During a rolling upgrade, instances on rc.10 ignore stored overrides. ### Added - `[ChecksRequestState]` marks a method of your own that checks a parameter against the current request, such as `EnsureActsFor(tenantId)`. MC0026 doesn't report a class whose cached methods each pass one of their parameters to it ([A tenant parameter checked against the request](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#a-tenant-parameter-checked-against-the-request)). - MC0026 follows an interface to the classes that implement it in referenced projects. The generator writes the classes of each project that take per-request state into its assembly (`MethodCacheRequestState.g.cs`). - The generator writes the tags each project invalidates into its assembly (`MethodCacheInvalidatedTags.g.cs`), and `TagCoverage` reads them from the projects next to the tests. - Warning MC0036: a name in `methodcache.request_state_types` that matches no type, such as one left behind by a rename. - Information MC0037: a `[Cache]` method whose key is written when the call runs, such as one with an `object` argument. It shows in the editor and never stops a build. - The MSBuild property `MethodCacheAnalysisLevel` turns off the analyzer rules that come in versions after the one it names, so a new version can't break a build that treats warnings as errors ([Rules of a later version](https://github.com/eoniclabs/MethodCache/blob/main/docs/user-guide/DIAGNOSTICS.md#rules-of-a-later-version)). - The `MethodCache` package carries this `CHANGELOG.md` in its `docs` folder, next to the docs of that version. - New docs: giving a class an interface ([Getting started](https://github.com/eoniclabs/MethodCache/blob/main/docs/getting-started.md#a-class-without-an-interface)), replacing a cached service with a fake in a test, generic EF Core helpers with `[InvalidatesCache]`, a worker and an API with PostgreSQL in "invalidations only" mode, prometheus-net with a registry of your own, `DurationFor` for future-dated rows, what changed keys mean during a rolling deploy, and where MC0027 and MC0030 read what they know about referenced projects. - `SlidingFor` sets the sliding window from the result, like `DurationFor` sets the duration: a long window for a finished value and none for one still being processed ([A sliding window from the result](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/expiration.md#a-sliding-window-from-the-result)). Your own `ICacheManager` reads it with `CacheEntryOptions.SlidingExpirationOf(value)`. MC0033 checks its type like `DurationFor`'s. - The counter `methodcache.evictions` counts the entries each instance removed to make room since it started, per `methodcache.kind`. The monitoring guide shows the hit ratio per method in PromQL ([Hit ratio per method](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/monitoring.md#hit-ratio-per-method)). - `MethodCacheWeigher.Bytes`, a ready-made weigher that counts approximate bytes of strings and arrays of numbers: `o.Weigher = MethodCacheWeigher.Bytes`. - `CachedServices.ProblemsAsync(provider)` in `MethodCache.Testing` checks that every service with cached methods resolves to its caching decorator, so a registration mistake fails a test ([Every cached service resolves](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/testing.md#every-cached-service-resolves)). - `MapMethodCacheAdmin(..., audit: ...)` records who changes the cache through the admin endpoints: the user, the action, its targets and the time ([Audit](https://github.com/eoniclabs/MethodCache/blob/main/src/MethodCache.AspNetCore/README.md#audit)). - Runtime overrides apply on every instance with Redis, SQL Server or PostgreSQL and their backplane: they are stored in the distributed cache, the other instances apply them within moments, and an instance that starts applies the active ones, so they survive restarts and slot swaps ([Runtime overrides](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/configuration.md#runtime-overrides)). ### Changed - The agent instructions ask a coding agent to show its feedback draft to its user and to file it only when the user agrees. - The error for a cached service registered after `AddMethodCache` says how a test that replaces a service with a fake avoids it: call `AddMethodCache` again after the fake. - MC0031 suggests a private method that does the work when the call doesn't need the cache, such as a recursive call. - The MC0026 message points to `[ChecksRequestState]` for a tenant or user that the method takes as a parameter. - A policy in code or appsettings for a cached service that the application doesn't register is logged at `Information` instead of `Debug`, so a misspelt or moved service shows in the startup log. ### Fixed - **`MethodCache.EntityFrameworkCore`**: a many-to-many link added or removed with only the two ids, without loading either side, invalidates every mapped tag of both sides. The side the context hasn't loaded is read once before the save when its tags use more than its key. Before, only tags that use the key alone, such as `product:{Id}`, were invalidated, and a cached list by category kept the old links. - **`MethodCache.EntityFrameworkCore`**: a row changed without loading it invalidates the new value of a column the database computes, such as `HasComputedColumnSql`. Before, only the old value was invalidated. - **`MethodCache.EntityFrameworkCore`**: the warning for an invalidation that can't be confirmed after a commit gives the number of tags and the error's type. Before, it logged the tags, which can hold user or tenant ids, and the exception with its message. - **`MethodCache.EntityFrameworkCore`**: `UseEntityFrameworkCore` works in a container without logging, such as a `ServiceCollection` built without a generic host. Before, it threw because no `ILogger` was registered. ## 1.0.0-rc.10 (2026-11-06) ### Upgrading from 1.0.0-rc.9 - Two new build errors find what failed when the call ran: MC0033 for `CacheWhen`, `DurationFor` or `TagsFor` of a type the result can never be, and MC0034 for a key argument whose state is all private. - `AddMethodCache` throws when a registered interface has `[Cache]` methods but the source generator didn't run in its project, where its calls ran uncached before. - New warnings MC0030, MC0031, MC0032 and MC0035 fail a build that treats warnings as errors until they are fixed or suppressed. - Entries with a set or dictionary argument get a new key, so they are missed once after the upgrade. ### Added - A way for coding agents to report problems: the agent instructions (`docs/ai/methodcache.md`, Feedback) say when and how to file an `[Agent feedback]` issue, without the project's code, names or secrets, and the repository has an issue form with the same fields. - `ICacheManager.SetAsync(key, value, options)` stores a value you already have, such as one you just saved, in memory and the distributed cache. Other instances drop their copy, and a load already running for the key doesn't overwrite it. A value the options turn down removes the key's old value instead. - `TagsFor` adds tags read from each result to its entry, next to the method's own tags, such as the customer of an order found by its id: `mc.Method(...).TagsFor(order => [MethodCacheKeys.Tag($"customer:{order.CustomerId}")])`, and `TagsFor` on `CacheEntryOptions.Builder` for manual caching. Custom managers read them with `CacheEntryOptions.TagsOf(value)`. - The cache logs one `Information` line when it starts, naming the memory cache's `MaxItems`, and the distributed cache's store, `KeyPrefix` and backplane, or that there is no distributed cache, so configuration that differs between instances shows in the log. - Build error MC0034 reports a key argument of a `[Cache]` method, or a value inside one, whose type has only private state, which MethodCache refuses when the call runs since every value would get the same key. - Analyzer MC0035 warns when the factory of `GetOrCreateAsync` or `GetOrCreateManyAsync` uses a cancellation token from outside it, such as `HttpContext.RequestAborted`, that the call doesn't pass as its `cancellationToken`: its cancellation fails the load for every caller sharing it. The code fix makes the factory use its own token and passes the outer one as `cancellationToken`. - `MethodCacheKeys.Part` and `MethodCacheKeys.Tag($"...")` take nullable values (`int?`, `Guid?`, a nullable enum and the other value types they take), writing the value or null the way tag templates do. - `AddMethodCache` fails with an `InvalidOperationException` when a registered interface has `[Cache]` methods but MethodCache's source generator didn't run in its project, so its calls would run uncached. The message names the project and what to check. - Analyzer MC0030 reports a program with cached services, its own or a referenced project's, when its code calls neither `AddMethodCache` nor a method of a referenced project that calls it, such as a shared `services.AddData()`. For this, MethodCache marks a project's assembly with `AssemblyMetadata` attributes when it has cached services, and for each of its methods that calls `AddMethodCache`, also through other setup methods. - Analyzer MC0031 reports a call a class makes to its own cached method, which skips the cache. - `DurationFor` gives each result its own duration in place of `Duration`, such as the time left on a token or a shorter time for an empty result: `mc.Method(...).DurationFor(token => token.ExpiresAt - DateTimeOffset.UtcNow)`, and `DurationFor` on `CacheEntryOptions.Builder` for manual caching. Zero or less doesn't cache the result. Custom managers read it with `CacheEntryOptions.DurationOf(value)`. - `MethodCacheKeys.Tag($"price:{provider}:{model}")` builds a tag from an interpolated string, writing each value the way `[Cache]` tag templates do. A value of a type tags can't hold, or with a format, doesn't compile. MC0024's code fix offers it, and MC0028 counts tags built with it. - MC0026 reads the application's own request-state types, such as an `ICurrentUser` service, from the `.editorconfig` option `methodcache.request_state_types`. - `GetOrCreateManyAsync(ids, id => $"user:{id}", (missingIds, ct) => ..., options)` takes ids and how each makes its key; the factory gets the missing ids and returns a dictionary by id, and so does the call. - Analyzer MC0032 reports a class that implements a cached interface created with `new` outside a service registration, since its calls skip the cache. The docs show keyed registrations for several instances of one class. - Analyzer MC0033 is a build error for `CacheWhen`, `DurationFor` or `TagsFor` in `Method(...).Configure(...)`, `GetOrCreateAsync`, `GetOrCreateManyAsync` or `SetAsync` for a `T` the call's result can never be. - The memory cache logs one warning the first time it is full and removes an entry to make room, naming the limit (`MaxItems`, or `WeightLimit` with a weigher) to raise when entries are removed before they expire. ### Changed - A setting for a `[Cache]` method whose service the application doesn't register, in `mc.Method(...)` or in `appsettings.json`, is skipped instead of failing startup, so startup code and configuration shared by several applications works in each of them. A method id that matches no `[Cache]` method still fails. - MC0028 counts a `[CacheInvalidate]` declared on an interface in a referenced project, such as a shared contracts project, so a tag that the referenced interface invalidates is no longer reported. - MC0026 follows constructors two levels down instead of one, and follows an interface to the classes in the project that implement it, so a cached service that takes `IUserRepository`, whose implementation takes a `DbContext` that takes `IHttpContextAccessor`, is reported. - Sets and dictionaries in arguments are written sorted in keys, so two equal sets or dictionaries get one key whatever order they enumerate in, also on two servers. Existing entries with a set or dictionary argument are missed once. - The error for a `CacheWhen` or `DurationFor` of another result type names the types as C# writes them, `CacheWhen can't check the int result`, instead of ``Nullable`1`` and `Int32`. `NoOpCacheManager` makes the same check, so a test with it finds the mistake too. - `GetOrCreateManyAsync` accepts a factory answer that leaves out keys, such as ids that don't exist, instead of failing the whole call. A key left out is not cached and not returned, unless it has a fail-safe value, which it then gets as when the factory throws. A `null` answer still fails. ## 1.0.0-rc.9 (2026-11-05) ### Changed - MC0027 in a project that references the one with the `ef.Entity(...)` mapping, such as its tests or a worker, checks writes against that mapping, so a write to a table that nothing caches is no longer reported there. For this, MethodCache writes a project's mapping into its assembly as `AssemblyMetadata` attributes. - MC0027 reads constants and numbers interpolated into `ExecuteSqlRaw`, so `$"SELECT pg_advisory_xact_lock({LockId})"` and `$"SET LOCAL lock_timeout = '{waitMs}ms'"` are no longer reported. An interpolated string still is, since it could hold any SQL. ## 1.0.0-rc.8 (2026-11-05) ### Added - `[Cache(InvalidatedElsewhere = ["catalog"])]` marks the tags that another application or process invalidates, such as an import worker. Analyzer MC0028 and `TagCoverage` count them as invalidated, on every method that has the tag, so neither a `#pragma` nor a list in the test is needed. Caching itself doesn't change. Analyzer MC0029 reports a tag in `InvalidatedElsewhere` that matches none of the method's `Tags`. ### Changed - `TagCoverage.Uninvalidated` counts the entity mapping of `mc.UseEntityFrameworkCore` by itself, so `alsoInvalidatedBy: mapping.AllTags` is no longer needed. `alsoInvalidatedBy` remains for tags the code invalidates with `InvalidateTagAsync`. ## 1.0.0-rc.7 (2026-11-05) ### Breaking changes since 1.0.0-rc.6 - A duration is a number and a unit: `"30s"`, `"10m"`, `"1.5h"`, `"7d"`. A `TimeSpan` such as `"00:10:00"` is no longer accepted: in an attribute it is error MC0004, whose message and code fix give the value with a unit (`"10m"`), and in `appsettings.json` startup fails with the value to write instead. One way to write a duration keeps an application consistent. `TimeSpan` arguments in code are unchanged. ### Changed - MC0027 reports raw SQL only when it names the table of a mapped entity type (by class, `DbSet`, `ToTable` or `[Table]` name, in any case, so `ai_model_prices` matches `AiModelPrice`), runs a procedure or block (`call`, `exec`, `do`), or can't be read. Statements that only `select` or `set` a session setting, such as `SET LOCAL lock_timeout`, are never reported. A project that maps no type still reports all other raw SQL. - MC0026 also reports a cached implementation that takes a class whose constructor takes per-request state, such as a `DbContext` that takes `IHttpContextAccessor`, directly or through `IDbContextFactory`. ### Added - Analyzer MC0028 reports a tag on a `[Cache]` method that nothing in the project invalidates: no `[CacheInvalidate]`, entity mapping, `InvalidateTagAsync`, `InvalidateAfterCommit` or `[InvalidatesCache]` call names it. A placeholder matches any value. A project that invalidates nothing, such as a library of cached interfaces, isn't reported; a tag another project invalidates is suppressed with a `#pragma`. - The `MethodCache.Testing` package, for tests of the caching itself. `services.AddMethodCacheTesting()` registers a `FakeTimeProvider` as the container's clock and a `CacheRecorder`: `Loads(call)` counts how many times a call ran your implementation, and `InvalidatedTags` and `InvalidatedKeys` list what was invalidated. `TagCoverage.Uninvalidated(provider, alsoInvalidatedBy)` lists the tags of cached methods, also from configuration, that no `[CacheInvalidate]` method or listed tag covers, across the whole application. - `EntityTagMapping` in `MethodCache.EntityFrameworkCore` lists the mapped entity types with their tags, and `AllTags` every tag of the mapping, such as for `TagCoverage`. ### Documentation - Entity Framework Core: a row-level security section, with a context of their own for cached reads, and what happens when a save of a row the context didn't load can't read it (PostgreSQL and SQL Server don't change the row either, and the save throws `DbUpdateConcurrencyException`). EF Core query filters don't hide the row from that read. - The PostgreSQL, Redis and SQL Server package READMEs show how to share only invalidations, such as for a worker that changes data an API caches. The agent guide lists every feature guide and says when to read it. - Testing: how to prove a read is cached when every save invalidates. - Monitoring: prometheus-net 8 exports MethodCache's instruments with no setup, and how its names and types differ from OpenTelemetry's Prometheus exporter. - Examples use durations with a unit throughout. ## 1.0.0-rc.6 (2026-11-04) ### Changed - Analyzer MC0027 reports `ExecuteUpdate` and `ExecuteDelete` only on the entity types the project maps with `ef.Entity(...)`, and on their base and derived types, so writes to tables that nothing caches are no longer reported. A project that maps no type, such as a data layer apart from the startup project, is still reported on every type. Raw SQL that is one statement starting with `select`, such as an advisory lock, is no longer reported. ### Added - `ef.Entity(user => user.WhenDeleted("posts"))` maps tags that are invalidated only when a row is deleted, with the deleted row's values in the braces. Use it for rows the database deletes with the entity, through `ON DELETE CASCADE` or a trigger, when the entity is saved too often to invalidate them on every change. `user.Tags(...)` in the same call maps tags for any change. A type mapped only with `WhenDeleted` is reported by MC0027 for `ExecuteDelete` alone. - `[InvalidatesCache]` marks a method of your own that invalidates, such as a helper around `ICacheManager.InvalidateTagsAsync`. MC0027 counts a call to it as the invalidation and doesn't report the writes inside it. ## 1.0.0-rc.5 (2026-11-04) ### Breaking changes since 1.0.0-rc.4 - `ICacheManager.TryGetAsync` and `ICacheManager.InvalidateKeysAsync` take every argument: `(key, version, cancellationToken)`. Extension methods give the short forms, so a cancellation token no longer needs a named argument: `TryGetAsync(key, cancellationToken)`, `InvalidateKeyAsync(key, cancellationToken)` and `InvalidateKeysAsync(keys, cancellationToken)`, and with a version `TryGetAsync(key, 2, cancellationToken)`, `InvalidateKeyAsync(key, 2, cancellationToken)`. Calls that passed `version: null` drop it; your own `ICacheManager` keeps working. ### Added - `IMethodCacheKeys.Tag(call, template)` returns the tag a call to a cached method stores its result under, filled in exactly as the decorator fills it in. Use it to invalidate when the data changes outside the cached interface, such as in an endpoint that writes to the database directly: `cache.InvalidateTagAsync(keys.Tag(s => s.GetRateAsync(provider, model), "price:{provider}:{model}"))`. The template must be one of the method's tags. - Analyzer MC0024 warns when a tag built with string interpolation for `InvalidateTagAsync` or `InvalidateTagsAsync` writes a value differently from MethodCache's tags, such as a string with `:` (`gemma3:4b`), a `Guid`, an enum or a `bool`. Such an invalidation matched nothing, without an error. The code fix wraps the value in `MethodCacheKeys.Part`. - The XML documentation says when `[CacheInvalidate]` runs, how tag arguments are written, what `Weigher` receives, how to skip caching null for one method, and how to clear the cache after a test writes to the database directly. - Analyzer MC0025 warns when a cached method returns a type that isn't safe to share between callers: `JsonNode` (`JsonObject`, `JsonArray`), `DataTable`, `DataSet`, `DataRow`, `DataView`, a `Stream` or a `StringBuilder`, also as an element. Every caller gets the same instance at once, and a cached `JsonObject` read by two requests at the same time could come back empty. A `Stream` result reported MC0020 before. - Analyzer MC0026 warns when the implementation of a cached interface takes `IHttpContextAccessor`, `HttpContext`, `HttpRequest` or a `ClaimsPrincipal` in its constructor: the key holds only the method's arguments, so a result that depends on the current user could reach another user. - **`MethodCache.EntityFrameworkCore`**, a new package: `AddMethodCache(mc => mc.UseEntityFrameworkCore(ef => ef.Entity("product:{Id}", "products")))` invalidates those tags after every commit that adds, changes or deletes a `Product`, with the old and the new values of a changed row, and drops them on a rollback. A row saved without loading it (`Update`, `Attach`, `Remove(new Product { Id = id })`) is read once for its stored values. `OwnsOne` and `OwnsMany` types invalidate their owner, many-to-many links both sides, and cascade deletes and other interceptors' changes count. `db.InvalidateAfterCommit(tags)` queues other tags for the same moment. Works with `AddDbContext`, `AddDbContextPool`, `AddDbContextFactory`, `TransactionScope` and `UseTransaction`, and with document databases on `SaveChanges`. - Analyzer MC0027 warns, in a project that uses `MethodCache.EntityFrameworkCore`, about `ExecuteUpdate`, `ExecuteDelete` and `ExecuteSql…` writes, which go past EF Core's change tracker, when the method around them doesn't invalidate. MC0024 also checks the tags passed to `InvalidateAfterCommit`. ### Documentation - How to keep values in each process's memory and share only invalidations ([Invalidations only](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#invalidations-only)), how to invalidate after a database transaction, per-user data and row-level security in Getting started, and a table of duration units. - The `MethodCache` package carries the user documentation in its `docs` folder, with `llms-full.txt`, so a coding agent can read the docs for the installed version. The README has a prompt to give your agent. - New [How do I…?](https://github.com/eoniclabs/MethodCache/blob/main/docs/how-to.md) page with short answers to common questions, and reference pages with the exact rules for [registration](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/registration.md), the [distributed cache](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/distributed.md) and [HTTP caching](https://github.com/eoniclabs/MethodCache/blob/main/docs/reference/http-caching.md). - The README, the NuGet READMEs and the guides were rewritten to say what you do and see, without implementation detail. New sections: why an interface is needed, invalidating when the write happens elsewhere, and testing with writes straight to the database. - `llms.txt` now lists PostgreSQL and the new pages. ## 1.0.0-rc.4 (2026-11-04) ### Breaking changes since 1.0.0-rc.3 A third API review before 1.0.0 found settings that were accepted and then silently did something else. They now fail where they are set. No API is removed. - `FromAssemblyOf()` and `FromAssembly(...)` choose the module that wins when several assemblies generate the same interface; the services the other modules generate stay cached. Before, they turned caching off for every interface outside the selected assemblies, without a warning. With `AutoRegister`, only the selected modules register missing services, as before. - A `Duration` longer than `MethodCacheMemoryOptions.MaxExpiration` (7 days by default) fails where it is set: at startup from `[Cache]`, code or `appsettings.json` (a reload with one is rejected and the previous policies stay), with an `ArgumentException` from a runtime override, and with an `ArgumentOutOfRangeException` from a manual `GetOrCreateAsync` or `GetOrCreateManyAsync` before the factory runs. Before, the entry was removed after `MaxExpiration` instead. Shorten the `Duration`, or raise the limit with `mc.Memory(o => o.MaxExpiration = ...)`. With your own `ICacheManager` nothing changes. - A `CacheWhen` for a type the method can't return, such as `CacheWhen` on a method that returns `int`, fails where it is set: at startup from code, and with an `ArgumentException` from `IRuntimeCacheConfigurator.UpsertAsync`, which leaves the policy as it was. Before, the override was accepted and every call of the method threw. A generic method's result type depends on the call, so there the call still throws. - `IMethodCacheKeys.For` throws an `InvalidOperationException` when the interface has several registrations and the last one is a scoped or transient factory, which may create another type in each scope. Before, it returned the key of the type the factory created in a scope of its own, which could miss the caller's entry. Register the service with its implementation type, give it a service key of its own, or invalidate by tag. ### Added - **`MethodCache.PostgreSql`**: `PostgreSqlOptions.ConfigureDataSource` configures MethodCache's `NpgsqlDataSourceBuilder`s, for passwordless login with a token from Microsoft Entra ID or AWS IAM, client certificates or a custom server certificate check. It applies to the connection pool and to the connection that listens for invalidations. ### Fixed - **`MethodCache`**: `GetOrCreateManyAsync` checks the factory's answer before it caches any of it. An answer that leaves out a key, or is `null`, fails like a factory that throws: keys with a fail-safe value get it, and nothing from the answer is cached. Before, the values for the other keys were cached before the call threw. - **`MethodCache`**: `IMethodCacheKeys.MethodId` no longer creates the service; it reads the method from the call. ### Documentation - [Invalidation](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/invalidation.md#with-several-instances) says what each count of `InvalidationResult` confirms, and [What other instances see](https://github.com/eoniclabs/MethodCache/blob/main/docs/features/distributed-cache.md#what-other-instances-see) how Redis, SQL Server and PostgreSQL catch up after a lost backplane connection. Code that earlier release candidates generated keeps working. It doesn't name the methods' result types, so for it a `CacheWhen` of the wrong type is still reported by the call. ## 1.0.0-rc.3 (2026-11-04) The packages are on nuget.org only. GitHub Packages no longer has the MethodCache packages, so remove a `nuget.pkg.github.com/eoniclabs` source you added for them. ### Added - **`MethodCache.PostgreSql`**: PostgreSQL as the distributed cache, `AddMethodCache(mc => mc.UsePostgreSql(connectionString))`. Invalidations reach other instances at once through `LISTEN`/`NOTIFY`, with the invalidations table as the truth and a poll every second as a safety net, so a lost notification or a pooler in transaction mode only delays them. Every read and every new value is one prepared statement; new cache values and backplane messages are committed without waiting for the disk (replacements of live values and invalidation stamps are not), and values up to about 8 KB stay in the row. Small values read about as fast as from Redis. After a crash, a failover or a restore, every instance clears its in-memory cache. The tables are created at startup, or by the package's `migrations/0001-create-schema.sql`. Requires PostgreSQL 13 or later. ### Fixed - **`MethodCache.SqlServer`**: cache commands no longer join the application's `TransactionScope`. A scope that rolled back undid the cache writes and invalidations made inside it, and the cache's connection could turn it into a distributed transaction. - **`MethodCache.SqlServer`**: an instance clears its in-memory cache when it may have missed invalidations in two more cases: SQL Server was unreachable from startup for half of `BackplaneRetention`, or the instance fell behind the invalidations table for that long. Instances that share a `KeyPrefix` now keep invalidations as long as the longest `BackplaneRetention` any of them uses, so one with a shorter setting no longer deletes rows the others haven't read, and old invalidations are deleted apart from polling, so a large delete no longer holds back delivery. - **`MethodCache`**: disposing the cache no longer deadlocks with a custom `IBackplane` whose `UnsubscribeAsync` waits for a delivery in progress. ## 1.0.0-rc.2 (2026-10-20) ### Breaking changes since 1.0.0-rc.1 Two API reviews before 1.0.0 removed duplicates and names that didn't match the rest of the API, and made settings that were accepted but did nothing fail at startup instead. Each change below says what to write instead. Registration - `AddMethodCacheRedis`, `AddMethodCacheSqlServer` and `AddMethodCacheMessagePack` are removed. Use the builder: `services.AddMethodCache(mc => mc.UseRedis("localhost:6379"))`, `mc.UseSqlServer(...)` and `mc.UseMessagePack()`. - The classes that hold these methods are now `RedisMethodCacheBuilderExtensions`, `SqlServerMethodCacheBuilderExtensions` and `MessagePackMethodCacheBuilderExtensions`, and `MethodCacheAdminEndpoints` is `MethodCacheEndpointRouteBuilderExtensions`. This matters only where you call them as static methods. - An app has one distributed cache: `UseRedis` and `UseSqlServer` together throw in `AddMethodCache`, naming both. Before, the app started, stored values in the second one and kept the first one's backplane. Keep one of them. - `mc.Method(...)` on a method without `[Cache]` fails at startup. Before, it logged a warning and changed nothing. Add `[Cache]` to the method, or remove the line. - The `MethodCacheBuilder.Method` and `IRuntimeCacheConfigurator` overloads for methods that return nothing (`Expression>` and `Expression>`) and `IFluentMethodConfiguration` without a type argument are removed, since such methods can't be cached. Pointing `Method`, `UpsertAsync` or `RemoveAsync` at a `void`, `Task` or `ValueTask` method throws an `ArgumentException`. - Several registrations of one interface under the same service key can no longer share cached results when they may be configured differently: an instance registration whose type another of them also has fails in `AddMethodCache`, and a factory that creates the same type as another of them fails once both are created. Register them under different service keys. Registrations the container builds from the same type, such as a library and the app both calling `AddSingleton()`, still share their results. Options and attributes - `CacheEntryOptions.Builder.RefreshAhead` is now `WithRefreshAhead`, like every other builder method. - `CacheEntryOptions.Builder.FailSafe(duration, timeout, retryAfter)` is now three methods, one per setting as in `[Cache]` and `appsettings.json`: `WithFailSafe(duration)`, `WithFailSafeTimeout(timeout)` and `WithFailSafeRetryAfter(retryAfter)`, so an override can change one value without repeating the others. - `[Cache(RetryAfter = ...)]` and `[CacheInterface(RetryAfter = ...)]` are now `FailSafeRetryAfter`, the name used in code and in `appsettings.json`. - `CacheEntryOptions.Builder.WithTags` is now `AddTags`, since it adds to the tags instead of replacing them. It throws an `ArgumentException` for a null, empty or whitespace tag, as `InvalidateTagsAsync` does; before, such a tag was skipped. - `IFluentMethodConfiguration.WithVersion(n)` is removed; write `.Configure(o => o.WithVersion(n))`. - `CacheWhen` is set per method: in `mc.Defaults(...)` or `mc.Group(...)` it fails at startup. Before, every method that didn't return that type threw an `InvalidOperationException` on each miss, after the method had run. Use `mc.Method(...).CacheWhen(...)` for each method it applies to. - A `CacheWhen` for a type the method can't return, such as `CacheWhen` on an `int` method, throws an `InvalidOperationException` on the call. Before, it silently cached nothing. - `[Cache]` or `[assembly: CacheInterface]` with a `RefreshAhead` that isn't shorter than the `Duration` or `SlidingExpiration` next to it is the new error MC0023, as in code and `appsettings.json`. Before, it compiled and the window was cut to half the entry's life while the app ran. Make it shorter than both, or remove it. - `MethodCacheMemoryOptions.SizeLimit` is now `WeightLimit`. `MaxItems` and `WeightLimit` both bound the cache, so an entry is evicted when either is reached; before, a `Weigher` made `MaxItems` stop counting. Setting `WeightLimit` without a `Weigher` fails at startup instead of being ignored. - `MethodCacheMemoryOptions`, `RedisOptions` and `SqlServerOptions` are sealed, like the other options classes. Configuration files - The `"Services"` section of `appsettings.json` is now `"Methods"`, since each key in it is a method id; environment variables are named `MethodCache__Methods__0__MethodId` and so on. A leftover `"Services"` section fails at startup as an unknown setting. - Startup fails, naming the setting, for configuration that was ignored or applied in a way nobody asked for: - A method id that matches no cached method, such as a misspelled name or an id without its `[Assembly]` prefix. The message suggests the closest cached id. Before, a warning was logged. - A method listed twice, for example by name in `appsettings.json` and under an index in an environment variable. Before, one of them replaced the other without a word. To override a file from another source, list the method under the same index in both. - `"*"` or `"group:"` as a method id. Use `Defaults`, or the new `Groups` section. - `Group`, `Metadata` or `Notes` in `Defaults`, and a `"group"` key in a method's `Metadata`, which moved the method to that group. Use `Group` on the method. - The same fail-safe value both in `Defaults` and in the top-level `FailSafe` block, such as `Defaults.FailSafeTimeout` and `FailSafe.Timeout`. Set it in one place. - Tag templates such as `"order:{orderId}"` from `appsettings.json`, from startup code and from runtime overrides are checked against the parameters of every method they reach, with the rules of MC0010, MC0016 and MC0017 for `[Cache]`. A template with a misspelled parameter fails at startup, rejects a reload, or makes `UpsertAsync` throw. Before, it became a tag with the literal text, which no invalidation matched. Keys - `MethodCacheKeys.For`, `ForVersion`, `KeyedMethodName`, `TypePart`, `Sequence`, `Prefix` and `Pattern`, and the constants `MethodCacheKeys.Null` and `Separator`, are removed. A key built by hand went wrong without notice after a version, an overload, a generic argument or a keyed registration was added, and the prefix of `GetUser` also matched `GetUsers`. For one key, write `keys.For(users => users.GetUser(42))` with the new `IMethodCacheKeys`. For all entries of a method, pass `keys.MethodId(users => users.GetUser(0))` to `ICacheAdministrator.InvalidateMethodAsync` or `ListEntries(methodId: ...)`. `MethodCacheKeys.Part` stays, for tags. - `CacheEntryOptions.GetCacheKey` and `CacheManagerExtensions.GetCacheKey` are replaced by `MethodCacheKeys.StoredKey(key, version)`. A generated call passes `Version = null` to your `ICacheManager`, since its key already holds the version. A custom manager stores under `StoredKey(key, options?.Version)`, and under `StoredKey(key, version)` in `TryGetAsync` and `InvalidateKeysAsync`. Before, a manager that added `options.Version` stored generated entries with the version twice, and invalidating the key from `IMethodCacheKeys` missed them. Manual caching - `ICacheManager.GetOrCreateAsync` takes a state and a factory `(state, ct) => ...`, like `HybridCache`, so a hot path can use a static lambda without a closure. `CacheContext` is removed: the factory gets the cancellation token, and `GetOrCreateAsync(key, ct => ...)` keeps working through the extension methods. - `GetOrCreateManyAsync` factories take `(keys, ct)` instead of `(keys, context, ct)` and return an `IReadOnlyDictionary` instead of an `IDictionary`, and so does the call. A `Dictionary` works as both. - The `TryGetAsync` extension method that duplicated `ICacheManager.TryGetAsync` is removed. - `NoOpCacheManager` moved from `MethodCache.Extensibility` to `MethodCache` and is sealed; wrap it to change one call. Administration - `ICacheAdministrator.InvalidateTagsAsync` takes an `IEnumerable` and returns the `InvalidationResult` in a `ValueTask`. It covers method and HTTP entries. - `ICacheAdministrator.GetStatsAsync` returns a `CacheStats` record instead of an `ICacheStats`, which is removed, as is the AspNetCore `CacheStatsResponse`; the stats endpoint returns `CacheStats` unchanged. - `CacheEntryInfo.Key` is now `StoredKey`, and `ListEntries`, `GetEntry` and `RemoveEntryAsync` take `storedKeyPrefix` and `storedKey`. It is the key as stored, which for a manual entry with a version is not the key you pass to `ICacheManager`. The admin endpoints return it as `storedKey`. - `RemoveEntryAsync`, `InvalidateTagsAsync` and `ClearAsync` throw the public `CacheInvalidationQueuedException` when the change is applied in memory but still queued for the distributed cache. Before, they threw an internal type. - `InvalidationQueues.Distributed` and `Publication` are now `Queued` and `PublicationQueued`, the names `InvalidationResult` uses. `Distributed` counted invalidations still waiting for the distributed cache, while `InvalidationResult.Distributed` counts confirmed ones. - `CachedMethodInfo.Duration`, `Tags`, `Version`, `Sources` and `L2Namespace` are removed. Read `Options.Duration`, `Options.Tags` and `Options.Version`, `SettingSources` and `IsDistributedNamespaceShared` instead. - `CachedMethodInfo.SettingSources` maps a `CacheEntryOptions` property name, such as `Duration` or `FailSafeTimeout`, to a `CacheSettingSource`: `Attribute`, `Code`, `Configuration` or `RuntimeOverride`. Before, its keys and values were internal names such as `"startup-fluent"`. The methods endpoint returns the same names. - `CacheEntryInfo`, `CachedMethodInfo`, `InvalidationQueues`, `RuntimeOverride` and `RuntimeOverrideMetadata` use `init` properties instead of positional constructors, so new properties can be added in 1.x without breaking you. Write `new RuntimeOverrideMetadata { Owner = "ops", ExpiresAt = ... }`. `CacheEntryInfo.Format` is removed. - If you implement `ICacheAdministrator` yourself: `GetInvalidationQueues()` has no default body any more (in rc.1 it returned `new(0, 0)`), and `InvalidateMethodAsync` and the `methodId` parameter of `ListEntries` are new. Runtime overrides - `IRuntimeCacheConfigurator` has the shape of `ICacheAdministrator`: `UpsertAsync`, `RemoveAsync` and `ClearAsync` return a `ValueTask` instead of a `Task`, and `GetOverridesAsync()` is now `GetOverrides()`, which returns an `IReadOnlyList` ordered by method id. `await` works as before; call `.AsTask()` where you need a `Task`. - The expression helpers take one type argument, like `IMethodCacheKeys.For`: write `UpsertAsync(s => s.GetAsync(Any.Value), o => ...)` instead of `UpsertAsync(...)`, and the same for `RemoveAsync`. They work for methods returning `T`, `Task` and `ValueTask`. A method without `[Cache]` throws an `ArgumentException` that names the closest cached method id. ASP.NET Core - `DELETE {prefix}/entries` is replaced by `POST {prefix}/clear` with the body `{}`. Before, `DELETE entries?tag=orders`, the natural guess after `GET entries?tag=orders`, ignored the tag and emptied the whole cache on every instance. - The query parameters `key` and `prefix` are now `storedKey` and `storedKeyPrefix`, the names the JSON uses. A query parameter an endpoint doesn't take, or a body property it doesn't take (`invalidate` takes only `tags`), answers 400 and changes nothing. - `MethodCacheHealthCheck` and the request type of the invalidate endpoint are internal; register the check with `services.AddHealthChecks().AddMethodCache()` and call the endpoints as before. - The health check reports the invalidations waiting for the distributed cache as `queued` instead of `invalidationQueued`. Telemetry - Metric and span attributes are in the `methodcache.` namespace: `kind`, `name`, `result`, `type`, `stage` and `operation` are now `methodcache.kind`, `methodcache.method` (`methodcache.http.client` for an `HttpClient`), `methodcache.result`, `methodcache.invalidation.type`, `methodcache.invalidation.stage` and `methodcache.operation`. Before, `name` and `kind` clashed with the application's attributes and with a span's own fields. Update dashboards, alerts and views. - An `ICacheManager` call by key reports `methodcache.kind=manual` and no method, instead of `name="MethodCache.Fluent"` or `"MethodCache.Fluent.Bulk"`; a `GetOrCreateManyAsync` batch adds `methodcache.bulk=true`. - `methodcache.load.duration` and `methodcache.distributed.duration` advise bucket boundaries in seconds, from 5 ms to 10 s. Before, SDKs used their millisecond buckets, every value fell into the first one, and percentiles meant nothing. - The `MethodCache.distributed` span is `Internal` instead of `Client`, so the Redis and SqlClient client spans nest under it. HTTP caching - `HttpCacheOptions.MaxResponseSize` is now `MaxResponseBytes`. Zero or less fails at startup; before, `0` meant no limit. Write `long.MaxValue` for no limit. - `HttpCacheOptions.CacheableMethods` is removed. GET and HEAD responses are cached, as before; a POST or PUT added to the set was ignored anyway. - `AddDiagnosticHeaders` adds a `MethodCache` member to the RFC 9211 `Cache-Status` header, such as `Cache-Status: MethodCache; hit; ttl=42`, instead of `X-Cache`, `X-Cache-Age` and `X-Cache-TTL`. Behind a CDN that sets `X-Cache` itself, MethodCache's outcome was hidden. - A GET or HEAD whose response replaces a stored one that can't be retired throws `HttpCacheInvalidationException`, like a write, with a message that says a retry is safe. Before, it threw `CacheInvalidationQueuedException`, whose message said the origin mutation may have succeeded. Add-on packages - `RedisOptions.Configuration` has no default, and startup fails when neither `Configuration` nor `ConnectionMultiplexerFactory` is set. Before, it was `localhost:6379`, so a missing configuration section made the app run without a distributed cache and without invalidation between instances, silently. Write `UseRedis("localhost:6379")` for a local Redis. - `UseMessagePack(MessagePackSerializerOptions)` is now `UseMessagePack(o => ...)`, which receives MethodCache's defaults: `UseMessagePack(o => o.WithCompression(MessagePackCompression.None))` keeps `UntrustedData` and the contractless resolver. Before, options built from `MessagePackSerializerOptions.Standard` dropped them without notice. ### Added - `IMethodCacheKeys`, resolved from dependency injection, returns the key of a call to a cached method, `keys.For(users => users.GetUser(42))`, and the method's id, `keys.MethodId(...)`. Overloads, versions, generic methods and keyed registrations are handled like the real call, so you no longer write `"FindAsync(string)"` or the version yourself. - `ICacheAdministrator.InvalidateMethodAsync(methodId)` removes every result of one method, on every instance, and `POST {prefix}/invalidate-method` does the same over HTTP. `CacheEntryInfo.MethodId` and `ListEntries(methodId: ...)` (`GET entries?methodId=`) show one method's entries. An id that no cached method has throws an `ArgumentException`, and the endpoints answer 400. - A `"Groups"` section in `appsettings.json` sets a group's policy, with the settings of `Defaults` plus `ClearTags`. It wins over `mc.Group(...)` in code; a method's own settings win over both. - `mc.Distributed(o => ...)` and `mc.Telemetry(o => ...)` configure `DistributedCacheOptions` and `MethodCacheTelemetryOptions`, so you don't need `services.Configure<...>` for them. `MethodCacheBuilder.Services` is public, for a package that adds its own `mc.UseXxx()`. - `SlidingExpiration` and `RefreshAhead` accept `"off"` in `[Cache]` and `appsettings.json`, and `TimeSpan.Zero` in `WithSlidingExpiration` and `WithRefreshAhead`, to turn an inherited window off for one method, as `FailSafe` already did. Before, a method could not turn them off. - `CacheInvalidationQueuedException.Result` holds the counts of the invalidation that is still queued (`null` after `ClearAsync`), and the exception has the standard constructors. - `GetOrCreateManyAsync` takes built `CacheEntryOptions`, so a hot bulk call can reuse them, as `GetOrCreateAsync` can. ### Fixed - Several registrations of one interface, such as two `IPriceProvider` implementations resolved as `IEnumerable`, shared cached results, so every provider returned the first one's answer. Each implementation type now caches its own results; its keys carry the type. A single registration keeps its keys. - A keyed service whose constructor takes a `[ServiceKey]` parameter got MethodCache's internal key and couldn't be resolved. It gets your key, as without MethodCache. - Resolving a cached interface with `KeyedService.AnyKey` also returned the implementations without caching. It returns only the cached ones. - `GetOrCreateManyAsync` kept a cancelled caller waiting while a factory that ignored the token ran. The caller stops waiting, and the batch finishes in the background and is cached, as with `GetOrCreateAsync`. - `GetOrCreateManyAsync` threw when the factory failed, where `GetOrCreateAsync` served the fail-safe value. Each key now gets its fail-safe value; the factory's exception is thrown only when a key has none. - A typed `.CacheWhen(...)` on `mc.Method(...)` won over a later `.Configure(o => o.CacheWhen(...))`. The last call wins. - `GetOverridesAsync` reported `ClearsTags = false` for an override that cleared tags; `GetOverrides` reports it. - A `ConnectionMultiplexerFactory` ran inside a lock on the thread of the first cached call, so while Redis was slow or down that call and every concurrent one waited for the connect timeout. It runs on the thread pool, and calls are served from memory and your method in the meantime. - `AddHttpCaching` both in `ConfigureHttpClientDefaults` and on a named client added two cache handlers to that client. It has one, and every settings delegate applies; use `services.Configure("name", o => ...)` to give one client other settings. - Invalid `UseSqlServer` options gave the same general message for every problem. The message names the rule. - Calling `UseSqlServer` more than once, to add to its options, created the tables once per call at startup, and while SQL Server was down each call waited and retried on its own. The tables are created once. - A rejected `appsettings.json` reload logged only the exception type. It logs the setting's path and what is wrong with it, never the value. - A project's own `` replaced MethodCache's CS9057 error, so with a too old SDK the generator was skipped with only a warning and nothing was cached. The rule comes from a `.targets` file and keeps the project's list. - `mc.Distributed(...)`, `UseMessagePack()` or `UseJson(...)` without `UseRedis` or `UseSqlServer` did nothing without a word. Startup logs a warning. ## 1.0.0-rc.1 (2026-10-19) The first public release on nuget.org, as a release candidate. Install it with `--prerelease` (`dotnet add package MethodCache --prerelease`). The public API can still change before 1.0.0 if the release candidate shows a problem; from 1.0.0 on, MethodCache follows semantic versioning. | Package | What it adds | |---|---| | `MethodCache` | `[Cache]` and `[CacheInvalidate]`, the source generator, the analyzers and the in-memory cache | | `MethodCache.Redis` | Redis as the distributed cache, with a pub/sub backplane that keeps every instance's memory in sync | | `MethodCache.SqlServer` | SQL Server as the distributed cache, with a polling backplane | | `MethodCache.Serialization.MessagePack` | MessagePack instead of System.Text.Json for distributed values | | `MethodCache.AspNetCore` | Admin endpoints and a health check | | `MethodCache.OpenTelemetry` | Traces and metrics for cache operations | | `MethodCache.HttpCaching` | HTTP caching for `HttpClient`: ETag and Last-Modified revalidation, Cache-Control and Vary | All packages require .NET 10 and the .NET 10 SDK. ### Changes since the pre-release builds Only relevant if you used a build from GitHub Packages or from this repository before the first nuget.org release. - Retry transient Redis subscription-recovery failures without waiting for another socket event, preserving single delivery, generation guards and cancellable shutdown. - Every package carries the MethodCache logo as its NuGet icon. - Keep logical-key framing consistent across storage, lookups and invalidation, including leading NUL. Custom managers now accept and forward the optional version on `TryGetAsync` and `InvalidateKeysAsync`. - Use SipHash-1-3 with a secret 128-bit key kept for the process lifetime for memory-key lookups. Prefix reuse preserves exact UTF-16 key text, equality, L2 addresses and invalidation identities. - Keep one Redis callback per subscription after repeated reconnects. Incompatible L2 scopes fall back to memory, retain invalidations and report an actionable unhealthy status. - Reject durations that contain fractional ticks, preserve MC0004 for invalid durations, and report each shared attribute error once when generator and analyzer run together. - Report HTTP/admin invalidations awaiting distributed confirmation as 503; accept long client names through bounded hashed identities and validate static tags at startup. - Before release, narrow and refreeze generated contract 1: all inline key shapes use a bound builder. Rebuild applications using earlier development snapshots together with this Core. Diagnostic migration: MC0001 stays MC0001; duration MC0004 stays MC0004; MCG001 → MC0003; MCG002 → MC0022; MCG003–MCG007 → MC0005–MC0009; MCG009–MCG019 → MC0010–MC0020. MC0021 rejects explicit negative versions. Update analyzer suppressions and `.editorconfig`; migrate `[Cache("group")]` to `[Cache(Group = "group")]` and remove `[CacheKey]`. Canonical `ICacheKeyProvider` parts and manual `ICacheManager` keys replace raw-key use cases. - Avoid the implicit client-tag index on local HTTP publication. Client-tag invalidation scans resident HTTP entries and physically reclaims matching bodies; URL and other application-tag indexes remain. - Keep sparse tag indexes small and materialize local HTTP epoch/URL metadata only when needed. Administration, generation identities and conservative byte-budget accounting are preserved. - Reuse already successful HTTP origin tasks while recording the same load duration, errors and activity parent. - Reuse an entry's existing process-keyed hash when evicting or expiring it, avoiding redundant hashing during cache pressure without changing key identity or eviction behavior. - Reuse the latest SQL Server epoch command shape instead of rebuilding its SQL text on every HTTP lookup. Generation values remain fresh; reordered and duplicate keys retain their caller positions. - Avoid temporary sets and sorting when HTTP responses have no custom key headers or `Vary` fields; private caches still select by `Authorization` and `Cookie`. - Avoid allocating unused fail-safe and distributed-write closures on memory-only asynchronous misses. - Read already initialized, permanent SQL Server HTTP epoch metadata without rewriting its rows. Missing, expired or finite/sliding metadata is still initialized or repaired under the same atomic locks. - Keep generated source filenames bounded for long namespace/type identifiers, including Unicode, when `EmitCompilerGeneratedFiles` is enabled. Generated types and cache identities are unchanged. - **Breaking before 1.0:** all runtime packages now require .NET 10 and the .NET 10 SDK. Remove .NET 8/9 targets, their CI/package matrix and the allocating pre-.NET 9 lookup fallback. Generated contract 1 is refrozen before the first release. #### Core telemetry and attribute diagnostics - Move instrumentation into Core's container-owned Meter/ActivitySource; the OpenTelemetry package now only subscribes. Replace provider/wrapper APIs with `MethodCacheTelemetryOptions`, one final request outcome and seconds histograms. Spans/logs omit exception payloads and copied request identities; key/tag recording is explicit opt-in. - Replace object-memory estimates with local method/HTTP counts, HTTP bytes, observed distributed entries and `TotalWeight` in configured units. Health checks honor `failureStatus` and distinguish L2 availability from actual backplane connection state and the two recovery queues. - Unify duration parsing and generator errors; add named attribute groups, enabled/distributed flags and fail-safe retry delay. Remove raw-key attributes and consolidate diagnostic IDs. Dynamic tag placeholders now use canonical key parts while existing contract-1 binaries retain their formatting. - Omit invalid reload values and policy watcher exception payloads from diagnostic logs; retain error types. - Drain HTTP generation recovery before disposing its transport. Retry once through an open breaker and report unconfirmed URL invalidations at shutdown without exposing targets. #### Core-owned HTTP storage - Derive local HTTP administration IDs when first inspected, avoiding the hash and ID allocation on cold publication. IDs, removal behavior and conservative response-budget accounting remain unchanged. - Merge 304 response headers directly into the replacement representation, avoiding a temporary dictionary and per-response filter allocations when no Connection options are present. - Avoid constructing duplicate response/content/header objects during foreground 304 revalidation; validate the returned representation before adding caller-only headers, and preserve background/error ownership. - Release every retired local response body when its URL generation slot is invalidated, including colliding URLs. Avoid temporary identity/target buffers and reuse immutable local metadata during response replacement. - Require explicit AddMethodCache alongside AddHttpCaching, in either order. Core owns a separate 100 MiB HTTP byte budget, or exclusively uses MethodCache's native Redis/SQL Server transport. Remove the public HTTP storage options/interface/entry extension points and the application-cache fallback. - Capture shared atomic URL/client/static-tag/clear generations before origin work. Confirm unsafe mutation invalidation across nodes and value formats even with lost backplane messages; retain owned recovery when callers cancel. Unconfirmed mutations throw HttpCacheInvalidationException and must not be retried automatically. - Add KeepCookies for a complete response-cache bypass, static HTTP tags, resident/observed administration and bounded body-free L2 observations. Core telemetry and health distinguish HTTP capability from method statistics. #### Owned distributed transports and stable wire contract - Freeze one Core prefix and validated provider options at startup; use owned storage and serializer registrations. Application `IDistributedCache` is never a fallback. SQL connection strings can come from DI. - Add wire v1 and entry format 6 with absolute deadlines, format-independent logical invalidation and shared retention bounds. Malformed mandatory frames clear local entries and warn once. - Add native batched reads and permanent atomic epochs in Redis/SQL Server; version SQL schemas and ship an explicit legacy migration. - Select JSON through copied options or a source-generated context. Add `VerifyRoundTrip` and `SerializerVersion`; internalize serializer/atomic-store interfaces. #### Cache API and policy isolation - Reduce ICacheManager to four async operations with immutable options and explicit invalidation results. - Retire local generations on effective policy changes, isolate runtime L2 namespaces and validate L2 lifetimes from first publication. - Internalize policy/key/backplane implementation APIs and remove public cache callbacks and memory tuning switches. - Keep the replaced fluent root/service/group coordinators internal; startup configuration uses `MethodCacheBuilder` and retains its public method configuration results. #### Generated contract and explicit startup registration - Generated decorators use the versioned `MethodCache.Generated` facade. Each invocation captures one immutable policy/key snapshot; retired snapshots bypass caching and cannot publish into the current generation. - Startup uses `MethodCacheBuilder`, with `Defaults`, `Group`, typed `Method` expressions and explicit module selection. Missing services require `AutoRegister(lifetime)` and exactly one accessible implementation. Cacheable late, open generic, catch-all keyed and unsupported bindings produce named errors. - Built-in synchronous methods use a synchronous factory and single-flight path. Async-only custom managers bypass synchronous caching with a diagnostic. Distributed adapters without bounded native synchronous operations are unavailable for these calls; use async methods for L2 and distributed mutation invalidation. - All six add-on packages require the exact matching Core package version. Frozen vendor binaries are tested under the current runtime and Native AOT without rebuilding their source during ordinary tests. #### Project review fixes - Bulk factory results invalidated during their source read are not published; concurrent individual writes still win. - Collection subclasses keep their public state in default, JSON and MessagePack keys. Collection subtypes needing runtime-state serialization now use hashed keys; earlier inline keys for those subtypes become cold misses. - Static tags skip argument formatting, and dynamic tags format only referenced parameters. - Redis backplane publication honors cancellation, and cancelled unsubscribe acknowledgements no longer fail application shutdown. SQL backplane gaps survive slow transactions; a separate non-waiting probe retires confirmed absent identities while newer invalidations and other committed gaps keep arriving. - HTTP full replacement responses retire older entries when they cannot be stored. Stale-while-revalidate honors request freshness limits, and concurrent first variants share an index without hiding each other. Variant indexes outlive their bodies, and selection-rule changes retire the URL epoch once, preserving concurrent publications in the new epoch even when deleting the old entry fails after rotation. - Backplane gap failure coverage runs without infrastructure in the Core fault-injection suite; real SQL lock checks supplement it. - Memory benchmarks measure fresh fills and real tag invalidations; short-lived entries use the intended duration. - SQL Server pins patched PKCS dependency versions for [CVE-2026-84008](https://github.com/advisories/GHSA-846f-f764-76mx), restoring the high-severity dependency audit gate. #### Remove retained compatibility code The previous memory engine benchmark baseline is removed, and current runtime-key benchmarks have descriptive names. SQL Server backplane initialization requires `Scope binary(32) NOT NULL`; automatic migration and cleanup of unscoped rows are removed. Schema errors are logged, and table initialization uses the registered `TimeProvider` for its startup deadline and retry interval. Benchmark `--list` commands no longer throw. #### Release audit fixes The release audit fixes presence-aware manual reads, caller cancellation during loads, immutable policy tags, HTTP response age and background request metadata, keyed registrations and OpenTelemetry ownership, generic method constraints and attribute code fixes, and weighted capacity overflow. The web demo now stores atomic price updates in SQLite, and the memory benchmark measures an uncached baseline. MessagePack keys preserve derived member data in nested base-class/interface slots and collection elements. Earlier keys for these arguments become cold misses. Overloaded generic methods include generic arity in their policy ids and key prefixes, keeping different overloads distinct; earlier keys become cold misses. #### Third review fixes - **HTTP caching** no longer stores a redirect the transport followed under the original URL (the transport drops `Authorization`, so one caller's response could reach another), invalidates the URL a `POST` was sent to also when it answers `303`, and removes its own validators so a retry of the same request gets a full response. `Vary: Accept-Encoding` works with automatic decompression, a `GET` with a body bypasses the cache, a `Cache-Control` or `Vary` that doesn't parse is not stored, clients that get caching from `ConfigureHttpClientDefaults` keep their own entries, far-future `Expires` no longer overflows, weak ETags stay weak, and the URL fragment is not part of the key. HTTP cache keys change, so entries from an earlier build are misses. - **Loading and fail-safe**: a value invalidated or replaced while (or just before) its reload ran is no longer served as the fail-safe fallback to callers that joined the reload or a failed background refresh. A factory that requests the key it is loading now throws `InvalidOperationException` instead of hanging that key for every later caller. While a fail-safe value is reused, refresh-ahead no longer retries the method before `retryAfter`. - **Refresh-ahead**: a `RefreshAhead` not shorter than `Duration` or `SlidingExpiration` is rejected by `CacheEntryOptions.Builder.Build()` and in `appsettings.json` (startup fails); one that comes from combining sources starts the reload halfway through the entry's life instead of reloading on every read. - **Memory cache**: a manager that is never disposed no longer keeps its values (and the execution context of whoever created it) alive through its cleanup timer. `GetOrCreateManyAsync` no longer sends cached keys to the factory with `EnableFastPath = false` or inside a refresh window. The default `ICacheManager.TryGetFast` of a custom manager asks `LookupAsync`, so a cached `0`, `false` or `null` is a hit. `WithDuration`'s error message no longer promises entries that never expire. - **Distributed cache**: a tag invalidation or clear another instance announces while a stamp read is on the wire is no longer forgotten (which promoted invalidated entries into memory). Invalidations queued during an outage are stored in batches, so a large backlog drains; more than 10,000, or one the cache keeps refusing, become one clear. On shutdown the queue is tried once more, after a retry already running (which stops after the batch it is storing), and what is lost is logged. Keys whose write timed out are removed at shutdown instead of after a delay nothing waits for, and further timed-out writes of a key push its one removal back instead of adding another. Shutdown also waits for writes still running (each capped by the operation timeout), so the removal one of them leaves behind is stored with the rest of the queue. A write that times out no longer opens the circuit breaker for the whole instance. A tag or clear stamp from a server whose clock runs ahead no longer turns every entry written since into a miss. - **Serialization**: the default `JsonCacheSerializer` includes public fields, so value tuples and structs with fields are shared through the distributed cache instead of coming back empty. Each value written is read back first; values that don't survive that (private setters, a derived type returned as its base type, `object`) stay in memory only, with one warning, instead of handing other instances a value with missing data. Collections declared as interfaces are still shared when they come back as another implementation. A derived value nested in a collection or property isn't detected. Including fields changes two things: a type with a public field the serializer can't write (a delegate, a reference back to the object) now fails to serialize, and a public readonly field of a type with a parameterless constructor doesn't read back. Both now stay in memory only with one warning; before, the field was left out and the rest was shared. A value the serializer throws on now warns once per method and type instead of on every write. Entries an earlier build wrote for types with public fields are read without those fields until they expire. - **Redis**: a connection factory that threw once (Redis down at first use) is asked again on the next call instead of failing until restart, and the backplane retries its subscription with backoff (1 s doubling to 30 s, a warning per failure) instead of never subscribing. Once it subscribes after failing, it clears this instance's memory, as after a reconnect, since invalidations sent meanwhile never arrived. The docs now say to run Redis with `maxmemory-policy noeviction`: an evicted invalidation stamp brings invalidated values back. - **SQL Server**: a `TagRetention` that ends after 9999-12-31 fails at startup instead of making every tag invalidation fail, and stamp expiry is capped there. Expired rows are deleted every 5 minutes instead of 30, so each delete stays small. - **Generated decorators** compile for generic methods constrained to a base class (`where T : Entity`), keep `scoped` on forwarded parameters, escape U+2028/U+2029 in tag and group literals, skip `file` classes when picking an implementation to register, and no longer clash (CS0436) with a referenced project's generated code through `InternalsVisibleTo`. `[Cache]` or `[CacheInvalidate]` on a `static`, non-public or `sealed` interface member is now warning MCG017 instead of being ignored. The IDE builds each decorator once per edit, not once per cached method. - **Keys**: two cached methods with the same name on different interfaces of one hierarchy (`ICatalog : ILookup`, or `IC : IA, IB`) no longer share entries; their keys add the parameter types, and the declaring interface when the signatures are equal. `-0.0` and `0.0` are two keys in hashed keys too, `NaN` and infinities inside a hashed argument no longer throw, and `[CacheKey(UseAsRawKey = true)]` dates are written like generated keys: they keep fractions of a second and their offset, and a local time is written as UTC, so the key doesn't depend on the server's time zone. Keys of these methods and arguments change, so their entries from an earlier build are misses. - **Metrics and spans** name a cached method by its id (`MyApp.IUserService.GetAsync`) instead of its bare name, so same-named methods on different interfaces are separate series, as the OpenTelemetry README shows. A method inherited from a generic interface reports the closed type it comes from, so `IUserRepo : IRepository` and `IOrderRepo : IRepository` report `IRepository.Get` and `IRepository.Get`. - **Framework types in keys**: `BigInteger`, `Complex`, `IPAddress`, `JsonElement`, `Half`, `Int128`, `DateOnly`, `Uri`, `Version` and other immutable .NET types are written by their value, in every key generator and inside records and collections. Before, the decorator wrote `BigInteger`'s `IsZero` and `Sign`, so 3 and 5 shared one entry, and `IPAddress` threw. Other types from .NET, ASP.NET Core or Microsoft.Extensions in a key, such as `StringBuilder` or `CultureInfo`, are now build error MCG018 instead of a key that ignores their value. Keys of arguments with these types change, so their entries from an earlier build are misses. - **Result types a distributed cache can't restore** (`object`, an interface or an abstract class, also as an element) get warning MCG019: with a distributed cache, the default round-trip check keeps those results in memory only. - **`[assembly: CacheInterface]` in a class library** decorates the client even when none of the library's code has run before `AddMethodCache()`, also when several threads resolve services while the library's initializer runs. - **Dependency injection.** Generated decorators implement `IDisposable`/`IAsyncDisposable` only when the interface does, so the container no longer keeps every transient decorator resolved from the root (their `ownsDecorated` constructor parameter is gone). Keyed registrations are decorated under their own key, with the service key in their cache keys (`MyApp.IRates.Get@ecb:1`, see `MethodCacheKeys.KeyedMethodName`), so two registrations of one interface never share entries; a key that isn't a string, enum, bool, char, integer or `Guid` makes `AddMethodCache()` throw. An interface registered only keyed no longer gets an extra unkeyed singleton. When two assemblies generate a decorator for the same interface (`[assembly: CacheInterface]` in a library and in the app), the one in the assemblies passed to `AddMethodCache` (by default the caller's) or else the entry assembly's is used, instead of whichever module initializer ran last; otherwise `AddMethodCache` throws naming both. - **Startup validation.** The generic host loads every policy source when it starts, so startup-code misconfiguration and invalid appsettings fail `StartAsync` and unknown method ids are logged then, not on the first call. `AddMethodCacheFromConfiguration` reads its section at that point, so configuration sources added after the call count. appsettings now rejects unknown setting names, a single value for `Tags`, an object for a method's `FailSafe` and time spans without `:` (`"300"` was 300 days). The resolved policy of a method keeps the newest version when two sources change it concurrently. The `MethodId` property for environment variables is documented. - **OpenTelemetry and admin.** `ICacheMetricsProvider.CacheLatency` takes a `TimeSpan`, and `load_duration` keeps sub-millisecond precision. `EnableMetrics = false` keeps the app's own metrics provider, and options from several calls or `Configure` compose instead of resetting. A hit no longer writes a shared counter when nothing listens; the hit ratio comes from the cache's statistics. `SetCacheUserId(null)` and `SetCacheTenantId(null)` clear the value. Admin `DELETE entry` answers 204 with a distributed cache, since the removal reached it and the other instances. The web demo's `.http` walkthrough loads product 2 before showing it is still cached. - **Tags combine across policy layers.** Tags from startup code, `appsettings.json`, runtime overrides and the defaults are added to the `[Cache]` attribute's tags instead of replacing them, so a `[CacheInvalidate]` on an attribute tag always reaches the entry. To replace them, call the new `CacheEntryOptions.Builder.ClearTags()` (`CachePolicyFields.ClearTags` for a raw policy) or set `"ClearTags": true` for a method in `appsettings.json`. The docs no longer say runtime overrides win over everything: a method's own override wins over its other layers, while runtime defaults (`DefaultPolicy`, `ForGroup` in `ApplyAsync`) only fill in what the method leaves unset, as before. - **Background loads of scoped services.** A refresh-ahead, and a fail-safe call that goes on after its caller got the expired value, now run a scoped or transient service on a new instance from a new DI scope (keyed services keep their key), disposed when the load ends, instead of on the request's instance after its scope was disposed. Every scoped or transient cached service the load calls gets its own scope, and a call left running after the load ended gets none. The scope factory comes from the root container. Singletons are unchanged. Generated decorators call the new `DecoratorServices.ForLoad`, so rebuild the projects that generate them together with the new MethodCache.Core. #### If you used a pre-release build from GitHub Packages - **Generated `Add{Interface}WithCaching` methods are gone.** Combined with `AddMethodCache()` they registered the service twice. Register the interface the usual way (with a factory if you need one), before `AddMethodCache()`. - **Keys for array and collection arguments.** The decorator now writes them into the key itself (`ByIdsAsync:[3:1:2:3]`) instead of hashing them, so they also work under Native AOT. Distributed cache entries written by a pre-release build for such methods are misses and expire normally. - **HTTP cache keys.** Keys are now length-framed, so every HTTP response cache key changes, including for requests without `Vary` headers. Entries written by a pre-release build are not read again; this applies to the built-in and to custom HTTP cache storage. Let them expire, or clear the storage namespace when you deploy. - **Distributed invalidation.** Backplane key and tag messages use new message types and lossless UTF-16 encoding, and distributed cache entries use envelope version 4. Invalidations do not cross between a pre-release build and 1.0.0 in either direction: a node ignores backplane messages from another MethodCache version and logs one warning, and entries written by a pre-release build are cache misses. Upgrade every node that shares a cache and backplane together, with a cache clear, or use a new cache namespace. - **SQL Server tables.** The invalidations table gets a nullable `Scope binary(32)` column and the indexes `Index_Scope_Id (Scope, Id)` and `Index_Scope_CreatedAt (Scope, CreatedAt)`; with `CreateTablesIfMissing = false`, add them in your migration before deploying. Rows without a scope are ignored and deleted once they are older than `BackplaneRetention`. Cache rows written by a pre-release build (unhashed keys) become misses and expire normally. Upgrade every instance that shares the tables together, and restart them with empty in-memory caches.