ASP.NET Session State Provider

The Scaleout.AspNet NuGet package provides a 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

This is a new, alternative ASP.NET session provider that is different from the original session provider that ships in the ScaleOut Product Suite’s installer. This new provider offers the following benefits:

  • No need to install/configure ScaleOut’s remote client libraries.
  • Configuration is specified entirely through the application’s web.config file.
  • Built on top of ScaleOut’s new Scaleout.Client library.

Prerequisites

  • One or more instances of the ScaleOut SessionServer or StateServer service (either local or remote).
  • .NET Framework 4.6.2 or higher.

Configuration

Install this NuGet package and its dependencies:

Install-Package Scaleout.AspNet

Modify the sessionState element in your app’s web.config file to use the ScaleOut.AspNet session provider. For example:

<sessionState mode="Custom" customProvider="ScaleOutSessionProvider" timeout="20" regenerateExpiredSessionId="true">
  <providers>
    <add name="ScaleOutSessionProvider"
         type="Scaleout.AspNet.ScaleoutSessionStateProvider"
         connectionString="bootstrapGateways=192.168.1.42:721,192.168.1.43:721;maxRequestRetries=2;eventConnectionCount=4"
         clientCacheCapacity="1000"
         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.
  • clientCacheCapacity: Optional. The number of deserialized session state objects that can be held in the library’s in-process client cache. The default value is 100 sessions.
  • 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.

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.

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.