Scaleout.AspNetCore 1.0.1

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. Ensure the ScaleOut Client REST Service on each host running the ScaleOut StateServer service is running. It is strongly recommended to change the startup behavior to Automatic when using this library.
2. Install the Scaleout.AspNetCore NuGet package: Install-Package Scaleout.AspNetCore
3. 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"
		  },
		  {
			"ip": "10.0.0.101"
		  }
		],
		"defaultNamespace": "HelloWorld"
	  }

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: 4001 (for the SossHttpTransport provider).

Example

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

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. Which protocol to use when communicating between the client application and the ScaleOut StateServer service. Currently, only "SossHttpTransport" is supported, which communicates to the ScaleOut StateServer service through the ScaleOut REST API service. Default: SossHttpTransport.

UseSecure (boolean)

Optional. Whether to use the secure version of the selected protocol (e.g., HTTP becomes HTTPS). If set to true, ensure the associated service is properly configured to accept secure requests. Default: false.