Scaleout.AspNetCore 1.1.0-beta

ScaleOut ASP.NET Core Distributed Cache Library

This library provides an implementation of Microsoft.Extensions.Caching.Distributed.IDistributedCache for session state storage using ScaleOut StateServer in ASP.NET Core web applications.

NuGet: Install-Package Scaleout.AspNetCore

Quick Start

To configure your ASP.NET Core web application to use ScaleOut StateServer for session state storage:

1. Install the Scaleout.AspNetCore NuGet package: Install-Package Scaleout.AspNetCore
2. In an application settings file (such as appsettings.json), add the following configuration elements, replacing the example configuration values as appropriate to your environment (Configuration elements are described in further detail later in this document):

	"ScaleOutStateServer": {
		"gateways": [
		  {
			"ip": "10.0.0.100",
			"servicePort": 721
		  },
		  {
			"ip": "10.0.0.101",
			"servicePort": 721
		  }
		],
		"defaultNamespace": "HelloWorld",
		"Protocol": "SossTcpTransport"
	  }

4. In the ConfigureServices(IServiceCollection) initialization method, add the following line(s):

	public void ConfigureServices(IServiceCollection services)
	{
		// Add framework services.
		// ...
		services.AddSession();

		// Add ScaleOut implementation of IDistributedCache.
		services.AddScaleoutDistributedCache(Configuration);
		
		// ...
	}

Note: If the application configuration file(s) use a different name than "ScaleOutStateServer" for the configuration element, you may use the AddScaleoutDistributedCache(ConfigurationSection) overload, e.g., services.AddScaleoutDistributedCache(Configuration.GetSection("MyScaleOutConfigurationSection")).

That's it! All session access (typically through HttpContext.Session) will automatically read and store session information to the ScaleOut StateServer in-memory data grid.

Configuration

Gateways (list)

REQUIRED. List of gateways to use to connect to the ScaleOut StateServer service. Each element has two values:

1. ip (string). REQUIRED. The IP address of the gateway.
2. servicePort (integer). Optional. The service port for the selected protocol. Default: 721 (for the SossTcpTransport provider). If the SossHttpTransport is used, the port should be changed to direct requests to the port used by the ScaleOut REST API Service (typically port 4001).

Example

"gateways": [
    {
	    "ip": "10.0.0.100",
		"servicePort": 721
    },
    {
		"ip": "10.0.0.101",
		"servicePort": 721
    }
]

DefaultNamespace (string)

REQUIRED. The name of the application namespace to use in the ScaleOut StateServer in-memory data grid.

MaxSerializedCacheMemory (integer)

Optional. The maximum size (in bytes) of the serialized network cache held in the client memory process to minimize data transfer to and from the ScaleOut StateServer service when the client is internally known to be working with the latest version of a ScaleOut StateServer data grid object. Default: 10 MB.

MaxGatewayAttempts (integer)

Optional. The number of attempts for any operation which accesses the ScaleOut StateServer data grid before throwing an exception. Default: 3.

Protocol (string)

Optional. The protocol to use when communicating between the client application and the ScaleOut StateServer service. Two protocols are currently supported:

• SossTcpTransport (default): Connects directly to the ScaleOut service. Offers the best performance.

• SossHttpTransport: Communicates to the ScaleOut StateServer service over HTTP via the ScaleOut REST API service.

UseSecure (boolean)

Optional. Whether to use the secure version of the selected protocol. If set to true, ensure the associated service is properly configured to accept secure requests. Default: false.

The accept_secure, secure_svr_port, and secure_mgt_port parameters must be set in the ScaleOut service to use encrypted communications with the SossTcpTransport protocol. The servicePort value in your config's gateways section must also be modified to point to the ScaleOut service's secure_svr_port.

If the SossHttpTransport protocol is to be secured, see the Configuring the REST API Service topic for details on how to enable HTTPS in the REST service.

MaxTCPPoolSize (integer)

Optional. When using the TcpGatewayTransport, gets or 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 TCP connections per ScaleOut host.

CoherencyInterval (double)

Optional. The maximum amount of time (in seconds) that can elapse before the client library performs a round-trip to the authoritative ScaleOut service. During this interval, a requested object can be returned directly from the in-process cache, which results in very good performance, but the returned value could be stale. The default value is 0 seconds (the cache is fully coherent).

The CoherencyInterval option is only supported by the TcpGatewayTransport protocol.