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.)


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.


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

  • .NET Framework 4.6.2 or higher.


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">
    <add name="ScaleOutSessionProvider"
         namespace="My cache namespace" />

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”).

  • 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.

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.