NCache as an L2 Cache with FusionCache

This page covers the simplest way to use NCache with FusionCache: registering NCache as an IDistributedCache provider and using it as FusionCache’s distributed Layer 2 (L2) cache. In this architecture, FusionCache manages its local in-memory Layer 1 (L1) cache inside the application process, while NCache acts as the shared L2 distributed cache through the IDistributedCache interface.

Note

This feature is currently supported in the NCache OpenSource edition.

Important

FusionCache is supported in NCache 5.3.6.2 and onwards.

Under this model, the data access pathway follows a layered caching flow. FusionCache first checks its local L1 cache for the requested entry. If the entry is not available locally, FusionCache queries the registered IDistributedCache implementation, which in this case is NCache. If the value is found in NCache, FusionCache returns it to the application and stores it again in L1 for faster future access. If the entry is not found in either L1 or L2, the application retrieves the data from the original data source, and FusionCache stores the result according to the configured cache options.

This configuration allows multiple application servers to share cached data through NCache as the distributed L2 cache. However, using NCache only as an IDistributedCache provider does not automatically synchronize the local L1 cache across application nodes. When one node updates or removes an entry through FusionCache, the corresponding operation is applied to NCache as the shared L2 cache according to the configured FusionCache options, but other nodes may continue serving their local L1 copy until that entry expires or is invalidated by FusionCache behavior. To synchronize L1 cache changes across nodes, configure NCache as a FusionCache Backplane provider.

There are two common ways to configure NCache as an L2 cache with FusionCache depending on your deployment requirements:

  • Using appsettings.json configuration, recommended for production environments.
  • Using an action delegate in Program.cs for programmatic configuration.

Prerequisites

Before configuring NCache as the FusionCache distributed L2 cache provider, ensure that the following prerequisites are fulfilled:

  • Install the following NuGet packages in your application:
    • NCache L2 Provider: NCache.Microsoft.Extensions.Caching.OpenSource
    • FusionCache: ZiggyCreatures.FusionCache
    • Serializer: ZiggyCreatures.FusionCache.Serialization.SystemTextJson
  • Include the following namespaces in Program.cs:
    • Alachisoft.NCache.Caching.Distributed;
    • Microsoft.Extensions.Options;
    • ZiggyCreatures.Caching.Fusion;
    • ZiggyCreatures.Caching.Fusion.Serialization.SystemTextJson;
  • You must have L1 and L2 caching available:
    • L1 cache: FusionCache’s in-process memory cache inside the application.
    • L2 cache: NCache distributed cache, which must be configured and running.
  • The data being added to cache must be serializable.

Method 1: Using appsettings.json

This is the recommended approach for production environments because it keeps cache settings outside the application code. You can update cache connection settings without recompiling the application.

First, define the NCache configuration section in the appsettings.json file.

{
  "NCacheSettings": {
    "CacheName": "demoCache",
    "EnableLogs": true,
    "ExceptionsEnabled": true,
    "ServerList": [
      {
        "Name": "20.200.20.39",
        "Port": 9800
      }
    ]
  }
}
Note

The cache name configured in the application must match the NCache cache name.

Then, register NCache as the IDistributedCache provider and configure FusionCache to use the registered distributed cache as its L2 cache.

var builder = WebApplication.CreateBuilder(args);

// Register NCache as IDistributedCache using appsettings.json.
builder.Services.AddNCacheDistributedCache(
    builder.Configuration.GetSection("NCacheSettings"));

// Register FusionCache and configure it to use NCache as L2 cache.
builder.Services
    .AddFusionCache()
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(5),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30),
        FactorySoftTimeout = TimeSpan.FromSeconds(2),
        FactoryHardTimeout = TimeSpan.FromSeconds(5),
        DistributedCacheSoftTimeout = TimeSpan.FromSeconds(2),
        DistributedCacheHardTimeout = TimeSpan.FromSeconds(5),
        AllowBackgroundDistributedCacheOperations = true,
        ReThrowDistributedCacheExceptions = false
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithRegisteredDistributedCache();

var app = builder.Build();

app.Run();

In this configuration, AddNCacheDistributedCache() registers NCache as the application’s IDistributedCache implementation. FusionCache then uses the registered IDistributedCache instance as its L2 cache through WithRegisteredDistributedCache(). A serializer is configured because FusionCache must serialize cache values before storing them in NCache as the distributed cache.

Method 2: Using an Action Delegate in Program.cs

This approach defines NCache settings directly in Program.cs. It is useful when you want to configure cache settings programmatically or when your deployment does not require configuration changes through external files.

Register NCache as the IDistributedCache provider before registering FusionCache. This allows FusionCache to use the registered NCache distributed cache as its L2 backing store.

var builder = WebApplication.CreateBuilder(args);

// Register NCache as IDistributedCache using programmatic configuration.
builder.Services.AddNCacheDistributedCache(options =>
{
    options.CacheName = "demoCache";
    options.EnableLogs = true;
    options.ExceptionsEnabled = true;
});

// Register FusionCache and configure it to use NCache as L2 cache.
builder.Services
    .AddFusionCache()
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(5),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30),
        FactorySoftTimeout = TimeSpan.FromSeconds(2),
        FactoryHardTimeout = TimeSpan.FromSeconds(5),
        DistributedCacheSoftTimeout = TimeSpan.FromSeconds(2),
        DistributedCacheHardTimeout = TimeSpan.FromSeconds(5),
        AllowBackgroundDistributedCacheOperations = true,
        ReThrowDistributedCacheExceptions = false
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithRegisteredDistributedCache();

var app = builder.Build();

app.Run();

Method 3: Injecting NCacheDistributedCache Directly

You can also create an NCacheDistributedCache instance directly and pass it to FusionCache through WithDistributedCache(). Use this approach when you want more direct control over the distributed cache instance, or when you need to test or configure FusionCache without relying on the IServiceCollection extension method.

using Alachisoft.NCache.Caching.Distributed;
using Microsoft.Extensions.Options;
using ZiggyCreatures.Caching.Fusion;
using ZiggyCreatures.Caching.Fusion.Serialization.SystemTextJson;

var builder = WebApplication.CreateBuilder(args);

var cacheName = "demoCache";

var config = new NCacheConfiguration
{
    CacheName = cacheName,
    EnableLogs = true,
    ExceptionsEnabled = true
};

var ncacheOptions = Options.Create(config);

// Register FusionCache and configure it to use NCache as L2 cache.
builder.Services
    .AddFusionCache()
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(5),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30),
        FactorySoftTimeout = TimeSpan.FromSeconds(2),
        FactoryHardTimeout = TimeSpan.FromSeconds(5),
        DistributedCacheSoftTimeout = TimeSpan.FromSeconds(2),
        DistributedCacheHardTimeout = TimeSpan.FromSeconds(5),
        AllowBackgroundDistributedCacheOperations = true,
        ReThrowDistributedCacheExceptions = false
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(new NCacheDistributedCache(ncacheOptions));

var app = builder.Build();

app.Run();

In this configuration, NCacheDistributedCache is created directly from NCacheConfiguration and passed to FusionCache as its distributed L2 cache. This avoids relying on a separately registered IDistributedCache service.

Configuration Properties

The following configuration properties are available for configuring NCache as the IDistributedCache provider used by FusionCache as its L2 distributed cache.

Property Description
CacheName Specifies the name of the NCache distributed cache. This cache must already exist and must be running before the application starts using it.
EnableLogs Enables NCache provider logs for diagnostic and troubleshooting purposes.
ExceptionsEnabled Specifies whether NCache exceptions are thrown to the application. When enabled, cache-related exceptions can be handled by the application code.
ServerList Specifies the list of NCache server nodes used by the client application to connect to the distributed cache. Each server entry includes the server IP/name and port.
Note

FusionCache entry options such as Duration, IsFailSafeEnabled, FactorySoftTimeout, FactoryHardTimeout, DistributedCacheSoftTimeout, and DistributedCacheHardTimeout control FusionCache behavior, not the NCache distributed cache provider configuration. These options can still be configured when registering FusionCache, but the NCache L2 provider itself is configured through the distributed cache settings shown above.

See Also

FusionCache with NCache
NCache as FusionCache Backplane Provider