NCache as an L2 Cache with Standard Microsoft HybridCache

This page covers the simplest way to use NCache with HybridCache: registering NCache as an IDistributedCache provider and using Microsoft's standard Microsoft.Extensions.Caching.Hybrid implementation. In this architecture, HybridCache manages its built-in MemoryCache as the local Layer 1 (L1) cache, while NCache acts as the shared Layer 2 (L2) distributed cache through the IDistributedCache interface. No custom NCache HybridCache provider is required.

Important

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

Under this model, the data access pathway works through an intermediary layer:

  • HybridCache communicates strictly via the generic IDistributedCache interface.
  • IDistributedCache targets the underlying NCache API framework, handling the CRUD operations behind the scenes to treat the remote NCache cluster as a shared Layer 2 (L2) backing store.
  • Microsoft's framework handles Layer 1 (L1) data access natively, managing its own internal local in-process dictionary (MemoryCache).

This standard configuration does not support real-time Pub/Sub-based synchronization. Because it relies entirely on standard IDistributedCache abstractions, there is no background backplane broadcasting invalidations between application instances. When Node A updates or removes a key via SetAsync or RemoveAsync, the change is immediately written out to the shared NCache L2 cluster. However, Node B remains unaware of this change and will continue serving its local L1 in-process value until that item's LocalCacheExpiration period naturally expires.

Note

The NCache native provider requires an NCache client cache. This requirement does not apply when using Microsoft's HybridCache implementation as described on this page. For the native provider, see NCache as HybridCache Provider.

There are two ways to configure NCache as an L2 Cache with Standard Microsoft HybridCache in ASP.NET Core depending on your environment and deployment needs:

  • Using appsettings.json (Recommended for Production)
  • Using an Action Delegate in Program.cs

Prerequisites

Before using the HybridCache with NCache, ensure that the following prerequisites are fulfilled:

  • Install the following NuGet packages in your application:
  • To utilize the HybridCache provider, include the following namespaces in Program.cs:
    • Alachisoft.NCache.Caching.Distributed
    • Microsoft.Extensions.Caching.Hybrid
    • Microsoft.Extensions.Caching.Distributed
  • Create and start the distributed NCache cache that will provide L2 storage, and configure the application to connect to it. Microsoft HybridCache creates and manages its own L1 cache, so a separate NCache local cache is not required.
  • Make sure that the data being added is serializable.

Method 1: Specifying Configurations In appsettings.json

This is the recommended approach to manage your cache settings as it allows configuration changes without needing to recompile the application. First, define the configuration section in appsettings.json of your project.

{
  "NCacheSettings": {
    "CacheName": "defaultCache",
    "EnableLogs": true,
    "ExceptionsEnabled": true
  },
  "AllowedHosts": "*"
}

Then, in your Program.cs, register the service:

var builder = WebApplication.CreateBuilder(args);

// 1. Register NCache OSS as IDistributedCache, reading from config section
builder.Services.AddNCacheDistributedCache(
    builder.Configuration.GetSection("NCacheSettings")
);

// 2. Register Microsoft's HybridCache — it automatically picks up the
//    IDistributedCache registered above as its L2 backing store
builder.Services.AddHybridCache();

var app = builder.Build();
app.Run();

First, the NCacheSettings section from appsettings.json is retrieved using builder.Configuration.GetSection("NCacheSettings") and passed to AddNCacheDistributedCache(), which registers NCache as the application's IDistributedCache implementation. Then AddHybridCache() registers Microsoft's HybridCache, which automatically uses the registered IDistributedCache implementation (NCache) as its L2 cache.

Method 2: Configuring HybridCache in Program.cs

If your deployment scenario does not require dynamic configuration modifications via external files, you can declare your cluster properties directly inside the C# code using an inline action delegate. To use NCache as your backing L2 distributed layer within the standard HybridCache ecosystem, you must register the NCache distributed cache provider before invoking the HybridCache services. This ordering ensures that when AddHybridCache() evaluates application dependencies, it automatically detects and binds your custom NCache IDistributedCache service as its L2 backing engine.

var builder = WebApplication.CreateBuilder(args);

// 1. Register NCache OSS as IDistributedCache
builder.Services.AddNCacheDistributedCache(options =>
{
    options.CacheName = "defaultCache";
    options.EnableLogs = true;
    options.ExceptionsEnabled = true;
});

// 2. Register Microsoft's HybridCache
builder.Services.AddHybridCache();

var app = builder.Build();
app.Run();
Important

Choose one HybridCache implementation during application startup. Use AddHybridCache for Microsoft's implementation or AddNCacheHybridCache for the native NCache provider. The native NCache provider connects to NCache directly and does not use a registered IDistributedCache.

To learn more about standard HybridCache API usage patterns, including entry options, behavior flags, and tag invalidations, refer to Microsoft's HybridCache Documentation.

Note

To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

When your application uses Microsoft's HybridCache implementation:

  • Reading data: HybridCache checks L1 first, then NCache L2. If the entry is missing from both, it calls the supplied factory to load the data and caches the result. Requests for the same key share this work within the same HybridCache instance, but not across application instances.

  • Updating or removing data: SetAsync updates the entry, while RemoveAsync removes it from the calling application's L1 cache and the shared L2 cache. Other application instances can keep serving their existing L1 copies until those copies expire.

  • Expiration: Expiration controls how long an entry stays in L2. LocalCacheExpiration controls how long its L1 copy stays in application memory.

  • Tags: RemoveByTagAsync marks matching entries as invalid. It does not physically delete their stored values.

For entry options, flags, serialization, and tag invalidation behavior, refer to Microsoft's HybridCache documentation.

See Also

ASP.NET Core Caching
IDistributedCache