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