You are viewing the documentation for a prerelease version.

View Latest

Install and Start Using the .NET SDK with Couchbase Server

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

These pages cover the Alpha of the Couchbase .NET SDK. As such they are likely to change without notice. This alpha code should not be used in production.

Documentation is incomplete, subject to change, and likely to contain broken links.

The Couchbase .NET client allows applications to connect to the Couchbase Data Platform 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 .NET Standard 2.0, which in turn supports .NET Framework 4.6.2+ and .NET Core (eg netcoreapp). The library is distributed in a number of ways:


Nuget package host at (recommended)


Zip file with can be downloaded [here]

Build from Source

Build the library from source

Hello Couchbase

Now you have the .NET client installed, open a fresh project in VS Code, and try out the following:

var config = new Configuration()
    .WithCredentials("username", "password")

Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings — but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be couchbase://localhost.

var cluster = new Cluster(config);
var bucket = await cluster.Bucket("bucket-name");

If you installed the travel sample data bucket, substitute travel-sample for bucket-name.

var collection = await bucket.DefaultCollection;

The 3.0 SDK is ready for the introduction of Collections in Cheshire Cat, the next release of the Couchbase Data Platform. The latest release, Mad Hatter, 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.

var upsertResult = await collection.Upsert("my-document", new {name = "mike"});
var getResult = await collection.Get("my-document");

KV Operations are described in detail on the KV Operations page. Now that you know the basics, you may wish to go straight to that page.

The Developer Preview version of the 3.0 .NET Client is entirely asynchronous — synchronous alternatives may be added in the future.

Additional Resources

The API reference is generated for each release and can be found here.

Couchbase welcomes community contributions to the .NET SDK. The .NET SDK source code is available on GitHub.