A newer version of this documentation is available.

View Latest

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" password="secret">
              <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. In some circumstances, changing to true will increase performance. You can use Query Workbench to see how fast the response should be, then change the setting here if, with `Expect100Continue' set to false, the SDK is considerably slower.

    false

    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)

    • Since MUX uses a single connection per node for Memcached (K/V) operations, some of the connection pool settings no longer apply, these are:

      • MinSize

      • MaxSize

      • WaitTimeout

    • 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