Start Using the SDK
Edit this article in GitHub
Version 2.3

Start Using the SDK

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

Installing the SDK

The following sections explain in detail how to get started using each method.

Installing the Client

The Couchbase .NET SDK is compatable with both Microsoft .NET Framework 4.5 or and Microsoft .NET Core runtimes. Microsoft Visual Studio 2013 or later is assumed in this guide, though you should use 2015 or later if possible. Add the Couchbase .NET SDK to your Visual Studio solution using one of the following methods:

  • Using NuGet (recommended method)
  • Downloading and referencing the binaries
  • Building from source yourself

Information on new features, fixes, known issues as well as information on how to install older release versions is in the release notes.

The following sections explain in detail how to get started using each method.

Using NuGet

For every release, we package the binaries and store the latest version in NuGet. If you are not familiar with NuGet, it’s the official and most widely supported package manager for Microsoft Visual Studio and .NET in general. NuGet is a centralized repository for package authors and consumers, and it also defines a suite of tools for authoring and consuming packages.

Using Visual Studio 2013 or later, follow these steps to get started with the Couchbase .NET SDK:

  1. From the IDE, right-click the project you want to add the dependency to.
  2. In the context menu, click Manage NuGet Packages. The NuGet package manager modal dialog opens.
  3. From the Tree View menu on the left, select Online > nuget.org.
  4. In the search box at the top right-hand side of the dialog, type CouchbaseNetClient and then press enter on your keyboard.
  5. In the search results, select the CouchbaseNetClient package and then click Install.

That’s it! NuGet will pull in all required dependencies and reference them. You're ready to start coding!

As an alternative to using the Visual Studio IDE, you can include the binaries by using the Package Manager Console. The main advantage of using the Package Manager Console is that the NuGet Dialog by default always installs the latest version of the package published to NuGet.org, however the console allows you to define the version of the package you want to include. For users targeting older builds of the SDK, using the Package Manager Console is the best option.

To use the Package Manager Console to include the SDK in your project:

  1. From the Visual Studio menu bar, click Tools.
  2. Select NuGet Package Manager > Package Manager Console.
  3. In the console, enter the package installation command:
    • To install the latest version:
      Install-Package CouchbaseNetClient
    • To install a specific version, include the version parameter. For example:
      Install-Package CouchbaseNetClient -Version 2.0.0 -Pre

Downloading and referencing the binaries

If you do not want to use NuGet to include the Couchbase .NET SDK in your project, you can download and reference the binaries directly. If you chose this route, you’ll also be responsible for including and resolving dependencies used internally by the SDK.

To download and reference the binaries directly:

  1. Download the version of the SDK you want to install - Releases
  2. In Visual Studio, right-click the project you want to include the SDK in and then click Add.
  3. Click Reference to open the Reference Manager.
  4. On the left side, click Browse and select the binaries you downloaded.
  5. Click OK.

After you have referenced the Couchbase .NET SDK binaries, you need to locate and reference the dependencies it uses in a similar fashion.

.NET Framework dependencies are:

.NET Core dependencies are:

Other versions might not be compatible with the current SDK version.

Building from source

If none of the other installation options suffice or if you want to debug the source or perhaps contribute, building directly from the source is the best option for you. All source is located on GitHub.

Note:

The software provided via NuGet and S3 are the official releases that have been through a rigorous testing process. Code on GitHub that is not tagged as an official release is still in development.

To build the .NET SDK from source:

  1. (Optional) Fork the GitHub repository: https://github.com/couchbase/couchbase-net-client/fork
  2. Using a Git console, enter the command to clone the repository:
    git clone https://github.com/couchbase/couchbase-net-client.git
  3. Enter the command to retrieve the latest code from GitHub:
    git pull origin master
  4. Navigate to the directory that the source was cloned to and open the solution.
  5. Build the solution.

After you have successfully built the source, it’s then just a matter of referencing the binaries (.DLL files) from your consuming project.

Hello Couchbase

This tutorial creates a simple console application using Visual Studio that illustrates the most basic usage of the Couchbase .NET SDK.

To begin, open Visual Studio and create a new Console Application Project called Couchbase.HelloCouchbase:

This creates a simple executable with a main() method that you can use to try reading and writing from a Couchbase Cluster.

Next, use the NuGet Package Manager to reference the Couchbase .NET SDK and its dependencies:

At this point, you should be ready to go. Add a Cluster object, which represents a factory and resource manager for Couchbase buckets. This is added to the Program.cs file that was added automatically by Visual Studio when the project was created:

Creating the Cluster and Bucket
internal class Program
{
	private static readonly Cluster Cluster = new Cluster();

	private static void Main(string[] args)
	{
		using (var bucket = Cluster.OpenBucket())
		{
			...
		}
	}
}

The default OpenBucket() overload with no parameters opens the default bucket. Additionally, because the default constructor is used to create the Cluster object, the app connects to the localhost (127.0.0.1) instance of Couchbase Server.

The CouchbaseBucket object (as well as the Cluster object) implements the dispose pattern. Because of this, the instance is wrapped in a using statement, which means that the internal resources allocated by the instance will be reclaimed as the bucket instance goes out of scope. Managing the lifetime or scope of these objects is critical to developing high-performing, robust applications with the .NET SDK.

Now that you have connected to a Couchbase bucket, you can create a document and add it to the database:

Storing and Getting a document
using (var bucket = Cluster.OpenBucket())
{
	var document = new Document<dynamic>
	{
		Id = "Hello",
		Content = new
		{
			name = "Couchbase"
		}
	};

	var upsert = bucket.Upsert(document);
	if (upsert.Success)
		{
			var get = bucket.GetDocument<dynamic>(document.Id);
			document = get.Document;
			var msg = string.Format("{0} {1}!", document.Id, document.Content.name);
			Console.WriteLine(msg);
		}
	Console.Read();
}

First, the code creates a new Document object, types it as dynamic and provides an Id value. Then, it creates the actual value that will be stored as JSON in Couchbase and assigns it to the Content property. After the Document object is created, it uses the Upsert() method to store it into the database. Finally, it checks whether the operation was successful and if it is, does a GetDocument() operation to retrieve the document and formats a string with the Id of the document and the Name property from the Content field (the actual JSON document).

If you build and run this from Visual Studio, you should see the following message output:

Hello Couchbase!

Congratulations, you have successfully created the Hello Couchbase Tutorial! The full source can be found on GitHub.

API Reference

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

Contributing

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