Connecting to a ScaleOut Data Grid

The ScaleOut session providers use 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.)

Troubleshooting Connectivity Errors in ASP.NET

When an error occurs in a traditional 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.