Getting Started with Couchbase .NET SDK 1.3

Introduction

This guide provides information for developers who want to use the Couchbase .NET SDK to build applications that use Couchbase Server.

Beginning with the 1.2.5 release, Couchbase .NET Client Library supports .NET Framework versions 3.5 and 4.0.

Downloading the software

To get the software:

Download and install Couchbase Server.
Get the client library by using one of the following methods:
Download the zip file from the Couchbase .NET community Getting Started page.
Run the following command in the NuGet package manger console:

PM> Install-Package CouchbaseNetClient

Setting up a project

Create a new console project in Visual Studio. Add references to the Couchbase.dll, Enyim.Memcached.dll, Newtonsoft.Json.dll, andRestSharp.dll assemblies that are in the release zip file.

Visual Studio console applications target the .NET Framework Client Profile by default, so you need to change the project properties to target the full .NET Framework. If you skip this step, you’ll have compilation errors.

Adding configuration

You can configure your Couchbase client either programmatically or using the app.config file with the appropriate Couchbase configuration section. Using app.config s more flexible and is the preferred approach. Modify your app.config file as follows:

<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="couchbase" type="Couchbase.Configuration.CouchbaseClientSection, Couchbase"/>
  </configSections>
  <couchbase>
    <servers bucket="default" bucketPassword="">
      <add uri="http://192.168.0.2:8091/pools"/>
      <add uri="http://192.168.0.3:8091/pools"/>
    </servers>
  </couchbase>
</configuration>

The URIs in the servers list are used by the client to obtain information about the cluster configuration. If you’re running on your local development machine, include only a single URI and use 127.0.0.1 as the address.

The bucket and bucketPassword attributes are optional because the default Couchbase Server installation creates a bucket named default that does not use a password. If you create an authenticated bucket, you must specify those values in place of the default settings shown in the example.

By default, the TCP/IP port allocation on Windows includes a restricted number of ports available for client communication. For more information on this issue, including information about how to adjust the configuration and increase the available ports, see MSDN: Avoiding TCP/IP Port Exhaustion.

Instantiating the Client

To instantiate the client, add the following using statements to the Program.cs file:

using Couchbase;
using Enyim.Caching.Memcached;
using Newtonsoft.Json;

Couchbase is the namespace containing the client and configuration classes with which you’ll work. Enyim.Caching.Memcached contains supporting infrastructure. Because Couchbase supports the memcached protocol, it can make use of the popular EnyimMemcached client for many of its core key-value operations.

Next, create an instance of the client in the Main method. Use the default constructor, which depends on the configuration from theapp.config file.

var client = new CouchbaseClient();

In practice, it’s expensive to create clients. The client incurs overhead as it creates connection pools and sets up the thread to get cluster configuration. Therefore, the best practice is to create a single client instance, per bucket, per AppDomain. Creating a static property on a class works well for this purpose. For example:

public static class CouchbaseManager
{
   private readonly static CouchbaseClient _instance;
 
   static CouchbaseManager()
   {
       _instance = new CouchbaseClient();
   }
 
   public static CouchbaseClient Instance { get { return _instance; } }
}

However, for the purpose of this getting started section, the locally scoped client variable created above is sufficient.

Performing CRUD Operations

The primary CRUD API used by the .NET Client is a standard key-value store. You create and update documents by supplying a key and value. You retrieve or remove documents by supplying a value. For example, consider the following JSON document that you’ll find in the beer-sample bucket that’s available when you install Couchbase Server and set up your cluster. The key for this document is new_holland_brewing_company-sundog.

{
 "name": "Sundog",
 "abv": 5.25,
 "ibu": 0,
 "srm": 0,
 "upc": 0,
 "type": "beer",
 "brewery_id": "new_holland_brewing_company",
 "updated": "2010-07-22 20:00:20",
 "description": "Sundog is an amber ale as deep as the copper glow of a Lake Michigan sunset. Its biscuit malt give Sundog a toasty character and a subtle malty sweetness. Sundog brings out the best in grilled foods, caramelized onions, nutty cheese, barbecue, or your favorite pizza.",
 "style": "American-Style Amber/Red Ale",
 "category": "North American Ale"
}

To retrieve this document, if you are using local machine installation, you should update your app.config,

<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="couchbase" type="Couchbase.Configuration.CouchbaseClientSection, Couchbase"/>
  </configSections>
  <couchbase>
    <servers bucket="beer-sample" bucketPassword="">
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
  </couchbase>
</configuration>

and call the Get method of the client:

var savedBeer = client.Get("new_holland_brewing_company-sundog");

If you add a line to print savedBeer to the console, you should see a JSON string that contains the data from the JSON document.

var savedBeer = client.Get("new_holland_brewing_company-sundog");
Console.WriteLine(savedBeer);