skip to content

In ASP.NET Core, what does AddDistributedMemoryCache register, and why can't four load-balanced instances share basket snapshots through it?

level: juniorimportance: should knowfreq 38%

answer

  1. IDistributedCache over a private MemoryCache
  2. per process, despite the name
  3. SizeLimit 200 MB, Size = byte length
  4. TryAdd, so Redis or SQL wins
  5. development, tests, single-server apps

basics

~20 s

AddDistributedMemoryCache registers MemoryDistributedCache, an IDistributedCache that keeps byte arrays in a MemoryCache inside the process. Each instance therefore has its own store, so a basket written on one instance is a miss on the others.

solid answer

~40 s

`AddDistributedMemoryCache` registers `MemoryDistributedCache` as the `IDistributedCache` singleton. It implements the distributed contract, byte arrays plus `DistributedCacheEntryOptions`, on top of a private `MemoryCache` in the web process, so despite its name it is **not** distributed: four instances hold four unrelated stores. It is meant for development, tests, single-server apps and for frameworks that need some `IDistributedCache` to exist. Its options derive from `MemoryCacheOptions` with `SizeLimit` defaulting to **200 MB**, each entry's size being its byte length; at the limit new writes are dropped and compaction runs. It registers with `TryAdd`, while `AddStackExchangeRedisCache` and `AddDistributedSqlServerCache` use `Add`, so the real store wins whichever order the calls run in. A common pattern registers it in Development and Redis elsewhere.

go deeper

for a junior

Recall that AddDistributedMemoryCache implements IDistributedCache inside the process, so it is not shared between instances and suits development and tests.

for a middle

Explain the 200 MB default size limit counted in bytes, and why TryAdd versus Add makes a real store win regardless of registration order.

for a senior

Recognise what an in-memory stand-in hides, such as missing TTLs, latency and outages, and keep integration tests on the real store.

for a principal

Decide which environments may run without shared infrastructure and how much divergence between development and production behaviour the team accepts.

## What gets registered `AddDistributedMemoryCache()` lives in `Microsoft.Extensions.Caching.Memory`, next to `AddMemoryCache()`. It adds the options infrastructure and registers `MemoryDistributedCache` as a singleton `IDistributedCache`, using `TryAdd`. The class wraps a `MemoryCache` that it creates for itself: - **`Set` / `SetAsync`** create an entry with the absolute, relative and sliding expirations copied from `DistributedCacheEntryOptions`, set `Size` to the byte array's length, and store the array. - **`Get` / `GetAsync`** read the array; a read also resets a sliding expiration, just as `Refresh` does. - **Async methods** complete synchronously and return finished tasks; there is no I/O. The XML documentation of `AddDistributedMemoryCache` states the intent: frameworks that require a distributed cache can safely add it so at least one implementation exists, and it should only be used in single-server scenarios. ## Why the four storefront instances cannot share it The fashion retailer runs its storefront API as four instances behind a round-robin load balancer. With `AddDistributedMemoryCache`: 1. Request A for basket 42 hits instance 1, which serializes the snapshot and calls `SetAsync`. 2. Request B hits instance 3. Its `MemoryDistributedCache` is a different object in a different process; `GetAsync("basket:42")` returns `null`. 3. Instance 3 rebuilds the basket and stores its own copy, which can now drift from instance 1's. Nothing replicates between processes. The interface promises an out-of-process store but the implementation does not provide one, which is exactly why it fits tests: application code exercises the real `IDistributedCache` contract, including serialization, with no Redis. ## Size limit and capacity `MemoryDistributedCacheOptions` derives from `MemoryCacheOptions` and sets `SizeLimit = 200 * 1024 * 1024` in its constructor, unlike `IMemoryCache`, which has no limit by default. Because each entry's size is its byte count, the limit means roughly 200 MB of cached values. At the limit the underlying `MemoryCache` refuses the new entry with eviction reason `Capacity` and compacts in the background; `SetAsync` still completes normally, so the symptom is a falling hit rate rather than an exception. Raise or lower it with `AddDistributedMemoryCache(o => o.SizeLimit = ...)`. ## Registration order | Call | Registration | |---|---| | `AddDistributedMemoryCache()` | `TryAdd` singleton `MemoryDistributedCache` | | `AddStackExchangeRedisCache(...)` | `Add` singleton Redis implementation | | `AddDistributedSqlServerCache(...)` | `Add` singleton `SqlServerCache` | When a component registers the memory store as a fallback and `Program.cs` also adds Redis: - Memory first, Redis second: both descriptors exist and the container resolves the **last**, Redis. - Redis first, memory second: `TryAdd` sees an existing registration and adds nothing. Either way Redis is resolved. Two calls that both use `Add` are different: the last one wins, so registering SQL Server after Redis silently replaces Redis. ## Choosing per environment ```csharp if (builder.Environment.IsDevelopment()) { builder.Services.AddDistributedMemoryCache(); } else { builder.Services.AddStackExchangeRedisCache(o => { o.Configuration = builder.Configuration.GetConnectionString("redis"); o.InstanceName = "storefront:"; }); } ``` This keeps local runs free of infrastructure, but it hides store-specific behaviour: Redis's lack of a default TTL, network latency and connection failures never show up locally. Integration tests that matter should run against a real Redis. ## Compared with IMemoryCache | | `IMemoryCache` | `MemoryDistributedCache` | |---|---|---| | Values | object references | byte arrays you serialize | | Default size limit | none | 200 MB | | Shared across instances | no | no | | Swappable for Redis without code changes | no | yes | Use `IMemoryCache` for in-process caching of objects; use `AddDistributedMemoryCache` only as a stand-in for a real distributed store. ## Where it is legitimately used - **Development machines** that should run the app with no Redis or SQL Server installed. - **Integration tests** built on `WebApplicationFactory`, where a fresh in-process store per test run keeps tests isolated and fast. - **Single-instance deployments**, such as an internal tool that never scales out, where a shared store adds cost with no benefit. - **A fallback registration** in a library that needs some `IDistributedCache`; thanks to `TryAdd` it never overrides the application's real choice. In each case the deciding question is the same: will more than one process ever need to see the same entry? If yes, it needs a real distributed store.

  • Why would a team register AddDistributedMemoryCache at all instead of using IMemoryCache directly?
    Code written against `IDistributedCache` can run with no Redis in development and tests and switch to Redis in production with only a `Program.cs` change. It also satisfies libraries that require an `IDistributedCache` registration. `IMemoryCache` has a different, object-based API that cannot be swapped for a remote store.
  • A test suite registers AddDistributedMemoryCache and passes, but production on Redis fills up with keys; why didn't the tests catch it?
    Writes without `DistributedCacheEntryOptions` get no expiration in either store, but the memory store is bounded at 200 MB and discarded with the process, so the build-up never shows. Redis keeps such keys until removed or evicted. Assert on explicit options in tests, or run integration tests against a real Redis.

  • AddDistributedMemoryCache shares entries across instances because it implements IDistributedCache
  • AddDistributedMemoryCache has no size limit, like AddMemoryCache
  • Calling AddDistributedMemoryCache after AddStackExchangeRedisCache replaces Redis with memory
  • MemoryDistributedCache stores object references, so values need no serialization
  • MemoryDistributedCache replicates writes to other instances through a background sync