ASP.NET Async Session State Provider
The Scaleout.AspNetAsync NuGet package provides an async session state provider for use with ScaleOut Software’s in-memory data grid products.
(This provider is for ASP.NET applications running on the traditional .NET Framework. For ASP.NET Core session state support, use the Scaleout.AspNetCore package.)
Background
Support for async session providers was introduced in ASP.NET 4.6.2. See the Introducing the ASP.Net Async SessionState Module article on the ASP.NET blog for more information about the advantages of using the Async SessionState module.
Prerequisites
One or more instances of the ScaleOut SessionServer or StateServer service (either local or remote).
.NET Framework 4.6.2 or higher.
Installation
Install this NuGet package and its dependencies:
Install-Package Scaleout.AspNetAsync
One of the package’s dependencies, the Microsoft.AspNet.SessionState.SessionStateModule package, will add a new module to your web.config to add async session support to your application. You should see the following change made to web.config automatically:
<system.webServer>
<modules>
<remove name="Session" />
<add name="Session" type="Microsoft.AspNet.SessionState.SessionStateModuleAsync, Microsoft.AspNet.SessionState.SessionStateModule, Version=1.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="integratedMode" />
</modules>
</system.webServer>
More information about the async session module is available in the ASP.NET team’s introductory blog post.
Configuration
Modify the sessionState element in your app’s web.config file to use the Scaleout.AspNetAsync session provider. For example:
<sessionState mode="Custom" customProvider="ScaleOutAsyncSessionProvider" timeout="20" regenerateExpiredSessionId="true">
<providers>
<add name="ScaleOutAsyncSessionProvider"
type="Scaleout.AspNetAsync.ScaleoutSessionStateProviderAsync"
connectionString="bootstrapGateways=192.168.1.42:721,192.168.1.43:721;maxRequestRetries=2;eventConnectionCount=4"
clientCacheType="LRU"
clientCacheCapacity="100"
encryptionPasswordLocation="None"
handleSessionEnd="false"
namespace="My cache namespace" />
</providers>
</sessionState>
Provider Settings
The following configuration attributes in the example above are specific to the ScaleOut session provider:
- connectionString
String containing information for connecting to ScaleOut service, as described in the Connecting to a ScaleOut Data Grid topic.
- clientCacheType
Optional. The type of eviction strategy used by the library’s in-process client cache. The default is “LRU”, indicating that the client cache size is limited to a count of recently-accessed session objects, as specified by the
clientCacheCapacity
value. If “LRU-MaxMemory” is used, the size of the client cache size is determined by memory usage instead of a simple count; theclientCacheCapacity
value indicates the client cache’s memory limit in this mode (specified in megabytes).- clientCacheCapacity
Optional. The size of the library’s in-process client cache, expressed either as a count or a memory limit (in MB), depending on the
clientCacheType
value. The default value is 100 sessions (or 100 megabytes, ifclientCacheType
is “LRU-MaxMemory”).- encryptionPasswordLocation
Optional. Sets the location of a password in web.config when encrypting session data. Use “AppSettings” to specify the password in the <appSettings> section of web.config, or set to “ConfigSection” to to specify the password in the <scaleoutEncryptedSessions> configuration section. “None” (default) disables encryption. See Encrypting Session Data for more information.
- handleSessionEnd
Optional. Determines whether the provider registers with the ScaleOut service to handle object expirations events so that Global.asax’s Session_End event can be fired. Defaults to false.
- namespace
Optional. Specifies the cache namespace that the ScaleOut service will use for storing ASP.NET session objects. If omitted, the application path in the web server is used as the cache name.
- remoteStores
Optional, requires ScaleOut GeoServer® Pro license. A comma-separated list of GeoServer remote store names that session provider should use to look for sessions that are not found in the local store. Read calls will check remote stores in the order that they are listed. If a missing session is found in one of the specified remote stores then it will be replicated to the local store using GeoServer Pro replication. The specified name(s) must exactly match the names of remote stores that are configured for GeoServer pull replication.
Alternative Connection String Locations
To specify a connection string through a different mechanism than the connectionString
attribute described above, remove the connectionString
attribute and replace it with one of the following alternatives:
- connectionStringEnvironmentVariable
The name of a system environment variable containing the ScaleOut connection string.
- connectionStringAppSetting
The name of an entry in a config file’s appSettings section that contains the ScaleOut connection string.
- connectionStringElement
The name of an entry in a config file’s connectionStrings section that contains the ScaleOut connection string. The specified entry under the connectionStrings section does not need to have its
providerName
attribute set if this location is used.
The value that is referenced in any of these locations must be a valid connection string as described in Connecting to a ScaleOut Data Grid.
Allowing Concurrent Requests
By default, ASP.NET session state providers use a restrictive locking strategy that only allows a single request to access a session at a time. This can cause performance bottlenecks when a web app makes concurrent XMLHttpRequests, as they can only be processed sequentially.
The ScaleOut Async Session State Provider supports the aspnet:AllowConcurrentRequestsPerSession
appSettings value to disable this restrictive locking behavior. If set to true, multiple requests will be allowed to access a session simultaneously:
<appSettings>
<add key="aspnet:AllowConcurrentRequestsPerSession" value="true"/>
</appSettings>
When concurrent requests are enabled, there is a risk of losing session updates if multiple requests modify a session at the same time. Only use this approach if you are confident that just one of your concurrent requests (say, the main page request handler) is going to modify your session state or if your business requirements allow for a lost session update.
Troubleshooting Configuration Errors
When an error occurs in an ASP.NET application, the standard error page (often called the “Yellow Screen of Death”, or YSOD) typically provides useful troubleshooting details such as exception information and a stack trace. However, ASP.NET does not provide this detailed information when an exception is thrown from a session provider. Instead, the YSOD simply states that a configuration error occurred and highlights the provider that is responsible for the problem.
To see the full stack and exception details when the ScaleOut session provider cannot start up due to a configuration/connectivity problem, open the Windows Event Viewer and check the Application Event Log; the full exception will be logged as a Warning entry.