Managing Connections using the .NET SDK with Couchbase Server

    +
    This section describes how to connect the .NET SDK to a Couchbase cluster. It contains best practices as well as information on TLS/SSL and other advanced connection options.

    Connecting to a Cluster

    A connection to a Couchbase Server cluster is represented by a Cluster object. A Cluster provides access to Buckets, Scopes, and Collections, as well as various Couchbase services and management interfaces. The simplest way to create a Cluster object is to call Cluster.ConnectAsync() with a connection string, username, and password:

    var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "passord");
    var bucket =  await cluster.BucketAsync("travel-sample");
    var collection = bucket.DefaultCollection();
    
    // You can access multiple buckets using the same Cluster object.
    var anotherBucket = await cluster.BucketAsync("beer-sample");
    
    // You can access collections other than the default
    // if your version of Couchbase Server supports this feature.
    var customerA = bucket.Scope("customer-a");
    var widgets = customerA.Collection("widgets");
    
    // For a graceful shutdown, disconnect from the cluster when the program ends.
    await cluster.DisposeAsync();
    If you are connecting to a version of Couchbase Server older than 6.5, it will be more efficient if the addresses are those of data (KV) nodes. You will in any case, with 6.0 and earlier, need to open a `Bucket instance before connecting to any other HTTP services (such as Query or Search.

    In a production environment, your connection string should include the addresses of multiple server nodes in case some are currently unavailable. Multiple addresses may be specified in a connection string by delimiting them with commas:

    var cluster = await Cluster.ConnectAsync("192.168.56.101,192.168.56.102", "username", "password");
    You don’t need to include the address of every node in the cluster. The client fetches the full address list from the first node it is able to contact.

    Connection Strings

    A Couchbase connection string is a comma-delimited list of IP addresses and/or hostnames, optionally followed by a list of parameters.

    The parameter list is just like the query component of a URI; name-value pairs have an equals sign (=) separating the name and value, with an ampersand (&) between each pair. Just as in a URI, the first parameter is prefixed by a question mark (?).

    Simple connection string with one seed node
    127.0.0.1
    Connection string with two seed nodes
    nodeA.example.com,nodeB.example.com
    Connection string with two parameters
    127.0.0.1?io.networkResolution=external&timeout.kvTimeout=10s

    Currently, as of .NET SDK Version 3.0.2 there is only partial mapping of query parameters to options properties. This will change in future versions and the entire list of mappings will be found in the client settings reference.

    A connection string may optionally be prefixed by either "couchbase://" or "couchbases://". If "couchbases://" is used, the client will use secure connections (TLS/SSL) if a valid certificate is configured or you can use the ClusterOptions.EnableTls flag.

    Connection Lifecycle

    Most of the high-level classes in the .NET SDK are designed to be safe for concurrent use by multiple threads. You will get the best performance if you share and reuse instances of Cluster, Bucket, Scope, and Collection, all of which are thread-safe.

    We recommend creating a single Cluster instance when your application starts up, and sharing this instance throughout your application. If you know at startup time which buckets, scopes, and collections your application will use, we recommend obtaining them from the Cluster at startup time and sharing those instances throughout your application as well.

    Before your application stops, gracefully shut down the client by calling the Dispose method of each Cluster you created. In older applications this can be done in Application_Start and Application_End in your Global.asax file. For newer applictions we suggest using Dependency Injection and Startup.cs file.

    Dependency Injection

    There is a special NuGet package to help you get started with Dependency Injection (DI).

    Working in the Cloud

    For most use cases, connecting client software using a Couchbase SDK to the new Couchbase Cloud service is similar to connecting to an on-premises Couchbase Cluster. The use of DNS-SRV. Altermate Address, and TLS is covered above.

    We strongly recommend that the client and server are in the same LAN-like environment (e.g. AWS Availability Zone). As this may not always be possible during development, read the guidance on working with constrained network environments. More details on connecting your client code to the Couchbase Cloud can be found in the Cloud docs.

    Troubleshooting Connections to Cloud

    Some DNS caching providers (notably, home routers) can’t handle an SRV record that’s large — if you have DNS-SRV issues with such a set-up, reduce your DNS-SRV to only include three records. [For development only, not production.]. Our Troubleshooting Cloud Connections page will help you to diagnose this and other problems — as well as introducing the SDK doctor tool.

    Additionally, in certain situations ClusterOptions.IgnoreRemoteCertificateNameMismatch may also need to be true.