ASP.NET Core Session Provider Configuration

To configure NCache ASP.NET Core Session Provider for Session Management Service, you need to modify the appropriate files and then add middleware to the application if necessary, as explained below.

Prerequisites

Using .NET 6.0 and Above

If you are using a .NET 6.0 or above version for your applications, follow the steps mentioned below:

Step 1: Configure NCache Session Management Service

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

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

The configuration must always contain the cache name.

Method 1: Specifying Configurations in Program.cs

Sessions can be initialized by the AddNCacheSession extension method in your Program.cs file as shown below:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllersWithViews();

// Set up MVC Services
builder.Services.AddMvc();

// Configure NCache Session State
builder.Services.AddNCacheSession(options =>
{
      options.CacheName = "demoCache";
      options.EnableLogs = true;
      options.UseJsonSerialization = true; // To avoid the Binary Format error
      options.SessionAddId = “demoApp”;
      options.SessionOptions.IdleTimeout = 5;
      options.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 to set up NCache as the distributed cache provider for session management using settings from the configuration, though the builder.Services property:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllersWithViews();

// Set up MVC Services
builder.Services.AddMvc();

// Get the NCache settings from configuration
builder.Services.AddNCacheSession(builder.Configuration.GetSection("NCacheSettings"));

Step 2: Add Middleware to Application

After initializing the services, you can configure the HTTPS request pipeline by adding middleware in the Configure method. Below is an example that demonstrates how to include middleware using the UseNCacheSession extension method in IApplicationBuilder. It's important to place the NCache session middleware before any layers that depend on session data.

// Set up Logging
builder.Logging.AddConsole(options =>
{
    options.IncludeScopes = true;
    options.TimestampFormat = "HH:mm:ss";
});
builder.Logging.AddDebug(); // Set up Logging

var app = builder.Build();

// Configure the HTTP request pipeline
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseNCacheSession(); // Ensure NCache session is used

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

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

Using .NET 3.1 to 5.0

If you are using .NET version 3.1 to 5.0 for your applications, follow the steps mentioned below:

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. This method initializes configurations from external files before adding the session services to the container. It takes an IOptions<NCacheSessionConfiguration> object as the configuration.

In the 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 the Appsettings.json file 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.

With the help of the AddNCacheSession method, you can refer to the configurations by providing the name of the section containing the 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 (optional) 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

.NET: Alachisoft.NCache.Web.SessionState namespace.