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.

Important

HybridCache is supported in NCache 5.3.800 and onwards in NCache and 5.3.6.2 and onwards in NCache Open Source.

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

  1. 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.

  2. NCache as a HybridCache Provider: Replace the default Microsoft HybridCache implementation with NCache's native provider using AddNCacheHybridCache. In the NCache edition, the provider uses an NCache client cache for local L1 storage and its associated distributed cache for L2, with synchronization handled by NCache. In the NCache Open Source edition, the provider uses separately configured local and distributed caches, with a Pub/Sub backplane for synchronization and logical tag invalidation.

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 Protection: Coordinates requests for the same missing key within an application instance to reduce duplicate factory calls. Separate application instances can still load the same key at the same time.

  • Tag-Based Operations: Tags group related entries. Microsoft's implementation and the NCache Open Source provider use logical invalidation, while the NCache provider physically removes matching entries.

  • Cache Synchronization: The native NCache providers coordinate changes between application instances. The NCache edition uses NCache client-cache synchronization, while the NCache Open Source uses a provider-managed Pub/Sub backplane.

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: NCache

The NCache edition provider uses an NCache client cache as L1 and its associated distributed cache as L2. Both levels are accessed through the same NCache connection; the provider does not create a separate Microsoft MemoryCache.

Data Retrieval

For a normal GetOrCreateAsync request:

  • NCache checks the local client cache first.

  • On a local miss, NCache checks the distributed cache. If the entry is found, NCache returns it and populates the client cache as appropriate.

  • If neither level contains the entry, the provider invokes the supplied factory and stores the result through the same NCache connection.

The provider coordinates concurrent cache misses for the same key within an application process to reduce duplicate factory calls. Separate application instances can still invoke their factories for the same key.

Cache Updates and Synchronization

NCache handles writes, updates, removals, and synchronization with connected client caches. The application does not need to implement a separate invalidation channel for this integration.

The timing and consistency of changes follow the configured NCache client-cache synchronization mode. Changes should not be assumed to become visible immediately in every application instance.

Expiration

The NCache provider applies one entry lifetime through the shared NCache connection. It does not support separate local and distributed entry expiration settings.

Tag-Based Removal

The NCache provider uses native NCache tag removal to physically delete matching entries. NCache synchronizes these removals with connected client caches according to their configured synchronization mode.

Native NCache HybridCache Provider: NCache Open Source

Initialization Flow

During application startup, AddNCacheHybridCache binds configuration and registers the provider as a singleton. The provider connects to the separately configured local L1 and distributed L2 caches, initializes tag invalidation tracking, and subscribes to an internal NCache Pub/Sub topic for synchronization notifications.

Data Retrieval Logic

  • Validation and Bypass: The provider validates the key and checks HybridCacheEntryFlags. If the key is null or empty, or both cache tiers are disabled, it bypasses the cache and invokes the factory. If DisableUnderlyingData is set, it returns default(T) instead of invoking the factory.

  • Tiered Check: The provider checks L1 first, followed by L2.

  • Tag Invalidation: When an entry is found in either tier, its creation time is compared with its associated tags' invalidation timestamps. If an associated tag was invalidated after the entry was created, the entry is treated as stale and considered a cache miss. Otherwise, it is returned as a cache hit.

  • Stampede Protection: If no fresh entry is available, the provider obtains a per-key semaphore within the application process. One request invokes the factory and populates the enabled cache tiers, while concurrent requests wait and then retrieve the cached result.

Cache Updates and Synchronization

When data is added or updated, the provider stores it in the enabled cache tiers and publishes a Pub/Sub notification so other application instances can synchronize their existing L1 copies from L2. When an entry is removed, the provider removes it from L2 and notifies other instances so they can remove their corresponding local copies.

Logical Tag Invalidation

The NCache Open Source provider uses logical tag invalidation. Instead of deleting associated entries, it records tag invalidation timestamps in L2 and publishes a Pub/Sub notification so other application instances can synchronize their invalidation information.

On subsequent reads, entries created before an associated tag's invalidation timestamp are treated as stale, allowing the factory to retrieve fresh data.

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 to configure and use the native NCache HybridCache provider for the NCache and NCache Open Source editions.