Install and Start Using the .NET SDK with Couchbase Server

    +
    The Couchbase .NET SDK enables you to interact with a Couchbase Server cluster from .NET using C# and other .NET languages. It offers an asynchronous API based on the Task-based Asynchronous Pattern (TAP).

    The Couchbase .NET client allows applications to connect to Couchbase Server using any Common Language Runtime (CLR) language, including C#, F#, and VB.NET. The SDK is written in C#, and some of its idiomatic patterns reflect that choice.

    Installing the SDK

    The Couchbase .NET SDK targets and is tested with .NET Standard 2.0, which in turn supports .NET Framework 4.6.2+ and .NET Core (e.g. netcoreapp) 2.1. The library is distributed in a number of ways:

    NuGet

    NuGet package host at nuget.org (recommended)

    Zip

    Zip files for each release are linked from the Release Notes here.

    Build from Source

    Build the library from source available on GitHub (not officially supported)

    Hello Couchbase

    Start a new console project (in Visual Studio or VS Code, etc). Install the latest 3.0 CouchbaseNetClient NuGet package.

    The following code samples assume:

    • Couchbase Server is installed and accessible locally (Do a Quick Install if you don’t already have Couchbase Server installed).

    • You have create a bucket (perhaps using the travel-sample dataset, or by creating a new bucket).

    • You have created a Couchbase user named "username" with permissions to access the cluster (at least Application Access permissions).

    Firstly, you will need to have a few using statements at the top of Program.cs in your console program:

    using System.Threading.Tasks;
    using Couchbase;

    Then you can connect to the cluster:

    var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "password");

    Couchbase uses Role Based Access Control (RBAC) to control access to resources. If you’re developing client code on the same machine as the Couchbase Server, your URI can be couchbase://localhost.

    Then open the bucket:

    // get a bucket reference
    var bucket = await cluster.BucketAsync("bucket-name");

    Substitute whatever bucket name you want for bucket-name in the above example.

    The 3.0 SDK is ready for the introduction of Collections in an upcoming release of the Couchbase Data Platform. The latest release, Couchbase Server 6.5, brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to specified Scope. Here we will use the DefaultCollection, which covers the whole Bucket and must be used when connecting to a 6.5 cluster or earlier.

    // get a collection reference
    var collection = bucket.DefaultCollection();

    To get you started the following code creates a new document and then fetches it again, printing the result.

    // Upsert Document
    var upsertResult = await collection.UpsertAsync("my-document-key", new { Name = "Ted", Age = 31 });
    var getResult = await collection.GetAsync("my-document-key");
    
    Console.WriteLine(getResult.ContentAs<dynamic>());

    Other possible key/value CRUD Operations are described in detail on the KV Operations page.

    You can also perform a N1QL query with the cluster object:

    var queryResult = await cluster.QueryAsync<dynamic>("select \"Hello World\" as greeting");
    await foreach (var row in queryResult) {
        Console.WriteLine(row);
    }

    You can learn more about N1QL queries on the Query page.

    Full Example

    If you want to copy and paste to run the full example, here it is:

    using System;
    using System.Threading.Tasks;
    using Couchbase;
    
    namespace examples
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                var cluster = await Cluster.ConnectAsync("couchbase://localhost", "username", "password");
                var bucket = await cluster.BucketAsync("bucket-name");
                var collection = bucket.DefaultCollection();
    
                var upsertResult = await collection.UpsertAsync("my-document-key", new { Name = "Ted", Age = 31 });
                var getResult = await collection.GetAsync("my-document-key");
                Console.WriteLine(getResult.ContentAs<dynamic>());
    
                var queryResult = await cluster.QueryAsync<dynamic>("select \"Hello World\" as greeting", new Couchbase.Query.QueryOptions());
                await foreach (var row in queryResult) {
                    Console.WriteLine(row);
                }
            }
        }
    }

    Additional Resources

    The API reference is generated for each release. Older API references are linked from their respective sections in the Release Notes.

    The Migrating from SDK2 to 3 page highlights the main differences to be aware of when migrating your code.