NCache as FusionCache Backplane Provider

The NCache Backplane integration for FusionCache enables cache synchronization across multiple application nodes by using NCache as the messaging layer. In a distributed application, each application instance maintains its own local in-memory Layer 1 (L1) cache. While this provides fast access, it can also cause stale data if one node updates or removes an entry and other nodes continue serving the older value from their local memory.

Note

This feature is currently supported in the NCache OpenSource edition.

Important

FusionCache is supported in NCache 5.3.6.2 and onwards.

When NCache is configured as a FusionCache Backplane provider, FusionCache publishes cache change notifications through NCache. Other application nodes receive these notifications and update, remove, expire, or invalidate their local L1 cache entries accordingly.

Note

The FusionCache Backplane does not store cached data. It only transports cache synchronization notifications between application nodes. Cached data is stored in FusionCache L1 and, if configured, in the distributed L2 cache.

In most multi-node FusionCache deployments, NCache should be configured both as the distributed L2 cache and as the Backplane provider. The L2 cache stores cached data through IDistributedCache, while the Backplane publishes synchronization notifications across application nodes. This combination helps avoid unnecessary database calls when a Backplane notification is received and FusionCache needs to check the distributed cache state.

How NCache Works as a FusionCache Backplane

The NCache Backplane operates as a Pub/Sub-based synchronization layer. Each application node connects to NCache and subscribes to the Backplane channel used by FusionCache. When a cache-changing operation occurs on one node, FusionCache publishes a notification through NCache. Other subscribed nodes receive the notification and apply the corresponding change to their local L1 cache.

This is different from using NCache only as an L2 cache. When NCache is used only as IDistributedCache, cached values are shared through the L2 cache, but local L1 entries on other nodes are not immediately synchronized. The Backplane adds this synchronization layer by broadcasting cache change notifications across the application nodes.

For a complete multi-node FusionCache setup, configure NCache as both the distributed L2 cache and the Backplane provider. The distributed L2 cache stores the cached values, while the Backplane keeps the local L1 cache entries synchronized across application nodes.

Prerequisites

Before configuring NCache as the FusionCache Backplane provider, ensure that the following prerequisites are fulfilled:

  • Install the following NuGet packages in your application:
    • NCache L2 Provider: NCache.Microsoft.Extensions.Caching.OpenSource
    • NCache Backplane Provider: NCache.OSS.ZiggyCreatures.FusionCache.Backplane
    • FusionCache: ZiggyCreatures.FusionCache
    • Serializer: ZiggyCreatures.FusionCache.Serialization.SystemTextJson
  • To use NCache as both the FusionCache distributed L2 cache and Backplane provider, include the following namespaces in Program.cs:
    • Alachisoft.NCache.Caching.Distributed;
    • Microsoft.Extensions.Options;
    • NCache.ZiggyCreatures.FusionCache.Backplane;
    • ZiggyCreatures.Caching.Fusion;
    • ZiggyCreatures.Caching.Fusion.Serialization.SystemTextJson;
  • You must have L1, L2, and Backplane cache connectivity available:
    • L1 cache: FusionCache’s in-process memory cache inside each application instance.
    • L2 cache: NCache distributed cache used to store cached data through IDistributedCache.
    • Backplane cache: NCache cache used for Backplane communication.
  • Each application node that participates in FusionCache synchronization must be able to connect to the same NCache cache.
  • The data being added to cache must be serializable when FusionCache is configured with a distributed cache.

Method 1: Explicit Configuration

In this approach, you provide NCache Backplane settings directly in code using NCacheBackplaneOptions. This is useful when you want to define server connectivity, retry behavior, timeout values, client binding, logging, or application name inside the application.

var backplaneOptions = new NCacheBackplaneOptions
{
    ServerList = new List<FusionCacheServerInfo>
    {
        new FusionCacheServerInfo("10.0.0.1")
    },
    ClientBindIP = "10.0.0.2",
    LoadBalance = true,
    ConnectionTimeout = TimeSpan.FromSeconds(5),
    ConnectionRetries = 3,
    RetryInterval = TimeSpan.FromSeconds(2),
    AppName = "FusionCache-App"
};

Then configure FusionCache to use NCache as both the distributed L2 cache and the Backplane provider.

var cacheName = "fusionCache";

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

var distributedCacheOptions = Options.Create(distributedCacheConfig);

builder.Services
    .AddFusionCache()
    .WithOptions(options =>
    {
        options.BackplaneChannelPrefix = "my-app";
        options.BackplaneCircuitBreakerDuration = TimeSpan.FromSeconds(30);
    })
    .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,
        ReThrowBackplaneExceptions = false,
        AllowBackgroundBackplaneOperations = true
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(new NCacheDistributedCache(distributedCacheOptions))
    .WithBackplane(
        new NCacheBackplane(
            cacheName: cacheName,
            options: backplaneOptions));

In this configuration, NCacheDistributedCache is used as FusionCache’s distributed L2 cache, while NCacheBackplane is used to publish synchronization notifications across application nodes.

Method 2: Using Default NCache Backplane Configuration

If explicit Backplane options are not provided, the NCache Backplane provider can use the default NCache client configuration, such as client.ncconf. Use this approach when NCache client connectivity is already configured outside the application code.

var cacheName = "fusionCache";

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

var distributedCacheOptions = Options.Create(distributedCacheConfig);

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,
        ReThrowBackplaneExceptions = false,
        AllowBackgroundBackplaneOperations = true
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(new NCacheDistributedCache(distributedCacheOptions))
    .WithBackplane(
        new NCacheBackplane(cacheName: cacheName));

In this configuration, FusionCache uses NCache as the distributed L2 cache and also uses the default NCache client configuration for Backplane connectivity.

Note

The Backplane does not store cached data. It only transports synchronization notifications between FusionCache instances. For a complete multi-node FusionCache setup, configure NCache as the distributed L2 cache along with the Backplane provider.

Configure NCacheBackplaneOptions

The following properties can be configured in NCacheBackplaneOptions.

Property Description
ServerList Defines the list of NCache server nodes used by the Backplane provider.
ClientBindIP Forces the client to bind to a specific local IP address.
ConnectionTimeout Specifies the client connection timeout. Default value is 5 seconds.
ConnectionRetries Specifies the number of retries used to re-establish a broken connection. Default value is 3 retries.
RetryInterval Specifies the time to wait between two connection retries. Default value is 1 second.
RetryConnectionDelay Specifies the delay after which the client tries to reconnect to the server. Default value is 10 minutes.
AppName Defines a unique identifier for the NCache client application.
LogLevel Sets the logging level, such as Info, Error, or Debug.
EnableClientLogs Enables or disables NCache client logs.

Configure FusionCache Backplane Options

FusionCache also provides global Backplane options that control how Backplane notifications are handled.

builder.Services
    .AddFusionCache()
    .WithOptions(options =>
    {
        options.BackplaneChannelPrefix = "my-app";
        options.IgnoreIncomingBackplaneNotifications = false;
        options.EnableAutoRecovery = true;
        options.BackplaneCircuitBreakerDuration = TimeSpan.FromSeconds(30);
        options.ReThrowBackplaneExceptions = false;
        options.AllowBackgroundBackplaneOperations = true;
    });

Configuration Option

Option Description
BackplaneChannelPrefix Defines a unique channel or topic prefix for Backplane communication.
IgnoreIncomingBackplaneNotifications Determines whether incoming Backplane notifications should be ignored.
EnableAutoRecovery Enables automatic recovery after transient Backplane failures or disconnections.
BackplaneCircuitBreakerDuration Specifies how long FusionCache should pause Backplane operations after errors.
ReThrowBackplaneExceptions Controls whether Backplane exceptions should propagate to the application.
AllowBackgroundBackplaneOperations Allows Backplane notifications to execute asynchronously in the background.

Skip Backplane Notifications for Specific Operations

FusionCache also allows skipping Backplane notifications for a specific operation. This is useful when a cache change should remain local to the current node or when you do not want to notify other application nodes for a particular operation.

await cache.SetAsync(
    "product:1001",
    product,
    options => options.SetSkipBackplaneNotifications(true));

Logging

NCache Backplane logging can be controlled through the Backplane options and NCache client logging settings. Use logging when you need to troubleshoot connection issues, publish/subscribe failures, or unexpected synchronization behavior.

var backplaneOptions = new NCacheBackplaneOptions
{
    AppName = "FusionCache-App",
    LogLevel = LogLevel.Info,
    EnableClientLogs = true
};

Use detailed logging carefully in production because verbose logs can add overhead and increase log volume.

See Also

FusionCache with NCache
NCache as FusionCache Provider