Programmatic configuration

The client comes with a set of default values for its configuration. For the most part, these defaults are satisfactory for most development and production use, however, these values can be modified or overridden as needed to tune the client to specific use-cases and scenarios. The client can be configured in one of two ways: programmatically through the ClientConfiguration object or through the App.Config or Web.Config.

The ClientConfiguration object

The client can be configured programmatically using the ClientConfiguration class and passing the custom configuration through one of the Cluster constructor overloads. Through the ClientConfiguration you can also configure individual buckets and their connection pools.

Here is an example of overriding the default configuration settings with several overrides:

var config = new ClientConfiguration
{
  Servers = new List<Uri>
  {
    new Uri("http://192.168.56.101:8091/pools"),
    new Uri("http://192.168.56.102:8091/pools"),
    new Uri("http://192.168.56.103:8091/pools"),
    new Uri("http://192.168.56.104:8091/pools"),
  },
  UseSsl = true,
  BucketConfigs = new Dictionary<string, BucketConfiguration>
  {
    {"default", new BucketConfiguration
    {
      BucketName = "default",
      UseSsl = false,
      Password = "",
      PoolConfiguration = new PoolConfiguration
      {
        MaxSize = 10,
        MinSize = 5
      }
    }}
  }
};

using (var cluster = new Cluster(config))
{
  IBucket bucket = null;
  try
  {
    bucket = cluster.OpenBucket();
    //use the bucket here
  }
  finally
  {
    if (bucket != null)
    {
      cluster.CloseBucket(bucket);
    }
   }
  }
}
		

At the top of the snippet, the code creates the ClientConfiguration object and uses property initializers to override the default settings. It then creates the bootstrap list of servers for initiating communication between the client and the cluster. The client attempts to bootstrap off of each of these servers. When it successfully connects with one of the servers in this list, the bootstrapping process ends.

Why add more than one server to the bootstrap (Servers) list? It’s possible that one or more of the servers in that list might not be part of the cluster at the time the client is created. By providing a range of nodes as bootstrap candidates, the likelihood of the client finding a suitable node to connect to increases. After the client successfully bootstraps, it receives a server configuration of the current state of the cluster. It uses this server configuration to update the bootstrap list by adding any additional candidate bootstrap servers to it.

Here are all of the ClientConfiguration members and their defaults:

In the ClientConfiguration example code snippet, the UseSsl property is set to true, indicating that all traffic between the client and the cluster will be encrypted. To use this feature, the server hosting the application needs to have the appropriate certificate installed and the cluster must be Couchbase Server version 3.0 or later. For more detail, please see: [link to installing certs].

In the example above, we are specifying a configuration for the “default” bucket. Providing a bucket level configuration will override any configuration settings set at the cluster level. The BucketConfiguration members and their defaults are as follows:

Finally, in the ClientConfiguration example code snippet, it provides a new PoolConfiguration, which overrides the default MaxSize and MinSize of 2 and 1 respectively, with the values 5 and 2. This means that the pool will start with 2 TCP connections and grow to 5 TCP connections on demand.

The rest of the PoolConfiguration members and their defaults:

The example source can be found on GitHub here.

Configuration with an App.Config or Web.Config

As an alternative to using programmatic configuration, you can also configure the client through an App.config or Web.config. The following snippet illustrates how you would do so:

<?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 useSsl="false">
      <servers>
        <add uri="http://192.168.56.101:8091/pools"></add>
        <add uri="http://192.168.56.102:8091/pools"></add>
        <add uri="http://192.168.56.103:8091/pools"></add>
        <add uri="http://192.168.56.104:8091/pools"></add>
      </servers>
      <buckets>
        <add name="default" useSsl="false" password="">
          <connectionPool name="custom" maxSize="10" minSize="5"></connectionPool>
        </add>
      </buckets>
    </couchbase>
  </couchbaseClients>
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.1" />
    </startup>
</configuration>
		

This the same configuration programmatically defined earlier in this section using the ClientConfiguration class.

To use this configuration, you need to use one of the special Cluster constructors that takes a string containing the path of the configuration:

using (var cluster = new Cluster("couchbaseClients/couchbase"))
{
  using (var bucket = cluster.OpenBucket())
  {
    //use the bucket here
  }
}
			

That the string couchbaseClients/couchbase matches the path of the sectionGroup and section elements in the App.config defined above. This example can be found on Github here.