ASP.NET Core Session Provider Configuration
To configure NCache ASP.NET Core Session Provider, follow the steps below.
Prerequisites
- Install the following NuGet packages in your application based on your NCache version:
- Enterprise: AspNetCore.Session.NCache.
- Professional: AspNetCore.Session.NCache.Professional
- OpenSource: AspNetCore.Session.NCache.OpenSource
- To utilize the extension, include the following namespaces in your application in Startup.cs:
- The cache must be running.
- For API details, refer to: AddNCacheSession.
- 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 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 in Startup.cs or
- 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 IDistributedCache Provider
Multi-Region ASP.NET Core Session Provider for NCache
Object Caching in ASP.NET Core
ASP.NET Core Response Caching