Client Settings for the .NET SDK with Couchbase Server

The Couchbase .NET SDK offers a configuration API for customizing bootstrapping, timeouts, reliability and for performance tuning. You can configure the client programmatically via the ClientConfiguration, PoolConfiguration and BucketConfiguration classes, using XML configuration App.Config and or Web.Config files or by using JSON config files.

Configuration Basics

There are three main levels of configuration which correlate to classes or config sections:

  1. Client level - applies to each and every client instance globally

  2. Bucket level - applies to a specific bucket and will override any global settings

  3. Pool level - applies to the connection level of a specific bucket configuration and override any bucket or client level settings if applicable

At each level, there are specific classes or sections for configuring the behavior of the SDK.

defaults exists for all properties at each level. While some, like the bootstrap server list are often overridden since environment is different, others rarely need to be changed from their defaults. In general, rely on these defaults unless otherwise proven that they do not meet your needs.

At the client level, the ClientConfiguration is the highest level configuration. Importantly, it contains the list of servers that the client will use to bootstrap against.

var clientConfig = new ClientConfiguration {
    Servers = new List<Uri> {
        new Uri("http://server1.somedomain.com:8091"),
        new Uri("http://server2.somedomain.com:8091"),
        new Uri("http://server3.somedomain.com:8091")
    }
};

The listing above is an example of a client level configuration for bootstrapping against a cluster containing the following nodes: http://server1.somedomain.com:8091, http://server2.somedomain.com:8091 and http://server3.somedomain.com:8091. This will override the default bootstrap host of http://localhost:8091 and the client will use this list to bootstrap the itself to the cluster.

Once you have a config, you’ll either pass it into the constructor or the Cluster class:

var cluster = new Cluster(clientConfig);

Alternatively, you can initialize the cluster helper:

ClusterHelper.Initialize(clientConfig);
calling a Initialize more than once per process or application may cause inconsistent behavior.

A more advanced configuration that uses all three levels might look something like this:

 var config = new ClientConfiguration {
    BucketConfigs = new Dictionary<string, BucketConfiguration> {
      {"authenticated", new BucketConfiguration {
          PoolConfiguration = new PoolConfiguration {
              MaxSize = 6,
              MinSize = 4,
              SendTimeout = 12000
          },
          DefaultOperationLifespan = 123,
          Password = "password",
          Username = "username",
          BucketName = "authenticated"
      }}
    }
};

In this example we are creating a configuration that also overrides the default BucketConfiguration and PoolConfiguration settings.

Using an App.Config or Web.Config Configuration

The section above shows how to programmatically configure the client, however in some situations you may want to use an App.Config or Web.Config to configure your client. For the most part, everything that is available programmatically can be done via the App.Config or Web.Config, for example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <sectionGroup name="couchbaseClients">
      <section name="couchbase" type="Couchbase.Configuration.Client.Providers.CouchbaseClientSection, Couchbase.NetClient" />
    </sectionGroup>
  </configSections>
  <couchbaseClients>
    <couchbase username="username" password="password">
     <servers>
        <add uri="http://server1.somedomain.com:8091"></add>
      </servers>
      <buckets>
        <add name="authenticated">
          <connectionPool name="custom" maxSize="6" minSize="4" />
        </add>
        <add name="travel-sample" useSsl="true" />
      </buckets>
    </couchbase>
  </couchbaseClients>
</configuration>

This configures two buckets "beer-sample" and "authenticated" and overrides the "authenticated" buckets pool configuration. To use this configuration, the appropriate constructor is called, passing the section name:

var cluster = new Cluster("couchbaseClients/couchbase");

JSON Configuration

In support of .NET Core, the client can now be configured using JSON config files.

JSON configuration is only supported for versions of the SDK 2.3.0 and greater running on .NET Core 1.0 or greater.
{
  "basic": {
    "username": "username",
    "password": "mypassword",
    "enableConfigHeartbeat": false,
    "servers": [
      "http://server1.somedomain.com:8091/", "http://server2.somedomain.com:8091/"
    ],
    "buckets": [
      {
        "name": "travel-sample"
      }
    ]
  }
}

Here is an example of opening a cluster using the JSON configuration above:

var builder = new ConfigurationBuilder();
builder.AddJsonFile("config.json");

var jsonConfiguration = builder.Build();
var definition = new CouchbaseClientDefinition();
jsonConfiguration.GetSection("couchbase:basic").Bind(definition);
var clientConfig = new ClientConfiguration(definition);

var cluster = new Cluster(clientConfig);
var bucket = cluster.OpenBucket("travel-sample");

The "travel-sample" bucket is opened using any of the overridden defaults.

ClientConfiguration Settings

These settings apply to each and every client instance globally.

Table 1. ClientConfiguration Properties
Name Description Default

AnalyticsRequestTimeout

Gets the analytics request timeout.

75000ms

UseSsl

Whether or not to use SSL encrypt data being sent to and from the server

false

SslPort

Overrides the DirectPort and sets the SSL port to use for key-value operations using the binary memcached protocol id UseSsl is enabled

11207

ForceSaslPlain

Forces PLAIN SASL - to work with RBAC external authentication, such as LDAP

true

ApiPort

The port to use for the Views API

8092

DirectPort

The port to use for standard memcached binary operations such as storing and retrieving documents by key

11210

MgmtPort

The port to use for the Management API

8091

HttpsMgmtPort

Overrides the MgmtPort and sets the SSL port to use for the Management API

18091

HttpsApiPort

Overrides the ApiPort and sets the SSL port to use for the Views API

18092

ObserveInterval

The interval to wait before each Observe attempt

10 ms

ObserveTimeout

The maximum amount of time to wait before timing out

500 ms

Servers

The list of servers to bootstrap from

http://localhost:8091/pools

MaxViewRetries

The upper limit for the number of times a View request that has failed will be retried

2

ViewHardTimeout

The maximum amount of time that a View request takes before timing out. This includes time for retries.

30000 ms

ViewRequestTimeout

Sets the timeout for each HTTP View request.

5000 ms

ConfigPollEnabled*

Enables configuration heartbeat checks.

true

ConfigPollInterval*

Sets the interval for configuration "heartbeat" checks, which check for changes in the configuration that are otherwise undetected by the client.

2500ms

ConfigPollCheckFloor*

Gets or sets the heartbeat configuration check floor - the minimum time between config checks.

50ms

DefaultConnectionLimit

Gets or sets the maximum number of concurrent connections allowed by a ServicePoint object used for making View and N1QL requests.

5

MaxServicePointIdleTime

Gets or sets the maximum idle time of a ServicePoint object used for making View and N1QL requests.

100,000 ms

Expect100Continue

Gets or sets a Boolean value that determines whether 100-Continue behavior is used.

DefaultOperationLifespan

Gets or sets the default maximum time an operation is allowed to take (including processing and in-flight time on the wire). Note that in App.config this is set via operationLifespan

2500ms

BucketConfigs

A map of bucket conifgurations and their names

BufferSize

The size of each buffer to allocate per TCP connection for sending and recieving Memcached operations

16k

Converter

Gets or sets the converter

-

EnableTcpKeepAlives

Gets or sets a value indicating whether enable TCP keep alives.

true

TcpKeepAliveInterval

Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received.

1000ms

TcpKeepAliveTime

Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent.

2hrs

IOErrorCheckInterval

Gets or sets the interval that the IOErrorThreshold will be checked. If the threshold is reached within the interval for a particular node, all keys mapped to that node the SDK will fail with a NodeUnavailableException in the IOperationResult.Exception field. The node will be flagged as "dead" and will try to reconnect, if connectivity is reached, the node will continue to process requests.

500ms

IOErrorThreshold

Gets or sets the interval that the IOErrorThreshold will be checked. If the threshold is reached within the interval for a particular node, all keys mapped to that node the SDK will fail with a NodeUnavailableException in the IOperationResult.Exception field. The node will be flagged as "dead" and will try to reconnect, if connectivity is reached, the node will continue to process requests.

10

NodeAvailableCheckInterval

If the client detects that a node has gone offline it will check for connectivity at this interval.

1000ms

QueryFailedThreshold

Gets or sets the query failed threshold for a Uri before it is flagged as "un-responsive". Once flagged as "un-responsive", no requests will be sent to that node until a server re-config has occurred and the Uri is added back into the pool. This is so the client will not send requests to a server node which is un-responsive.

2

QueryRequestTimeout

Gets or sets the timeout for a N1QL query request; this correlates to the client-side timeout. Server-side timeouts are configured per request using the QueryRequest.Timeout method

75000ms

SearchRequestTimeout

Gets or sets the search request timeout.

75000ms

CertificateFactory

Factory for retrieving X509 certificates from a store, or from the file system.

null

ConfigurationProviders

Control which server configuration providers are used to bootstrap the cluster and monitor for cluster changes.

CarrierPublication and HttpStreaming

IgnoreRemoteCertificateNameMismatch

Static. If TLS/SSL is enabled via UseSsl, setting this to true will disable hostname validation when authenticating connections to Couchbase Server. This is typically done in test or development enviroments where a domain name (FQDN) has not been specified for the bootstrap server’s URI, and the IP address is used to validate the certificate, which will fail with a RemoteCertificateNameMismatch error.

False

KvServerCertificateValidationCallback

Gets or sets the SSL validation callback for K/V to override the default callback.

Null

HttpServerCertificateValidationCallback

Gets or sets the SSL validation callback for HTTP Services (N1QL, Analytics, Views, etc.) to override the default callback.

Null

UseInterNetworkV6Addresses

Gets or sets a value indicating whether to use IP version 6 addresses.

falseSearchRequestTimeout

  • ConfigPollEnabled, ConfigPollInterval, and ConfigPollCheckFloor replace the previously used, deprecated settings of, respectively, EnableConfigHeartBeat, HeartbeatConfigInterval, and HeartbeatConfigCheckFloor.

BucketConfiguration Settings

These settings apply to a specific bucket and will override any global settings.

Table 2. BucketConfiguration Properties
Name Description Default

BucketName

The name of the bucket to connect to.

"default"

UseSsl

Whether or not to use SSL encrypt data being sent to and from the server

false

Password

The bucket password

empty string

ObserveInterval

The interval to wait before each Observe attempt

10ms

ObserverTimeout

The max amount of time to wait before timing out

500ms

PoolConfiguration

The TCP socket pool configuration

(see below)

DefaultOperationLifespan

The default lifespan for operations of this bucket (i.e. maximum time taken by the operation, including processing and in-flight time on the wire). Note that in App.config this is set via operationLifespan

2500ms

UseEnhancedDurability

Gets or sets a value indicating whether to use enhanced durability if the Couchbase server version supports it; if it’s not supported the client will use Observe for Endure operations.

false

PoolConfiguration Settings

These settings apply to the connection level of a specific bucket configuration and override any bucket or client level settings, if applicable.

Table 3. PoolConfiguration Properties
Name Description Default

MaxSize

The maximum number of TCP connections to use

Note: Multiplexing IO Service creates the number of MaxSize connections during the initialize phase.

2

MinSize

The minimum or starting number of TCP connections to use

Note: not used with Multiplexing IO Service

1

WaitTimeout

The amount of time to wait for a TCP connection before timing out after the MaxSize has been reached and all connections are being used

Note: not used with Multiplexing IO Service - SSL only

2500 ms

ShutdownTimeout

The amount of time to wait before the underlying socket closes its connection

10000 ms

SendTimeout

The amount of time to allow between an operation being written on the socket and being acknowledged.

15000 ms

UseSsl

Whether or not to use SSL encrypt data being sent to and from the server

false

BufferSize

The size of each buffer to allocate per TCP connection for sending and recieving Memcached operations

16k

EnableTcpKeepAlives

Gets or sets a value indicating whether enable TCP keep alives.

true

TcpKeepAliveTime

Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent.

2hrs

TcpKeepAliveInterval

Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received.

1000ms

CloseAttemptInterval

Gets or sets the interval between close attempts on a IConnection if it’s in use and IConnectionPool has been disposed.

100ms

MaxCloseAttempts

Gets or sets the maximum number of times the client will try to close a IConnection if it’s in use and IConnectionPool has been disposed.

5

UseEnhancedDurability

Gets or sets a value indicating whether to use enhanced durability if the Couchbase server version supports it; if it’s not supported the client will use Observe for Endure operations.

false

ConnectTimeout

The amount time allotted for the client to establish a TCP connection with a server before failing

10000ms

IOService

The IO Service is used to manage the TCP connections used by the SDK for Memcached (K/V) operations. There are two IO Services available; Multiplexing (MUX) and Pooled. You can configure the IOService either through the configuration file (app.config, web.config or json settings file) or programmatically using the SDK’s ClientConfiguration when initializing the Cluster.

Shared-Pooled IO Service w/MUX

As of v2.5.0, the client uses a Shared-Pooled IO Service for K/V along with Multiplexing (MUX) by default. A shared pool allows multiple threads to use a connection at the same time and each thread is assigned a connection from the pool in a round-robin fashion. This gives the best performance and the benefits of both Multiplexing IO Service and Pooled IO Service. This is the reccomended configuration and is the default from v2.5.0 on - there is no need for additional configuration to use it.

Multiplexing IO Service (Obsolete)

Multiplexing is when a single TCP connection is used by multiple threads to send and receive requests simultaneously. The benefit’s are improved throughput with less strain on the OS resources and importantly, a reduction on the number of TCP connections between the client and the server. The Multiplexing IO Service is the default IO Service if no custom configuration is provided.

Pooled IO Service (SSL only)

Pooled is when the SDK maintains a pool of TCP sockets and each thread uses a single socket at one time for Memcached K/V operations (Get, Insert, Remove, etc.). The connection pool limit is capped by the MinSize and MaxSize configuration settings; if MaxSize has been reached, the SDK would wait for a connection to become available or it would return an OperationTimeout response.

Configuring the IO Service

The default IO Service as of v2.6.0 is Shared-Pooled IO Service w/MUX and is the reccomended IO Service to use for non-SSL/TLS. We do not recommend using any of the other IO services or changing the default settings for IO Services as described below.

To configure the IO Service in your configuration file you would set the connectionPool element and ioService elements. An example of setting the configuration file to use PooledIOService would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
   <configSections>
      <sectionGroup name="couchbaseClients">
         <section name="couchbase" type="Couchbase.Configuration.Client.Providers.CouchbaseClientSection, Couchbase.NetClient" />
      </sectionGroup>
   </configSections>
   <couchbaseClients>
      <couchbase enableConfigHeartBeat="false">
         <servers>
            <add uri="http://127.0.0.1:8091" />
         </servers>
         <connectionPool name="custom" type="Couchbase.IO.ConnectionPool`1[Couchbase.IO.Connection], Couchbase.NetClient" />
         <ioService name="multiplexio" type="Couchbase.IO.Services.PooledIOService, Couchbase.NetClient" />
      </couchbase>
   </couchbaseClients>
</configuration>

To configure the IO Service programmatically you would use the ClientConfiguration and setting the IOServiceCreator properties. An example that configures the Multiplexing IO Service would look like this:

var config = new ClientConfiguration
{
    Servers = newList<Uri>
    {
        new Uri(ConfigurationManager.AppSettings["bootstrapUrl"])
    }
};
config = ConnectionPoolFactory.GetFactory<ConnectionPool<MultiplexingConnection>>();
config.IOServiceCreator = IOServiceFactory.GetFactory<MultiplexingIOService>();
ClusterHelper.Initialize(config);

Caveats

A couple of caveats are in order:

  • SSL is not yet supported for MUX (JIRA ticket)

  • MUX has no effect on Views, N1QL or Full Text Search queries

  • Shared-Pooled IO Service w/MUX currently ignores the MinSize and creates the MaxSize of connections configured. This is a known issue/limitation and can be tracked by the following Jira ticket: https://issues.couchbase.com/browse/NCBC-1534