How does the L1 `IMemoryCache` and L2 `IDistributedCache` work in `HybridCache`?

[khteh]

Description

This doc doesn't provide much details on how these 2 caches work together: https://learn.microsoft.com/en-us/aspnet/core/performance/caching/overview?view=aspnetcore-10.0#features

Here are my questions:

1. In the case of different Expiration and LocalCacheExpiration values, does HybridCache automagically refresh the L1 from L2 behind the scenes?
2. Does HybridCache populate the L1 when the process (re)starts, for example, in the k8s scaling out scenario?
3. In case of L1 cache miss, does it check for L2 as other processes may have called GetOrCreateAsync and loaded the L2?

[Enter feedback here]

Page URL

https://learn.microsoft.com/en-us/aspnet/core/performance/caching/overview?view=aspnetcore-10.0#hybridcache

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/performance/caching/overview.md

Document ID

e084ce18-78e0-0807-a3b1-d70a0c1a2686

Platform Id

ebbbc6a1-6d9e-5991-ffc9-80d924122afd

Article author

@tdykstra

Metadata

• ID: e084ce18-78e0-0807-a3b1-d70a0c1a2686
• PlatformId: ebbbc6a1-6d9e-5991-ffc9-80d924122afd
• Service: aspnet-core
• Sub-service: performance

Related Issues

[mehmeddemircan]

These are really good questions — I had the same confusion when I first started using HybridCache.

From what I observed in practice, HybridCache behaves like a classic two-level read-through cache where:

L1 = IMemoryCache (per process)
L2 = IDistributedCache (shared between instances)

A few important behaviors that are not very obvious from the docs:

• Different Expiration vs LocalCacheExpiration

These are intentionally independent.

Expiration controls how long the item lives in L2.
LocalCacheExpiration controls how long it stays in the in-memory L1.

If L1 expires but L2 is still valid, HybridCache does not refresh L1 in the background.

Instead, on the next GetOrCreateAsync call:
L1 miss → it checks L2 → if found, L1 is repopulated from L2.
The factory method is not executed in this case.

So the refresh is lazy and happens only when requested.

• Process restart / k8s scale-out

Since L1 is in-memory, it starts empty when a new instance comes up.
HybridCache does not pre-populate L1.

On the first request:
L1 miss → L2 hit (if another instance already cached it) → L1 gets hydrated.

This is actually what makes HybridCache work nicely in distributed scenarios.

• L1 miss behavior

On every L1 miss, HybridCache checks L2 before running the factory.

The flow is basically:

Try L1
→ if miss, try L2
→ if hit, copy to L1 and return
→ if miss, execute factory, store in both L2 and L1

So L2 effectively acts as the shared source of truth, and L1 is a fast local layer rebuilt on demand.

Hope this helps clarify how the two layers cooperate in real scenarios.