Table of Contents

Connecting to a ScaleOut Data Grid

The ScaleOut client library uses parameters in a connection string to determine how to connect to hosts in a distributed ScaleOut in-memory data grid. The connection string is typically stored in a config file and is supplied to the GridConnection's static Connect(string) (or ConnectAsync(string)) method.

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.

A GridConnection instance represents multiplexed connections to all of the servers in a ScaleOut in-memory data grid. A GridConnection instance is thread-safe and maintains a pool of TCP connections to ScaleOut hosts. Multiple CacheBuilders should use the same GridConnection instance if they are connecting to the same ScaleOut cluster. (Since most applications only connect to a single ScaleOut cluster, most applications should only use a single GridConnection instance.)

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.

    Note

    While the bootstrapGateway parameter is typically required, it can be omitted if a BootstrapGatewayProvider instance is supplied to the GridConnection's Connect/ConnectAsync overloads. A BootstrapGatewayProvider supplies dynamic gateway information to the GridConnection and is used to connect to ScaleOut clusters in cloud environments (see Connecting to ScaleOut in AWS EC2 for an example).

  • 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).

    Note

    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 128.

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

  • notReadyTimeoutSecs - Optional. Specifies the maximum amount of time (in seconds) that a client will spend retrying add/update operations if the ScaleOut service is low on memory (or reports that it is otherwise not ready to handle the request due to heavy load or environmental delays). This value is parsed as a double-precision floating-point number (invariant culture) and may specify a fraction of a second. A value of 0 (zero) disables the retry behavior, in which case a NotReadyException or a ScaleoutMemoryException may be thrown immediately from an add/update call. The default is 2.0 seconds.

  • eventConnectionCount - Optional. Specifies the number of TCP connections that a local client will open to receive events from the local ScaleOut service (expiration events, posted StreamServer events, Invoke events, etc.). The default is 4 connections. (This parameter is ignored for remote client applications--remote clients open one TCP connection for events.)

  • ignoreKeyAppId - Optional. Specifies that the connection should not use an object's application identifier (its cache membership) when selecting a location for an object. Setting this value to true allows objects with the same key to be stored on the same server even if they belong to different named caches. Only set to true when servers in the ScaleOut data grid are configured with ignore_key_appid set to 1 in their soss_params.txt files. The default value is false.

  • gatewayMode - Optional. Specifies whether the client should connect to the grid using the server's public gateway addresses (default) or the private host IP addresses used for host-to-host communication. The value must be one of the following:

    • "public" - Default. Connect to the grid using the ScaleOut hosts' public gateway addresses.
    • "private" - Connect using the private host IP addresses used by the service for host-to-host communication. This configuration is typically used in cloud environments: for example, when a client application needs to run locally on a ScaleOut server, but that server's public IP address is not reachable.

Using a Configuration File

Connections strings should be stored in a configuration file so that they can be modified in a production environment.

.NET Framework

In a traditional .NET Framework application, consider storing the string in your config file's <appSettings> section or in the <connectionStrings> section. For example:

<?xml version="1.0" encoding="utf-8" ?>  
<configuration>  
  <connectionStrings>  
    <add name="ScaleoutConnString" 
	     connectionString="bootstrapGateways=192.168.1.42:721,192.168.1.43:721" />  
  </connectionStrings>  
</configuration> 

// Read connection string from <connectionStrings/> section:
var settings = ConfigurationManager.ConnectionStrings["ScaleoutConnString"];
var conn = GridConnection.Connect(settings.ConnectionString);

// Build a Cache instance:
var cb = new CacheBuilder<string, string>("customers", conn);
var customerCache = cb.Build();

.NET Core

.NET Core's configuration system is less rigid than the .NET Framework and allows you to store values anywhere in a configuration file. Config values may be overridden by environment variables, which is convenient for deploying an application via Docker.

An appsettings.json file containing a connection string and cache policies could look like this:

{
  "scaleoutConnString": "bootstrapGateways=192.168.1.42:721,192.168.1.43:721",

  "cacheConfig": {
     "Timeout": "00:45:00",
     "ClientCacheEviction": "Random",
     "ClientCacheCapacity": 1234,
     "CoherencyInterval": "00:05:00"
  }
}

Values can be pulled from configuration sources as follows:

using System;
using Microsoft.Extensions.Configuration;
using Scaleout.Client;

class Program
{
    static void Main(string[] args)
    {
        // Gather config info from appsettings.json & environment variables:
        var builder = new ConfigurationBuilder()
                .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
                .AddEnvironmentVariables();
        var config = builder.Build();

        // Get connection string from config:
        string connString = config.GetSection("scaleoutConnString").Value;
        var conn = GridConnection.Connect(connString);

        // Build a Cache instance:
        var cb = new CacheBuilder<string, string>(
                "customers", 
                conn, 
                config.GetSection("cacheConfig"));
        var customerCache = cb.Build();
    }
}

In an ASP.NET Core application, an IConfiguration instance is built on your behalf and is available as a property in your application's Startup class--you typically do not need to build it yourself.

Note that the "scaleoutConnString" value could be overridden by an environment variable with the same name. For more details on configuration providers, see the documentation for the .NET Core Configuration API.

Running as a Local Client Application

A client application that connects to ScaleOut hosts remotely over the network must be licensed for remote access. Applications that run locally on a system running the ScaleOut service do not require a remote client license.

The connection string for local clients must contain either localhost or 127.0.0.1 in the connection string's bootstrapGateways list to put the library into local client mode. If the local host's actual IP address or hostname is used instead of the loopback address then the client library will connect to the service as a remote client, consuming a remote client license slot.

The port number can be omitted from the connection string's bootstrap gateway when running as a local client. If omitted, the Scaleout.Client library will read the local server's soss_params.txt file and use the svr_port value from there.