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.
Install this NuGet package and its dependencies:
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" clientCacheType="LRU" clientCacheCapacity="100" handleSessionEnd="false" namespace="My cache namespace" /> </providers> </sessionState>
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
clientCacheCapacityvalue. If “LRU-MaxMemory” is used, the size of the client cache size is determined by memory usage instead of a simple count; the
clientCacheCapacityvalue 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
clientCacheTypevalue. The default value is 100 sessions (or 100 megabytes, if
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
providerNameattribute 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.