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.

Hello Couchbase

On this page we show you how to quickly get up and running — installing the Couchbase .NET SDK, and trying out the C# Hello World code example against Couchbase Capella, or against a local Couchbase cluster.

We will go through the code sample step by step, but for those in a hurry to see it, here it is:

Couchbase Capella Sample

If you are connecting to Couchbase Capella, be sure to get the correct endpoint as well as user, password — and see the Cloud section, below.

using System;
using System.Threading.Tasks;
using Couchbase;

await new CloudExample().Main();

class CloudExample
{
    public async Task Main()
    {
        var cluster = await Cluster.ConnectAsync(
            // Update these credentials for your Capella instance!
            "couchbases://cb.njg8j7mwqnvwjqah.cloud.couchbase.com",
            new ClusterOptions
            {
                UserName = "username",
                Password = "Password!123",
                KvTimeout = TimeSpan.FromSeconds(10)
            });

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

        // get a user-defined collection reference
        var scope = await bucket.ScopeAsync("tenant_agent_00");
        var collection = await scope.CollectionAsync("users");

        // 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>());

        // Call the QueryAsync() function on the cluster object and store the result.
        var queryResult = await cluster.QueryAsync<dynamic>("select \"Hello World\" as greeting");
        
        // Iterate over the rows to access result data and print to the terminal.
        await foreach (var row in queryResult) {
            Console.WriteLine(row);
        }
    }
}

The Couchbase Capella free trial version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

Local Couchbase Server

using System;
using System.Threading.Tasks;
using Couchbase;

namespace examples
{
    class StartUsing
    {
        static async Task Main(string[] args)
        {

            var cluster = await Cluster.ConnectAsync(
                // Update these credentials for your Local Couchbase instance!
                "couchbase://localhost",
                "username",
                "password");

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

            // get a user-defined collection reference
            var scope = await bucket.ScopeAsync("tenant_agent_00");
            var collection = await scope.CollectionAsync("users");

            // 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>());

            // Call the QueryAsync() function on the cluster object and store the result.
            var queryResult = await cluster.QueryAsync<dynamic>("select \"Hello World\" as greeting");
            
            // Iterate over the rows to access result data and print to the terminal.
            await foreach (var row in queryResult) {
                Console.WriteLine(row);
            }

        }
    }
}

As well as the .NET SDK (see below), and a running instance of Couchbase Server, you will need to load up the Travel Sample Bucket using either the Web interface or the command line.

Installing the SDK

Requirements

The Couchbase .NET SDK is compatible with .NET Standard 2.0 and .NET Standard 2.1, which means that it is compatible with .NET Framework 4.6.2+, .NET 5.0, .NET 6.0, and .NET Core 3.1. The .NET Standard documentation and .NET Standard version chart may be useful to help understand other available options.

We strongly recommend using the latest version of .NET that is officially supported by Microsoft. Other .NET implementations might work but are not tested and are outside of the scope for technical support. See the Compatibility section for more details.

Quick Installation

The quickest way to get up and running is with NuGet, from the Package Manager Console, within your project:

From the Visual Studio menu bar, click Tools.
Select NuGet Package Manager > Package Manager Console.
In the console, enter the package installation command:
- To install the latest version:

Install-Package CouchbaseNetClient

All other installation methods can be found in our full installation guide.

Step by Step

Start a new console project (in Visual Studio or VS Code, etc). Go to our Platform Introduction if you don’t already have an editor or IDE setup for working in .NET — e.g. you are evaluating the .NET SDK, but .NET is not your normal platform.

Prerequisites

Install the latest 3.3 CouchbaseNetClient NuGet package — see above.

The following code samples assume:

Couchbase Capella cluster, or 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). Note, the Travel Sample bucket is installed automatically by the Capella free trial.
You have created a Couchbase user named "username" [change as appropriate] 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;

Connection

Then you can connect to the cluster:

Capella Connection
Local Server Connection

var cluster = await Cluster.ConnectAsync(
    // Update these credentials for your Capella instance!
    "couchbases://cb.njg8j7mwqnvwjqah.cloud.couchbase.com",
    new ClusterOptions
    {
        UserName = "username",
        Password = "Password!123",
        KvTimeout = TimeSpan.FromSeconds(10)
    });

From 3.3, the .NET SDK includes Capella’s standard certificates by default, so you do not need to additional configuration. You do need to enable TLS, which can be done by simply using couchbases: in the Connection String as in this example.

var cluster = await Cluster.ConnectAsync(
    // Update these credentials for your Local Couchbase instance!
    "couchbase://localhost",
    "username",
    "password");

For developing locally on the same machine as the Couchbase Server, your URI can be couchbase://localhost as here. But for Production deployments, you will want to use a secure server, with couchbases://.

See Managing Connections for full configuration details.

Couchbase uses Role Based Access Control (RBAC) to control access to resources.

Bucket, Scopes, and Collections

Open the bucket:

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

Collections allow Documents to be grouped by purpose or theme, according to specified Scope. Our Travel Sample bucket has separate scopes for inventory (flights, etc.), and for tenants (different travel agents).

// get a user-defined collection reference
var scope = await bucket.ScopeAsync("tenant_agent_00");
var collection = await scope.CollectionAsync("users");

To get you started the following code creates a new document in a custom scope and collection 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 SQL++ (formerly N1QL) query with the cluster object:

// Call the QueryAsync() function on the cluster object and store the result.
var queryResult = await cluster.QueryAsync<dynamic>("select \"Hello World\" as greeting");

// Iterate over the rows to access result data and print to the terminal.
await foreach (var row in queryResult) {
    Console.WriteLine(row);
}

You can learn more about SQL++ queries on the Query page.

Next Steps

Now you’re up and running, try one of the following:

Our Travel Sample Application demonstrates all the basics you need to know;
Explore Key Value Operations against a document database;
Or Query with our SQL-based SQL++ language;
Or read up on which service fits your use case.

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 from our earlier 2.x .NET SDK.

Troubleshooting

Couchbase Server is designed to work in the same WAN or availability zone as the client application. If you’re running the SDK on your laptop against a Capella cluster, see further information on:
- Notes on Constrained Network Environments.
- Network Requirements.
- If you have a consumer-grade router which has problems with DNS-SRV records review our Troubleshooting Guide.
Our community forum is a great source of help.