What is Stampede Prevention in HybridCache?

When a cache miss occurs, the data source is shielded from overload by allowing just one request to retrieve data from the database while other concurrent requests for the same key wait and subsequently receive the cached result.

What are the ways to integrate NCache with ASP.NET Core HybridCache?

You can integrate NCache in two ways: 1. As a standard L2 backing store using the default Microsoft HybridCache framework coupled with NCache IDistributedCache, or 2. As a native custom HybridCache Provider via AddNCacheHybridCache, which unlocks cluster-wide Pub/Sub synchronization and optimized tag invalidations.

How does NCache handle L1 and L2 synchronization?

NCache uses a Pub/Sub topic to notify all nodes when data is updated in the L2 distributed layer. In order to avoid stale reads, subscribed nodes then immediately sync or clean their local L1 memory.

Which NCache editions support HybridCache?

HybridCache integration is supported in NCache OpenSource edition, starting from version 5.3.6 onwards.

HybridCache in ASP.NET Core

ASP.NET Core 9.0 introduced HybridCache to provide a unified, multi-tier caching strategy. It combines the speed of an In-Process (L1) cache with the consistency and shared nature of a Distributed (L2) cache like NCache.

Note

This feature is currently supported in the NCache OpenSource edition.

Important

HybridCache is supported in NCache 5.3.6.2 and onwards.

When integrating NCache with the Microsoft HybridCache framework, you can employ two distinct architectural models depending on your performance and feature requirements:

NCache as an L2 Cache with Standard Microsoft HybridCache: Use Microsoft's built-in HybridCache implementation while configuring NCache as the distributed Layer 2 (L2) cache through the IDistributedCache interface. In this model, Microsoft HybridCache manages the local Layer 1 (L1) cache and all HybridCache operations, including cache population, stampede protection, serialization, and expiration handling.
NCache as a HybridCache Provider: Replace the default Microsoft HybridCache implementation with NCache's native HybridCache provider (AddNCacheHybridCache). In this model, NCache manages both local (L1) and distributed (L2) cache tiers directly through native NCache APIs and provides additional capabilities such as real-time Pub/Sub-based cache synchronization, logical tag invalidation, and cluster-wide cache consistency. ## Key Features

The key features of HybridCache are as follows:

Multi-Tiering: Data is stored in both L1 (per-instance) and L2 (shared cluster).
Stampede Prevention: Uses a semaphore-based "double-check" technique to guarantee that, in the event of a cache miss, only one request retrieves data from the database while others wait for the result.
Logical Invalidation (Tags): Allows you to group items with "tags." All related objects are considered stale when a tag is invalidated, even if they haven't officially expired yet.

How HybridCache Works with NCache

Depending on your chosen integration mode, NCache optimizes the lifecycle, synchronization, and retrieval of cache entries across your application as discussed below:

Standard Microsoft Implementation (IDistributedCache)

In this approach, the Microsoft framework handles the local L1 cache lifecycle and coordinates with NCache solely as an L2 layer using the IDistributedCache interface. Cache stampede protection and serialization follow standard Microsoft defaults, making it ideal for applications that already use Microsoft's caching interfaces instead of cache-specific APIs.

Native NCache HybridCache Provider

Initialization Flow
During application startup, the AddNCacheHybridCache binds configuration and registers the provider as a singleton. The provider connects to both cache tiers, initializes the TagKeeper (an internal component responsible for maintaining tags invalidation timestamps) for invalidation tracking, and subscribes to an NCache Pub/Sub topic to listen for cluster-wide updates.

Data Retrieval Logic

Validation and Bypass: NCache first validates the key and checks the HybridCacheEntryFlags. If the key is null/empty, or if both cache tiers are disabled via flags, the cache is bypassed to invoke the factory directly. If DisableUnderlyingData is set, default(T) is returned instead of invoking the factory.
Tiered Check: NCache checks L1 first, then L2.
Tag Invalidation: When an item is found in either cache tier, its associated tags are checked for invalidation against the item's creation time. If any tag associated with the item was invalidated and the item was created before this tag invalidation, the item is treated as stale and considered a cache miss. Otherwise, if no tags are invalidated or the item was created after all the invalidated tags, it is treated as fresh and returned as a cache hit.
Stampede Prevention: If the item is missing or invalidated in both cache tiers, the factory method is invoked to retrieve fresh data. In this case, a stampede protection mechanism is implemented where a Semaphore Lock is obtained against the requested key. This ensures that only one request fetches data and populates the L1 and L2 caches (based on the request flags). Concurrent requests wait for the operation to complete and then receive the cached result.

Cache Updates and Synchronization
Any changes made to the data are stored in the L2 Distributed Cache and L1 In-Memory Cache. Simultaneously, a notification is broadcast via Pub/Sub to all other nodes so they synchronize their L1 cache from L2 accordingly (if they have the same key).

Logical Tag Invalidation
NCache HybridCache uses Logical Deletion in case of Tags, i.e., data is not deleted, only tag(s) are marked as invalid and tag invalidation timestamps are updated in the L2 cache. This information is stored in L2 and a notification is broadcast via Pub/Sub to all other nodes so they synchronize the tag invalidation from L2. This ensures if a tag is marked invalid, any cache item associated with that tag is treated as stale across all nodes, ensuring cluster-wide consistency.

In This Section

NCache as an L2 Cache with Standard Microsoft HybridCache
Learn how to configure the native Microsoft HybridCache framework while utilizing NCache as the distributed IDistributedCache backing tier.

NCache as HybridCache Provider
Learn how NCache integrates as a HybridCache provider, enabling a two-tier caching architecture with in-memory (L1) and distributed (L2) layer.