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; the clientCacheCapacity 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, if clientCacheType 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.