NCache as CacheManager.Core Provider

The NCache CacheManager.Core integration allows CacheManager.Core applications to use NCache as a distributed cache handle and as a backplane for cache invalidation. The integration provides NCacheCacheHandle<T> for cache operations and NCacheCacheBackplane for cache change notifications across application instances.

NCache configuration is registered under a configuration key in NCacheConfigurations. The NCache cache handle and backplane then reference the same configuration key when they are added to CacheManager.Core.

Important

For the NCache OpenSource edition, CacheManager.Core integration is supported in NCache OSS 5.3.6.2 and later.

Prerequisites

Before configuring NCache with CacheManager.Core, make sure the following prerequisites are fulfilled:

  • Install the following NuGet package in your .NET application:
  • Include the following namespaces in your application:
    • CacheManager.Core
    • Enterprise: NCache.CacheManager.Core
    • OpenSource: NCache.OSS.CacheManager.Core
    • Microsoft.Extensions.DependencyInjection
    • Microsoft.Extensions.Logging
  • The NCache cache must already exist and must be running.
  • Configure ServerList when the application connects to a remote or distributed NCache deployment.
  • Make sure that the data being added to the cache is serializable.

Configure NCache with CacheManager.Core

NCacheCacheHandle<T> and NCacheCacheBackplane resolve their NCacheOptions from NCacheConfigurations by using a configuration key. NCache configuration can be registered using any of the following approaches:

  1. Fluent configuration using WithNCacheConfiguration(...).
  2. IServiceCollection configuration using AddNCacheConfiguration(...).
  3. Direct registration using NCacheConfigurations.AddConfiguration(...).

Regardless of the configuration approach, the cache handle and backplane must reference the same registered configuration key.

Method 1: Using Fluent Configuration

Use WithNCacheConfiguration(...) to register the NCache configuration directly while building the CacheManager.Core instance. Add the following code to your Program.cs file:

var manager = CacheFactory.Build<int>(settings =>
{
    settings
        .WithSystemRuntimeCacheHandle()
        .And
        .WithNCacheConfiguration("ncache", config =>
        {
            config.WithCacheName("demoCache")
                .WithEndpoint("20.200.20.11", 9800);
        })
        .WithMaxRetries(100)
        .WithRetryTimeout(50)
        .WithNCacheBackplane("ncache", "topic_name")
        .WithNCacheCacheHandle("ncache", true);
});

manager.Add("test", 123456);

In this configuration:

  • WithNCacheConfiguration(...) registers the NCache configuration under the ncache configuration key.
  • WithCacheName(...) specifies the NCache cache to connect to.
  • WithEndpoint(...) specifies the NCache server endpoint.
  • WithNCacheBackplane(...) configures the NCache backplane by using the registered ncache configuration.
  • WithNCacheCacheHandle(...) adds the NCache cache handle by using the same configuration key.

An existing NCacheOptions instance can also be registered instead of using the builder action:

settings.WithNCacheConfiguration("ncache", new NCacheOptions
{
    CacheName = "demoCache",
    ServerList = new List<NCacheOptions.ServerConfig>
    {
        new NCacheOptions.ServerConfig { Ip = "20.200.20.11" }
    }
});

Method 2: Using IServiceCollection

Use AddNCacheConfiguration(...) to register NCache configuration through IServiceCollection. The configuration can be supplied through an action delegate:

services.AddNCacheConfiguration("ncache", opt =>
{
    opt.CacheName = "demoCache";
    opt.ServerList.Add(new NCacheOptions.ServerConfig { Ip = "20.200.20.11" });
});

The configuration can also be bound from an IConfigurationSection. For example, the NCache configuration in appsettings.json can be defined as follows:

{
  "ncache": {
    "cacheName": "demoCache",
    "serverList": [
      {
        "ip": "20.200.20.11",
        "port": 9800
      }
    ]
  }
}

Register the configuration section using the same configuration key:

services.AddNCacheConfiguration("ncache", configuration.GetSection("ncache"));

Registering NCacheOptions does not by itself build the cache. Add the NCache cache handle and backplane using the same configuration key:

var provider = services.BuildServiceProvider();
var loggerFactory = provider.GetRequiredService<ILoggerFactory>();

var cache = CacheFactory.Build<object>(settings =>
{
    settings
        .WithDictionaryHandle()
        .And
        .WithNCacheBackplane("ncache", "topic_name")
        .WithNCacheCacheHandle("ncache", true);
},
loggerFactory);
Note

IServiceCollection configuration requires Microsoft.Extensions.DependencyInjection.Abstractions. The IConfigurationSection overload requires Microsoft.Extensions.Configuration.Binder. Loading configuration from a JSON file additionally requires Microsoft.Extensions.Configuration.Json.

Method 3: Using Direct Registration

Use NCacheConfigurations.AddConfiguration(...) to register an NCacheOptions instance directly in NCacheConfigurations. Add the following code to your Program.cs file:

var services = new ServiceCollection();

services.AddLogging(cfg =>
{
    cfg.AddConsole();
    cfg.SetMinimumLevel(LogLevel.Information);
});

var provider = services.BuildServiceProvider();
var loggerFactory = provider.GetRequiredService<ILoggerFactory>();

var options = new NCacheOptions
{
    CacheName = "demoCache",
    ServerList = new List<NCacheOptions.ServerConfig>
    {
        new NCacheOptions.ServerConfig
        {
            Ip = "20.200.20.11",
        }
    }
};

NCacheConfigurations.AddConfiguration("config_key", options);

var cache = CacheFactory.Build<string>("myCache", settings =>
{

    settings.WithDictionaryHandle();

    settings.WithHandle(
        typeof(NCacheCacheHandle<>),
        "config_key",
        true);

    settings.WithBackplane(
        typeof(NCacheCacheBackplane),
        "config_key",
        "topic_name");

},
loggerFactory);

In this configuration:

  • NCacheConfigurations.AddConfiguration(...) registers the NCacheOptions instance under config_key.
  • WithHandle(...) adds NCacheCacheHandle<T> by referencing the registered configuration key.
  • WithBackplane(...) adds NCacheCacheBackplane by referencing the same configuration key.
Note

The configuration key used by the cache handle and backplane must already be registered in NCacheConfigurations. NCacheOptions is no longer passed directly to WithHandle(...) or WithBackplane(...).

Configuration Properties

The following configuration properties are available in the NCacheOptions class.

Property Description
CacheName* Specifies the name of the NCache cache instance. The cache must already exist and must be running. This property is required for initialization.
ServerList Specifies the list of NCache server nodes used for cache connectivity. Each entry contains an IP address and port. If the port is not specified, the default NCache client port 9800 is used.
Note

The properties marked with an asterisk (*) are required.

ServerConfig Properties

Each ServerList entry uses the NCacheOptions.ServerConfig class.

Property Description
Ip* Specifies the IP address of the NCache server node. The value must be a valid IPv4 or IPv6 address.
Port Specifies the NCache client port. The value must be between 1 and 65535. The default value is 9800.
Note

The properties marked with an asterisk (*) are required.

Note

NCacheOptions is validated when it is registered. Invalid options cause registration to fail. If a cache handle or backplane references a configuration key that has not been registered, cache construction fails with InvalidOperationException.

See Also

CacheManager.Core with NCache
CacheManager.Core API Usage