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 Beta release of Couchbase .NET SDK 3.0. The API interface is stable, but could change for bug fixes during the Beta process. New features are likely to be added.

Documentation is incomplete, subject to change, and could 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. The .NET SDK 3.0 is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 6.5 as a developer preview). The API is now fully async.

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) 2.1. 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 here (not officially supported)

In VS Code, with the NuGet Package Manager Extension, open the command palette and type "nuget", then "CouchbaseNetClient", and select the latest 3.0 version available.

Hello Couchbase

Now you have the .NET client installed, open a fresh project in VS Code, and try out the following, which assumes a user named "user" with permissions to access the cluster, typically the "Application Access" role:

using Couchbase;
var cluster = Cluster.Connect("couchbase://localhost", "user", "pass");

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

var bucket = await cluster.BucketAsync("bucket-name");

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

var collection = 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.UpsertAsync("doc1", new {Name = "Ted", Age = 31});
var getResult = await collection.GetAsync("doc1");

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, following modern .NET development recommendations.

Additional Resources

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

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