ASP.NET Core Session Provider Configuration

To configure NCache ASP.NET Core Session Provider, follow the steps below.

Prerequisites

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:

  1. Through your application in Startup.cs or
  2. In JSON format in Appsettings.json
Note

The configuration must always contain the cache name.

Method 1: Specifying Configurations in Startup.cs

Sessions can be initialized by the AddNCacheSession extension method that takes an IOptions<NCacheSessionConfiguration> object as the configuration.

In Startup.cs of your application, add the following code in the ConfigureServices method:

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

    // Add services to the container with configured session
    services.AddNCacheSession(configuration =>
    {
        configuration.CacheName = "demoCache";
        configuration.EnableLogs = true;
        configuration.SessionAppId = "demoApp";
        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:

{
  "NCacheSettings": {
    "SessionAppId": "demoApp",
    "SessionOptions": {
      "CookieName": "AspNetCore.Session",
      "CookieDomain": null,
      "CookiePath": "/",
      "CookieHttpOnly": "True",
      "IdleTimeout": "5",
      "CookieSecure": "None",
      "useJsonSerialization": true,
      "WriteExceptionsToEventLog": true,
    },

    "CacheName": "demoCache",
    "EnableLogs": "True",
    "RequestTimeout": "90"
  },
}
Note

It is not recommended to use the WriteExceptionsToEventLog tag in a Production environment.

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("NCacheSettings"));
}

Step 2: Add Middleware to Application

Once the services have been initialized, you can now configure the HTTPS 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 the UseNCacheSession extension method in IApplicationBuilder. 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?}");
    });
}

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

Configuration Properties

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 the 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 it is locked after the sessionLockingRetry count has been 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 (Windows) or /opt/ncache/log-files/SessionState (Linux). false
EnableDetailLogs bool (optional) When this flag is set, NCache logs all 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
OperationRetry int (optional) Specifies the number of times the server will retry the operation, in case a 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 the 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 the 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 specifies 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 details. -
WriteExceptionsToEventLog bool (optional) If this flag is set, all the exceptions from cache API are written to event logs. false
usejsonserialization bool This is a boolean attribute. If you want to use JSON serialization for your ASP.NET Core Session objects, set the value of this attribute as true. false

See Also

Using NCache with ASP.NET Core
Configure ASP.​NET Core Sessions with NCache IDistributed​Cache Provider
Multi-Region ASP.​NET Core Session Provider for NCache
Object Caching in ASP.​NET Core
ASP.NET Core Response Caching