NCache 4.3 - Online Documentation

NCache Session State Module

 
NCache Session State Module allows you to transparently save and retrieve ASP.NET session-state objects within a webfarm. As compared to ASP.NET Session State Module which is centralized in nature, NCache Session State Module is truly distributed. It benefits from clustered caching and thus, it implicitly avoids single point of failure. Also, when running cache as InProc, no extra cost is involved in retrieving session-state objects.
 
Configuration Steps
 
Please follow these steps for enabling NCache Session State Module to transparently save and retrieve ASP.NET session-state objects.
 
1. Edit your application's web.config file to add <appSettings> entry under <configuration> section.
 
<appSettings>
<add key = "CacheName" value = "myReplicatedCache"/>
<add key = "sessionAppId" value = "1234"/>
<add key = "exceptionsEnabled" value = "true"/>
<add key = "enableLogs" value = "false" />
<add key = "enableDetailLogs" value = "false"/>
<add key = "clearASPSession" value = "false"/>
<add key = "writeExceptionsToEventLog" value = "false"/>
<add key = "operationRetries" value = "0"/>
<add key = "operationRetryInterval" value = "0"/>
</appSettings>
 
Following is the description of different key-value pairs specified above:
 
  • CacheName: Required string attribute. Specifies the name of the cache to be used for caching session. If no cache name is specified a configuration exception will be thrown.
 
  • sessionAppId : Optional string attribute. Specifies an identifier to make sure that session id remains unique in case multiple applications are using same cache. Application id should be same for an application in a web farm. If no app id is specified nothing will be concatenated with session id.
 
  • exceptionsEnabled: Optional Boolean attribute. 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. By default it is false.
 
  • enableLogs: Optional Boolean attribute. When this flag is set, http module logs all error information. The log files are created in "$ncache-install/log-files/httpmodule/". The default is false.
 
  • enableDetailLogs: Optional Boolean attribute. When this flag is set, http module logs all debugging information. The log files are created in "$ncache-install/log-files/httpmodule/". The default is false.
 
  • clearASPSession: Optional Boolean attribute. If your website contains multiple App Domains and you allow user to go from one App to another either through Response.Redirect(url, false) or by providing a link on one of the pages, you must use this property. If this flag is not set, the regular ASP session store will also save session information. And, in case of InProc sessions, web server will start consuming memory. By default it is true. There are two possible scenarios when user is using custom module along with NCache:
 
Scenario 1:
If custom module is loaded before NCache's, custom module calls our Load function to load session from cache. In this case NCache will not load session information again. So it is custom http module responsibility to clear session before calling Load function.
 
Scenario 2:
If custom module is loaded after NCache's, clearAspSession should be set to false because NCache will clear session after updating the cache and custom module will get empty session. However custom module may have to clear session and then Load from cache again after NCache's module has already loaded session from cache.
 
  • writeExceptionsToEventLog: Optional Boolean attribute. If this flag is set, all the exceptions from cache API are written to event logs. The default is false.
 
  • operationRetries: In a scenario where connection is lost with a server while an operation is executing, there is a possibility that operation will be lost during that time interval. operationRetries specifies the number of times the server will try to resume the operation . Its default value will be zero.
 
  • operationRetryInterval: It specifies the time interval between each operation retry, in case connection is lost with the server. Its default value will be zero.
 
2. Add <httpmodules> entry under <system.web> section in web.config.
 
<httpModules>
<add name = "NCacheWebSessionState" type = "Alachisoft.NCache.Web.SessionState.NSessionStateModule,
Alachisoft.NCache.SessionState, Version=x.x.x.x, Culture=neutral, PublicKeyToken=cff5926ed6a53769"/>
</httpModules>
 
Note: Replace version “x.x.x.x” with the actual NCache version that you have.
 
 
3. Add <machinekey> entry under <system.web> section in web.config. It is required to generate ASP.NET session IDs in the same manner on all nodes.
 
<machineKey validationKey = "A01D6E0D1A5D2A22E0854CA612FE5C5EC4AECF24" decryptionKey = "ACD8EBF87C4C8937" validation = "SHA1"/>
 
Special Considerations when Storing ASP.NET 1.1 Sessions in NCache
 
Session.Redirect(url, false)
 
You must specify "false" as the second argument in all your Session.Redirect calls. Otherwise, the new page will not see any changes which you have made to Session in the current page. The reason is that if you don't specify "false", ASP.NET terminates the response and does not invoke NSessionStateModule (NCache's Session State Module) for saving Session into the cache. And, when the new page retrieves Session from the cache, it gets the older copy which does not have your changes.
 
Session.Abandon()
 
If you make Session.Abandon() call, it does not delete the session from the cache in .NET 1.1. So, the preferred way of abandoning the session is by calling NSessionStateModule's Abandon call. However, you'll first have to get a handle to this NCache Session State Module from HttpApplication object. Below is sample code:
 
using Alachisoft.NCache.Web.SessionState;
 
//you may write the following code under logout button
NSessionStateModule sm = Application["NSessionStateModule"] as NSessionStateModule;
sm.Abandon(Session);
 
The reason for doing this, is that if you simply call Session.Abandon(), there is no way ASP.NET provides for NSessionStateModule to find this out. Therefore, it cannot take appropriate action.
Please note that this is not a problem in .NET 2.0 or later versions where you're able to use SSP.
 
Using Session in your own custom HttpModules
 
NCache provides an HttpModule (NSessionStateModule) to handle Session storage in the cache. This NSessionStateModul is called at AcquireRequestState and ReleaseRequestState events. However, if you've also developed an HttpModule and your event handlers are called before NSessionStateModule's event handlers are called, then your code is not likely to see the correct data in the Session object.
 
If your HttpModule is called before AcquireRequestState event handler of NSessionStateModule is called, then you'll see an empty session. And, to handle this situation, you'll need to use the following code at the beginning of your HttpModule's event handler:
 
using Alachisoft.NCache.Web.SessionState;
 
//you may write the following code under logout button
NSessionStateModule sm = Application["NSessionStateModule"] as NSessionStateModule;
sm.Load(HttpContext);
 
If your code is making changes to the Session object and wants to make sure these changes are seen by other ASP.NET pages, then you should call NSessionStateModule.Update(HttpContext) in the following way:
 
using Alachisoft.NCache.Web.SessionState;
 
//you may write the following code under logout button
NSessionStateModule sm = Application["NSessionStateModule"] as NSessionStateModule;
sm.Update(HttpContext);
 
This will ensure that everything is working properly.
 
Using Session.Clear()
 
Please note that if you're using Session.Clear(), NCache will remove this Session from the cache. Upon trying to save the Session content, NCache checks to see if Session is empty (Session.Count == 0). If that is the case, then it calls a cache.Remove(…).
 
 
See Also
 
© Copyright  2014 Alachisoft. All rights reserved.