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.

Note

This feature is currently supported in the NCache OpenSource edition.

Important

HybridCache is supported in NCache 5.3.6.2 and onwards.

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.

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 package 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
  • You must have two caches running, i.e., L1 and L2 cache.
  • 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": "demoCache",
    "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 = "demoCache";
    options.EnableLogs = true;
    options.ExceptionsEnabled = true;
});

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

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

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 interacts with the HybridCache instance initialized via this standard approach, data operations follow a rigid tier-by-tier flow:

  • On Cache Miss: The framework checks local L1 memory. If it misses, it uses the IDistributedCache API interface to query NCache (L2). If both tiers fail, the database factory method is safely executed with built-in semaphore-based stampede protection.

  • On Cache Updates: Any explicit update via SetAsync or removal via RemoveAsync triggers an instant, synchronous command through the IDistributedCache channel directly to the remote NCache L2 cluster.

See Also

ASP.NET Core Caching
IDistributedCache