Configure NCache ASP.NET Core Session Provider

Install NuGet Package

Important

For NCache Version 4.9 SP1 onwards, use ASP.NET Core version 2.1.

Install the NuGet package Alachisoft.NCache.SessionServices to your application by executing the following command in the Package Manager Console:

Install-Package Alachisoft.NCache.SessionServices

Include Namespaces

To utilize the APIs, include the following namespace in your application in Startup.cs:

using Alachisoft.NCache.Web.SessionState;

Using NCache Session Management Services with ASP.NET Core requires two steps:

Configuring the session management service
Adding middleware to the application

Step 1: Configure NCache Session Management Service

The session management service needs to be initialized in Startup.cs. There are two methods to specify configurations:

Through your application on IOptions or
In JSON format in Appsettings.json of your application.

Note

The configuration must always contain the cache name.

Method 1: Specifying Configurations in IOptions

The session can be initialized by the AddNCacheSession() extension method that takes an IOptions<NCacheSessionConfiguration> object as the configuration.

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

    //Add services to the container with configured session (SessionAppId = NcacheSessionApp) for cache "MyCache", with logging enabled and idle timeout set to 5
    services.AddNCacheSession(configuration =>
    {
        configuration.CacheName = "mySessionCache";
        configuration.EnableLogs = true;
        configuration.SessionAppId = "NCacheSessionApp";
        configuration.SessionOptions.IdleTimeout = 5;
        configuration.SessionOptions.CookieName = "AspNetCore.Session";
    });                   

}

Method 2: Specifying Configurations in Appsettings.json

The configurations for the services can also be provided in JSON format as a section in Appsettings.json of your ASP.NET application:

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

  "NCacheSessions": {
    "SessionAppId": null,
    "SessionOptions": {
      "CookieName": "AspNetCore.Session",
      "CookieDomain": null,
      "CookiePath": "/",
      "CookieHttpOnly": "True",
      "IdleTimeout": "5",
      "CookieSecure": "None"
    },
    "CacheName": "mySessionCache",
    "EnableLogs": "True",
    "RequestTimeout": "90"
  },
}

NCache provides the AddNCacheSession() method to initialize configurations from external files before adding the session services to the container. Using this method, you can refer to the configurations by providing the name of the section containing JSON format configurations in Appsettings.json:

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

    //Add services to the container                    
    services.AddNCacheSession(Configuration.GetSection("NCacheSessions"));
}

Step 2: Add Middleware to Application

Once the services have been initialized, you can now configure the HTTP request pipeline by adding middleware in the Configure() method. The following is an excerpt showing the addition of a middleware layer through the use of UseNCacheSession() extension method inIApplicationBuilder. The NCache session middleware should always be stacked before the layer that utilizes the sessions.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseBrowserLink();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }
    app.UseStaticFiles();           

    app.UseNCacheSession(); //store NCache session data            

    app.UseMvc(routes =>
    {
        routes.MapRoute(
            name: "default",
            template: "{controller=myApp}/{action=Index}/{id?}");
    });
}

The configuration options provided by NCache are explained below:

Member	Type	Description	Default Value
`CacheName`	`string` (required)	Specifies the name of the cache to be used for caching session. If no cache name is specified, a configuration exception will be thrown.	-
`EmptySessionWhenLocked`	`bool` (optional)	Specifies if an empty session should be returned if a session is locked after `sessionLockingRetry` has exceeded.	`false`
`EnableSessionLocking`	`bool` (optional)	If this flag is set, NCache Session Management exclusively locks the session-store item for which multiple concurrent requests are made.	`false`
`EnableLogs`	`bool` (optional)	If this flag is set, NCache logs all error information. The log files are created in `%NCHOME%/log-files/SessionState/.`	`false`
`EnableDetailLogs`	`bool` (optional)	When this flag is set, NCache logs all debugging information. The log files are created in `%NCHOME%/log-files/SessionState/.`	`false`
`ExceptionsEnabled`	`bool` (optional)	Specifies whether exceptions from cache API are propagated to the page output. Setting this flag is especially helpful during development phase of application, since exceptions provide more information about the specific causes of failure.	`false`
`OperationRetry`	`int` (optional)	Specifies the number of times server will retry the operation, in case connection is lost with a server while an operation is executing.	0 (zero)
`OperationRetryInterval`	`int` (optional)	Specifies the time interval between each operation retry, in case connection is lost with the server.	0 (zero)
`ReadOnlyFlag`	`string` (optional)	If specified in `HttpContext.Items` before session middleware, it will return a read-only session that will not be committed. This session is lock free.	`NCache.AspNetCore.IsReadOnly`
`RequestTimeout`	`int` (optional)	Specifies the time interval in seconds after which a session will be forcibly unlocked if it has not been released during this interval.	120
`SessionAppId`	`string` (optional)	Specifies an identifier to make sure that session ID remains unique in case multiple applications are using the same session. Application ID should be the same for an application in a web farm. If no app ID is specified, nothing will be concatenated with session ID.	-
`SessionLockingRetry`	`int` (optional)	If `enableSessionLocking` is true and this integer is not less than 0, NCache Session Store Provider will return an empty session after `sessionLockingRetry`, which specify the number of retries to acquire a lock.	-1
`SessionOptions`	`SessionOptions`	.NET Core specific class to configure sessions like cookie information. Refer to the API documentation for more detail.	-
`WriteExceptionsToEventLog`	`bool` (optional)	If this flag is set, all the exceptions from cache API are written to event logs.	`false`