NCache 4.6 - Online Documentation

Using NCache Session Management Services with ASP.NET Core

 

Install NuGet Package

Install the NuGet package Alachisoft.NCacheSessionServices.Enterprise to your application.
 

Include Namespaces

To utilize the APIs, include the following namespaces in your application:
using Alachisoft.NCache.Web.SessionState;
using Alachisoft.NCache.Web.SessionState.Configuration;
 

Configure Services

The session management service needs to be initialized. In Startup.cs, use the SetNCacheSessionConfiguration() extension method on IServiceCollection in ConfigureServices() to initialize the service. The very basic overload of this extension method takes an IOptions<NCacheSessionConfiguration> as its base configuration.
 
The configuration options provided by NCache are:
 
Member
Type
Description
Default Value
AffinityMapping
CacheAffinity
(optional)
Array of CacheAffinity type containing the CacheName and CachePrefix which is used to identify the location of source cache in cookies. Note that each location will contain a primary cache, and if more than one caches have been defined, the primary cache will be the one specified against CacheName (see Configuring Location Affinity for more detail).
null
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 "%Install_Dir%/log-files/SessionState/".
false
EnableDetailLogs
bool
(optional)
When this flag is set, NCache logs all debugging information. The log files are created in "%Install_Dir%/log-files/SessionState/".
false
EnableLocationAffinity
bool
(optional)
Flag to enable Location Affinity for a geographically distributed web farm.
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
(optional)
.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
 
The configuration must always contain the cache name.
 
·     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 configuration
    services.AddNCacheSession(configuration =>
    {
        configuration.CacheName = "myCache"; //compulsory
        configuration.EnableLogs = true;
        configuration.RequestTimeout = 5;
    });                    
}
 
·     Specifying Configurations In Separate Files
 
The configurations can also be provided in JSON format in either a section in appsettings.json of your application or any external JSON file. For example, the NCacheSettings section is added to appsettings.json:
 
"NCacheSettings": {
  "CacheName": "MyCache",
  "EnableSessionLocking": true
}
 
NCache provides the SetNCacheSessionConfiguration() method to initialize configurations from separate files before adding the session services to the container. Using this method, you can either:
 
·     Provide 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.SetNCacheSessionConfiguration(Configuration.GetSection("NCacheSettings"));
 
    services.AddNCacheSession();
}
 
·     Provide path to JSON file containing configuration:
 
public void ConfigureServices(IServiceCollection services)
{
    //Add framework services
    services.AddMvc();
    
    //Add services to the container       
    services.SetNCacheSessionConfiguration(Configuration.GetSection("D:/Config/ncsettings.json"));
 
    services.AddNCacheSession();
}
 

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 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?}");
    });
}
 
 
See Also