Scaleout.AspNet 1.0.0-beta

ASP.NET Session State Provider

An ASP.NET session state provider for use with ScaleOut Software's in-memory data grid products. (For ASP.NET Core session state support, use the Scaleout.AspNetCore package.)

Motivation

This 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 differs in the following ways:

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

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: Required. String containing information for connecting to ScaleOut service, as described in the Connection Strings topic below.
• 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.

Connecting to a ScaleOut Data Grid

The ScaleOut session provider uses parameters in a connection string to determine how to connect to hosts in a distributed ScaleOut in-memory data grid.

A ScaleOut in-memory data grid (also known as a distributed data grid) is a cluster of servers that work together to provide scalable, high-performance distributed cache. A data grid can host many separate namespaces, referred to as caches, for grouping logically related objects.

Connection Strings

A connection string is a list of parameters delimited by a semicolon and typically takes the following form:

bootstrapGateways=ServerOne:721,ServerTwo:721;useSecure=false;maxPoolsize=16

Connection String Parameters

The following parameters can be set in a connection string.

• bootstrapGateways - Required. A comma-separated list of host:port pairs pointing to ScaleOut hosts. This list is used for bootstrapping the first connection to the data grid. At least one of the hosts in the list needs to be active--the gateways are checked in order, and, once a connection is established, the current grid membership is retrieved from that server for subsequent connections.

  Each bootstrapGateway entry in the comma-delimited host list consists of two values, separated by a colon:

  • host - Required. The address (DNS name or IP) of a system running the ScaleOut service.

  • port - Required. The TCP port used by the ScaleOut service to serve client requests (the server's svr_port parameter). Use the host's secure_svr_port parameter if useSecure is enabled for this data grid connection.

• useSecure - Optional. Specifies whether the library will use secure, TLS-encrypted connections when communicating with servers in the ScaleOut data grid. The default value is false (disabled). If enabled, the servers in the ScaleOut data grid must be configured with accept_secure set to 1 in their soss_params.txt files. Also, this dataGrid configuration must use the hosts' secure_svr_port value (instead of svr_port) in each bootstrapGateways entry.

• maxPoolSize - Optional. Sets the maximum number of TCP connections that the library may open to each ScaleOut host in the data grid. The default value is 16 connections per host, and the maximum allowed value is 64.

• maxRequestRetries - Optional. Specifies the maximum number of retries that a client will make to connect to a ScaleOut server or to retry a request once connected. The default is 2 retries.

• eventConnectionCount - Optional. Specifies the number of TCP connections that a local client will open to receive events from the local ScaleOut service (for firing the Global.asax Session_End event). The default is 4 connections. (This parameter is ignored for remote client applications--remote clients open one TCP connection for events.)