Configure ASP.NET Core IDistributedCache

You can also use ASP.NET Core Sessions with NCache's IDistributedCache Provider. ASP.NET Core provides the AddDistributedMemoryCache method to add a default implementation of a IDistributedCache. However, to utilize NCache as a distributed cache to store ASP.NET Sessions or objects, NCache provides its own extension method, AddNCacheDistributedCache, which adds NCache as the default distributed cache as an implementation of IDistributedCache.

Prerequisites to Configure ASP.NET Core IDistributedCache

.NET

Install the following NuGet packages in your application based on your NCache edition:
- Enterprise: NCache.Microsoft.Extensions.Caching
- Professional: NCache.Microsoft.Extensions.Caching.Professional
- OpenSource: NCache.Microsoft.Extensions.Caching.OpenSource
To utilize the extension, include the following namespaces in your application in Startup.cs:
- Alachisoft.NCache.Caching.Distributed;
The cache must be running.
For API details, refer to: AddNCacheDistributedCache, AddNCacheDistributedCacheProvider.
Make sure that the data being added is serializable.
To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Step 1: Configure Services

NCache provides the AddNCacheDistributedCache extension method on IServiceCollection, which requires just a cache name in NCache and any optional configurations to store the sessions. The configuration object is the same as NCache ASP.NET Core Session Provider, which can be initialized similarly. The configuration can be provided through the IOptions initializer as well.

There are two methods to specify configurations:

Through your application in Startup.cs.
In JSON format in Appsettings.json of your application.

Method 1: Specifying Configurations in Startup.cs

In this approach, you configure your NCache settings directly in the Startup.cs file of your ASP.NET Core application. You can define a single cache or multiple caches as needed.

Configure Startup.cs for Single Cache:

The AddNCacheDistributedCache method is an extension of the AddDistributedCache method provided by ASP.NET Core. This method takes configuration settings in Startup.cs of your application, or reads them from the specified JSON file.

Add the following method and options in Startup.cs of your application:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services
    services.AddMvc();

    services.AddNCacheDistributedCache(configuration =>
    {
        configuration.CacheName = "demoCache";
        configuration.EnableLogs = true;
        configuration.ExceptionsEnabled = true;
    });
}

Configure Startup.cs for Multiple Caches:

Note

This feature is available in NCache Enterprise only.

The AddNCacheDistributedCacheProvider is an extension of the AddDistributedCache method provided by ASP.NET Core. This method takes configuration settings in the Startup.cs of your application. You can configure multiple caches using the AddNCacheDistributedCacheProvider method as follows:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services
    services.AddMvc();
    services.AddNCacheDistributedCacheProvider( options =>
             {
                options.CacheConfigurations = new NCacheConfiguration[] {
                new NCacheConfiguration() {
                    CacheName = "demoClusteredCache",
                    EnableLogs = true,
                    ExceptionsEnabled = true
                },
                new NCacheConfiguration(){
                    CacheName = "demoCache",
                    EnableLogs = true,
                    ExceptionsEnabled = true }
                };
             });
}

Method 2: Specifying Configurations In Appsettings.json

You can also specify the configurations within your application in JSON format in Appsettings.json of your application. Using this method, you can refer to the configurations by providing the name of the section containing JSON format configurations in Startup.cs.

Configure Appsettings.json for Single Cache:

Configure the Appsettings.json file of your application to configure a single cache as follows:

{
  "AppSettings": {
    "SiteTitle": "ASP.NET MVC Music Store",
    "CacheDbResults": true,
  },

  "NCacheSettings": {
    "CacheName": "demoCache",
    "EnableLogs": "True",
    "RequestTimeout": "90"
  },
}

Refer these configurations in the Startup.cs as follows:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services
    services.AddMvc();

    // Add services to the container
    services.AddNCacheDistributedCache(Configuration.GetSection("NCacheSettings")); 

    services.AddSession();
}

Configure Appsettings.json for Multiple Caches:

Configure the Appsettings.json file of your application to configure multiple caches as follows:

"NCacheFactorySettings": {
    "NCacheConfigurations": [
        {
            "CacheName": "demoClusteredCache",
            "EnableLogs": true,
            "RequestTimeout": "90"
        },
        {
            "CacheName": "demoCache",
            "EnableLogs": true,
            "RequestTimeout": "90"
        },
        {
            // Configure more caches
        }
    ]
}

Use the AddNCacheDistributedCacheProvider method to refer to the NCacheFactorySettings section in Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services
    services.AddMvc();

    // Add services to the container
    services.AddNCacheDistributedCacheProvider(_config.GetSection("NCacheFactorySettings")); 

    services.AddSession();
}

Step 2: Add Middleware to the Application

Once the distributed cache has been added to the service, sessions can store the data in NCache. The UseSession extension method provided by ASP.NET Core will add the default session middleware to the application but will utilize NCache as its cache.

You can now proceed to use NCache as the underlying cache for your ASP.NET Core Sessions.

Configuration Properties

Configurations specific to distributed caching are explained below:

Member	Type	Description	Default Value
`CacheName`	string (required)	Specifies the name of the cache to be used for the caching session. If no cache name is specified, a configuration exception will be thrown.	-
`EnableLogs`	bool (optional)	If this flag is set, NCache logs all the error information. The log files are created in `%NCHOME%\log-files\SessionState` (Windows) or `/opt/ncache/log-files/SessionState` (Linux).	`false`
`EnableDetailLogs`	bool (optional)	When this flag is set, NCache logs all the debugging information. The log files are created in `%NCHOME%\log-files\SessionState` (Windows) or `/opt/ncache/log-files/SessionState` (Linux).	`false`
`ExceptionsEnabled`	bool (optional)	Specifies whether exceptions from cache API are propagated to the page output. Setting this flag is especially helpful during the development phase of the application since exceptions provide more information about the specific causes of failure.	`false`
`WriteExceptionsToEventLog`	bool (optional)	If this flag is set, all the exceptions from cache API are written to event logs.	false
`RequestTimeout`	int (required)	Specifies the timeout for client requests in seconds.	90
`OperationsRetry`	int (optional)	Specifies the number of times a server retries an operation, in case the connection is lost while executing an operation.	0
`OperationRetryInterval`	int (optional)	Specifies the time interval between each operation retry.	0

Refer to the CacheConnectionOptions API Documentation for more detail on the properties of this class.