Introduction¶

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

Getting Started¶

This chapter will get you started with using Couchbase Server and the.NET (C#) Client Library.

As of release 1.2.5, the Couchbase.NET Client Library supports.NET Framework versions 3.5 and 4.0.

Get a Server¶

Get & Install Couchbase Server. Come back here when you’re done

Get a Client Library¶

It can either be downloaded as a zipfile or run the following in the NuGet Package Manger console:

PM> Install-Package CouchbaseNetClient

Try it Out!¶

Project Setup¶

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

Visual Studio console applications target the.NET Framework Client Profile by default, so you’ll need to update the project properties to instead 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 config section. Using app.config is 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 dev machine, include only a single URI using 127.0.0.1 as the address.

The default Couchbase Server installation creates a bucket named “default” without a password, therefore the bucket and bucketPassword attributes are optional. If you created an authenticated bucket, you should specify those values in place of the default settings above.

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

Instantiating the Client¶

Add the following using statements to Program.cs:

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. Recall that Couchbase supports the Memcached protocol and is therefore able to make use of the popular Enyim Memcached 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 app.config.

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 guide the locally scoped client variable created above is sufficient.

CRUD Operations¶

The primary CRUD API used by the.NET Client is that of 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 JSON document that you’ll find in the “beer-sample” bucket that’s available when you install Couchbase Server and setup 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, you simply call the Get method of the client.

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

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

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

In this example, savedBeer would be of type Object. To get a string back instead and avoid having to cast, simply use the generic version of Get.

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

To add a document, first create a JSON string.

var newBeer =
@"{
   ""name"": ""Old Yankee Ale"",
   ""abv"": 5.00,
   ""ibu"": 0,
   ""srm"": 0,
   ""upc"": 0,
   ""type"": ""beer"",
   ""brewery_id"": ""cottrell_brewing"",
   ""updated"": ""2012-08-30 20:00:20"",
   ""description"": ""A medium-bodied Amber Ale"",
   ""style"": ""American-Style Amber"",
   ""category"": ""North American Ale""
}";

For a key, we’ll simply take the name of the beer and prefix it with the name of the brewery, separated with a dash and with spaces replaced by underscores. The exact mechanism by which you create your keys need only be consistent. If you are going to query documents by key (not just through views) you should choose predictable keys (e.g., cottrell_brewing-old_yankee_ale).

var key = "cottrell_brewing-old_yankee_ale";

With this new key, the JSON document may easily be stored.

var result = client.Store(StoreMode.Add, "cottrell_brewing-old_yankee_ale", newBeer);

There are three arguments to Store. The first is the store mode. Use StoreMode.Add for new keys, StoreMode.Replace to update existing keys and StoreMode.Set to add when a key doesn’t exist or to replace it when it does. Store will fail if Add is used with an existing key or Replace is used with a non-existent key. The second and third arguments are the key and value, respectively. The return value, assigned to the result variable, is a Boolean indicating whether the operation succeeded.

Removing a document simply entails calling the Remove method with the key to be removed. Like the other methods we’ve seen so far, Remove returns a Boolean indicating operation success.

var result = client.Remove("cottrell_brewing-old_yankee_ale");

Storing JSON Documents¶

While storing and retreiving JSON strings is a straightforward process, documents in a typical application are likely at some point to be represented by domain objects (i.e., POCOs). More mileage will come from storing some representation of these data objects. For example, the beer documents could be represented by an instance of a Beer class in memory. The.NET Client Library will allow for serializable objects to be persisted using.NET’s standard over-the-wire serialization. However, on the server, these objects will be stored as binary attachments to a JSON document. The impact of being an attachment is that it will not be indexed in a view. A better solution then, is to serialize data objects to JSON strings before storing them and deserializing JSON document strings to objects when retreiving them.

CouchbaseClient JSON Extension Methods¶

If you want an easy way to read and write JSON, the CouchbaseClientExtensions class under the Couchbase.Extensions namespace provides two very basic methods, StoreJson and GetJson. Both methods depend on the open source Newtonsoft.Json library, which is already a dependency of the Couchbase.NET Library. Both methods wrap only the most basic Get and Store overloads and don’t currently support CAS or TTL operations. They are included with the library for convenience and will likely be augmented in the future by a Couchbase Labs extension library.

To improve the way beer data is managed in this getting started project, add a new file Beer.cs to the project. It will contain a plain-old-CLR-object (POCO) with mappings from class properties to JSON properties. For brevity, some document properties have been omitted. Notice also that the Type property has been made read-only and forces all beer instances to be marked with the type “beer.” This type information will be useful when creating views and wanting to find all “beer” documents.

public class Beer
{
    [JsonProperty("name")]
    public string Name { get; set; }

    [JsonProperty("abv")]
    public float ABV { get; set; }

    [JsonProperty("type")]
    public string Type
    {
       get { return "beer"; }
    }

    [JsonProperty("brewery_id")]
    public string BreweryId { get; set; }

    [JsonProperty("style")]
    public string Style { get; set; }

    [JsonProperty("category")]
    public string Category { get; set; }
}

By default, Json.NET will serialize the properties of your class in the case you created them. Because we want our properties to match the casing of the documents in the beer-sample bucket, we’re going to set JSON property names in JsonProperty attributes (in the Newtonsoft.Json namespace). Again, we could store instances of this Beer class without converting them first to JSON (requires marking the class with a Serializable attribute), but that would prevent those documents from being indexed in views.

Persisting an instance as JSON is similar to how we persisted the JSON document string above. Replace the code where a JSON string was created with the code below.

var newBeer = new Beer
{
    Name = "Old Yankee Ale",
    ABV = 5.00f,
    BreweryId = "cottrell_brewing",
    Style = "American-Style Amber",
    Category = "North American Ale"
};

And to store the new instance, simply use the extension method. Result will return a Boolean indicating operation success.

var result = client.StoreJson(StoreMode.Set, key, newBeer);

Retrieving the Beer instance is also similar to retrieving a document as was demonstrated above.

var savedBeer = client.GetJson<Beer>(key);

At this point, your simple Program.cs file should look something like the following:

class Program
{
    static void Main(string[] args)
    {
        var client = new CouchbaseClient();
        var key = "cottrell_brewing-old_yankee_ale";

        var newBeer = new Beer
        {
            Name = "Old Yankee Ale",
            ABV = 5.00f,
            BreweryId = "cottrell_brewing",
            Style = "American-Style Amber",
            Category = "North American Ale"
        };

        var result = client.StoreJson(StoreMode.Set, key, newBeer);

        if (result)
        {
            var savedBeer = client.GetJson<Beer>(key);
            Console.WriteLine("Found beer: " + savedBeer.Name);
        }

    }
}

Working with Views¶

Map/Reduce Views are used to create queryable, secondary indexes in Couchbase Server. The primary index for documents is the key you use when performing the standard CRUD methods described above. See the view documentation for more information on writing views.

For this example, the by_name view in the beer design document will be queried. This view simply checks whether a document is a beer and has a name. If it does, it emits the beer’s name into the index. This view will allow for beers to be queried for by name. For example, it’s now possible to ask the question “What beers start with A?”

function (doc, meta) {
  if (doc.type && doc.type == "beer" && doc.name) {
     emit(doc.name, null);
  }
}

Querying a view through the.NET Client Library requires calling the GetView method and providing the name of the design document and the name of the view.

var view = client.GetView("beer", "by_name");

The return type of GetView is an enumerable IView, where each enumerated value is an IViewRow. The actual view query isn’t run until you enumerate over the view. For example, if you wanted to print out each of the keys that have been indexed, you could use the IViewRow instance’s Info dictionary. This particular view emits null as the value, so that will be empty when this snippet runs.

foreach (var row in view)
{
    Console.WriteLine("Key: {0}, Value: {1}", row.Info["key"], row.Info["value"]);
}

The code above should give you a list of beer names for all beer documents that exist in the beer-sample bucket. If you want to filter that list, there are fluent methods that may be chained off of the IView instance before iterating over it. Modifying the GetView call above as follows will find all beers whose names start with “A” and limits the results to 50 rows. See the API reference for other fluent methods. Please note that these methods return an IView instance, which is an IEnumerable, but is not an IQueryable. Therefore, using LINQ extension methods on the IView will not reduce the results in the query. Only the IView fluent methods will affect the query before it is run.

var view = client.GetView("beer", "by_name").StartKey("A").EndKey("B").Limit(50);

Also included in the IViewRow instance, is the original ID (the key from the k/v pair) of the document. It is accessible by way of the IViewRow’s ItemId property. Taking that ID, it is possible to retrieve the original document. Using the JSON extension methods, it’s also possible to get a Beer instance for each row. If it seems expensive to perform these lookups, recall that Couchbase Server has a Memcached layer built in and these queries are unlikely to be pulling data from disk. The documents are likely to be found in memory.

foreach (var row in view)
{
    var doc = client.GetJson<Beer>(row.ItemId);
    Console.WriteLine(doc.Name);
}

Finally, there is a generic version of GetView which encapsulates the details of the view row data structures. To retrieve Beer instances automatically by ID as you iterate over the view, you need to add the generic parameter to GetView along with the third Boolean argument to tell the client to perform the by ID lookup. If you omit the third parameter, the client will attempt to deserialize the value emitted by the index into an instance of the specified generic type. Again, in this example the value was null. Therefore, deserialization must be done by way of ID lookup.

var view = client.GetView<Beer>("beer", "by_name", true).StartKey("A").EndKey("B").Limit(50);

foreach (var beer in view)
{
    Console.WriteLine(beer.Name);
}

For more information about using views for indexing and querying from Couchbase Server, here are some useful resources:

• For more information on Views, how they operate, and how to write effective map/reduce queries, see Couchbase Server 2.0: Views and Couchbase Sever 2.0: Writing Views.

• Sample Patterns: to see examples and patterns you can use for views, see Couchbase Views, Sample Patterns.

• Timestamp Pattern: many developers frequently ask about extracting information based on date or time. To find out more, see Couchbase Views, Sample Patterns.

Couchbase and ASP.NET MVC¶

This tutorial will walk you through the steps of creating an ASP.NET MVC app using Couchbase. It will focus on practical design patterns, best practices along with general SDK usage.

Prerequisites¶

This tutorial assumes that you have Visual Studio 2010 installed, along with ASP.NET MVC 4. You may use any edition of Visual Studio or you may use Visual Web Developer. Visual Studio 2012 will also work for this tutorial, but the screenshots included will be from Visual Studio 2012 Professional.

You will also need to have an installation of Couchbase Server 2.0 and have obtained the latest Couchbase.NET Client Library, version 1.2 or higher. See “Getting Started” for more information on client installation.

You also may use an older version of ASP.NET MVC if you do not have MVC 4 installed, but as with using Visual Web Developer or Visual Studio 2012, the templates shown in the screenshots will vary from what you see.

You should also have installed the beer-sample database on your Couchbase Server. If you haven’t, simply open the web console and navigate to the “Settings” tab. There, you’ll find an option to add a sample bucket to your cluster.

Visual Studio Project Setup¶

This project will be based on an ASP.NET MVC 4 application template. After opening Visual Studio, select File -> New Project and then select Web -> ASP.NET MVC 4 Application under the Visual C# project templates. Name the project “CouchbaseBeersWeb” and click “OK” to create the solution.

Start with an “Empty” application using the Razor view engine for the MVC template.

Next you’ll need to add a reference to the Couchbase.NET Client Library. You could either download the assemblies from the getting started page or obtain them using the NuGet package manager. When you install via Nuget, your project will automatically get references to Couchbase.dll, Enyim.Caching.dll and the dependencies Newtonsoft.Json.dll and Hammock.dll. These assemblies are also found in the zip file and should be referenced in your project if not using Nuget.

Working with Models¶

The first task to solve is displaying a list of breweries in from our beer-sample bucket. To add this functionality, there is some plumbing to setup in our application. These tasks are enumerated below.

• Create a Brewery model class to represent beer documents

• Create a BreweryRepository to encapsulate data access for Brewery instances

• Create a BreweriesController with an Index action used to show a Brewery list

• Create a Razor view to display our list of breweries

As a JSON document database, Couchbase supports a natural mapping of domain objects to data items. In other words, there’s very little difference between the representation of your data as a class in C# and the representation of your data as a document in Couchbase. Your object becomes the schema defined in the JSON document.

When working with domain objects that will map to documents in Couchbase, it’s useful, but not required, to define a base class from which your model classes will derive. This base class will be abstract and contain two properties, “Id” and “Type.”

Right click on the “Models” directory and add a new class named “ModelBase” and include the following code.

public abstract class ModelBase
{
    public virtual string Id { get; set; }
    public abstract string Type { get; }
}

Note that the Type method is abstract and readonly. It will be implemented by subclasses simply by returning a hard-coded string, typically matching the class name, lower-cased. The purpose of the Type property is to provide taxonomy to the JSON documents stored in your Couchbase bucket. The utility will be more obvious when creating views.

Next, create a new class namedin the “Models” directory of your project. This class will be a plain old CLR object (POCO) that simply has properties mapping to the properties of brewery documents in the beer-sample bucket. It will also extend ModelBase.

public class Brewery : ModelBase
{
    public string Name { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Code { get; set; }
    public string Country { get; set; }
    public string Phone { get; set; }
    public string Website { get; set; }
    public DateTime Updated { get; set; }
    public string Description { get; set; }
    public IList<string> Addresses { get; set; }
    public IDictionary<string, object> Geo { get; set; }
    public override string Type
   {
        get { return "brewery"; }
   }
}

{
  "name": "Thomas Hooker Brewing",
  "city": "Bloomfield",
  "state": "Connecticut",
  "code": "6002",
  "country": "United States",
  "phone": "860-242-3111",
  "website": "http://www.hookerbeer.com/",
  "type": "brewery",
  "updated": "2010-07-22 20:00:20",
  "description": "Tastings every Saturday from 12-6pm, and 1st and 3rd Friday of every month from 5-8.",
  "address": [
    "16 Tobey Road"
  ],
  "geo": {
    "accuracy": "RANGE_INTERPOLATED",
    "lat": 41.8087,
    "lng": -72.7108
  }
}

Encapsulating Data Access¶

After creating the Brewery class, the next step is to create the data access classes that will encapsulate our Couchbase CRUD and View operations. Create a new file in “Models” named “RepositoryBase`1.cs” with a class name of “RepositoryBase.” This will be an abstract class, generically constrained to work with ModelBase instances. The `1 suffix on the file name is a convention used for generic classes in C# projects.

public abstract class RepositoryBase<T> where T : ModelBase
{
   //CRUD methods
}

The process of creating an instance of a CouchbaseClient is expensive. There is a fair amount of overhead as the client establishes connections to the cluster. It is therefore recommended to minimize the number of times that a client instance is created in your application. The simplest approach is to create a static property or singleton that may be accessed from data access code. Using the RepositoryBase, setting up a protected static property will provide access for subclasses.

public abstract class RepositoryBase<T> where T : ModelBase
{
    protected static CouchbaseClient _Client { get; set; }
    static RepositoryBase()
    {
        _Client = new CouchbaseClient();
    }
}

The code above requires setting configuration in web.config. It is of course equally valid to define the configuration in code if that is your preference. See getting started for more details.

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

Working with Views¶

To display a list of all breweries, a view will be necessary. This map function for this view will simply emit null keys and values for each of the brewery documents in the database. This view will live in a “breweries” design document and be named “all.”

For more information on working with views in the admin console, see the documentation.

function(doc, meta) {
    if (doc.type == "brewery") {
        emit(null, null);
    }
}

A null-key index still provides access to each of the document’s keys when the view is queried. Note however that range queries on keys would not be supported with this view.

You could create the “all” view above by creating a new design document in the Couchbase web console or you could use the CouchbaseCluster API ( see docs ) found in Couchbase.dll to create and to save a design document. However, an easier approach is to use the CouchbaseLabs project Couchbase Model Views.

The Couchbase Model Views project is not part of the Client Library, but makes use of its design doc management API to create views from attributes placed on model classes. Using NuGet, add a reference to the CouchbaseModelViews package.

Once installed, modify the Brewery class definition to have two class level attributes, CouchbaseDesignDoc and CouchbaseAllView.

[CouchbaseDesignDoc("breweries")]
[CouchbaseAllView]
public class Brewery : ModelBase
{
    //props omitted for brevity
}

The CouchbaseDesignDoc attribute instructs the Model Views framework to create a design document with the given name. The CouchbaseAllView will create the “all” view as shown previously.

To get the Model Views framework to create the design doc and view, you’ll need to register the assembly containing the models with the framework. In Global.asax, create a static RegisterModelViews method for this purpose.

public static void RegisterModelViews(IEnumerable<Assembly> assemblies)
{
    var builder = new ViewBuilder();
    builder.AddAssemblies(assemblies.ToList());
    var designDocs = builder.Build();
    var ddManager = new DesignDocManager();
    ddManager.Create(designDocs);
}

Then in the existing Application_Start method, add a line to register the current assembly.

RegisterModelViews(new Assembly[] { Assembly.GetExecutingAssembly() });

Note that the Model Views framework will create the design doc only if it has changed, so you don’t have to worry about your indexes being recreated each time your app starts.

To test that the Model Views framework is working, simply run the application (Ctrl + F5). If all went well, you should be able to navigate to the “Views” tab in the Couchbase web console and see the new design doc and view in the “Production Views” tab (as shown below).

If you click the link next to the “Filter Results” button, you will see the JSON that is returned to the CouchbaseClient when querying a view. Notice the “id” property found in each row. That is the key that was used to store the document.

{"total_rows":1412,"rows":[
{"id":"21st_amendment_brewery_cafe","key":null,"value":null},
{"id":"357","key":null,"value":null},
{"id":"3_fonteinen_brouwerij_ambachtelijke_geuzestekerij","key":null,"value":null},
{"id":"512_brewing_company","key":null,"value":null},
{"id":"aass_brewery","key":null,"value":null},
{"id":"abbaye_de_leffe","key":null,"value":null},
{"id":"abbaye_de_maredsous","key":null,"value":null},
{"id":"abbaye_notre_dame_du_st_remy","key":null,"value":null},
{"id":"abbey_wright_brewing_valley_inn","key":null,"value":null},
{"id":"aberdeen_brewing","key":null,"value":null}
]
}

With the view created, the next step is to modify the RepositoryBase to have a GetAll method. This method will use some conventions to allow for reuse across subclasses. One of those conventions is that queries will be made to design docs with camel-cased and pluralized names (e.g., Brewery to breweries). To aid in the pluralization process, create a reference to inflector_extension using NuGet. Note that in.NET 4.5, there is a PluralizationService class that will provide some of the same support.

To the RepositoryBase class, add a readonly private field and initialize it to the inflected and pluralized name of the type of T. The inflector extension methods will require an additional using statement.

using inflector_extension;
private readonly string _designDoc;
public RepositoryBase()
{
    _designDoc = typeof(T).Name.ToLower().InflectTo().Pluralized;
}

The initial implementation of GetAll will simply return all breweries using the generic GetView<T> method of CouchbaseClient. The third parameter instructs CouchbaseClient to retrieve the original document rather than deserialize the value of the view row.

public virtual IEnumerable<T> GetAll()
{
    return _Client.GetView<T>(_designDoc, "all", true);
}

RepositoryBase is a generic and abstract class, so obviously it cannot be used directly. Create a new class in “Models” named “BreweryRepository.” The code for this class is very minimal, as it will rely on its base class for most functionality.

public class BreweryRepository : RepositoryBase<Brewery>
{
}

The Views and Controller¶

With the models and repository coded, the next step is to create the controller. Right click on the “Controllers” directory in the project and select Add -> Controller. Name the controller “BreweriesController” and select the template “Controller with empty read/write actions,” which will create actions for creating, updating, deleting, showing and listing breweries.

The Index method of the BreweriesController will be used to display the list of breweries. To allow the new controller to access brewery data, it will need an instance of a BreweryRepository. Create a public property of type BreweryRepository and instantiate it in the default constructor.

public BreweryRepository BreweryRepository { get; set; }
public BreweriesController()
{
    BreweryRepository = new BreweryRepository();
}

Then inside of the Index method, add a call to BreweryRepository ’s GetAll method and pass its results to the view as its model.

public ActionResult Index()
{
    var breweries = BreweryRepository.GetAll();
    return View(breweries);
}

The last step to displaying the list of breweries is to create the Razor view (as in MVC views, not Couchbase views). In the “Views” directory, create a new directory named “Breweries.” Right click on that new directory and select “Add” -> “View.” Name the view “Index” and create it as a strongly typed (to the Brewery class) view with List scaffolding. This template will create a Razor view that loops over the brewery results, displaying each as a row in an HTML table.

At this point, you should build your application and navigate to the Breweries path (e.g., http://localhost:52962/breweries ). If all went well, you should see a list of breweries.

There are quite a few breweries being displayed in this list. Paging will be an eventual improvement, but for now limiting the results by modifying the defaults of the GetAll method will be sufficient.

//in RepositoryBase
public IEnumerable<T> GetAll(int limit = 0)
{
    var view = _Client.GetView<T>(_designDoc, "all", true);
    if (limit > 0) view.Limit(limit);
    return view;
}
//in BreweriesController
public ActionResult Index()
{
    var breweries = BreweryRepository.GetAll(50);
    return View(breweries);
}

For more information about using views for indexing and querying from Couchbase Server, here are some useful resources:

• For technical details on views, how they operate, and how to write effective map/reduce queries, see Couchbase Server 2.0: Views and Couchbase Sever 2.0: Writing Views.

• Sample Patterns: to see examples and patterns you can use for views, see Couchbase Views, Sample Patterns.

• Timestamp Pattern: many developers frequently ask about extracting information based on date or time. To find out more, see Couchbase Views, Sample Patterns.

Brewery CRUD¶

The MVC scaffolding that created the Razor template to list breweries also included links to create, show, edit and delete breweries. Using more scaffolding, these CRUD features are easily implemented.

Create and Update methods require a bit of effort to encapsulate. One decision to make is whether to use the detailed result ExecuteStore method or the Boolean> Store method of the Client. ExecuteStore returns an instance of an IStoreOperationResult, which contains a success status and error message properties, among others.

Since it is likely important to know whether operations succeeded, ExecuteStore will be used in our RepositoryBase. However, that interface will be hidden from the application and instead an int will be returned by each method. The int will be the status code returned by Couchbase Server for each operation.

public virtual int Create(T value){}
public virtual int Update(T value) {}
public virtual int Save(T value) {}

There are other implementation details that need to be considered when implementing these methods, namely key creation and JSON serialization.

CRUD operations in Couchbase are performed using a key/value API. The key that is used for these operations may be either meaningful (i.e., human readable) or arbitrary (e.g., a GUID). When made human readable, your application may be able to make use of predictable keys to perform key/value get operations (as opposed to secondary indexes by way of view operations).

A common pattern for creating readable keys is to take a unique property, such as Brewery.Name, and replace its spaces, possibly normalizing to lowercase. So “Thomas Hooker Brewery” becomes “thomas_hooker_brewery.”

Add the following BuildKey method to the RepositoryBase to allow for default key creation based on the Id property.

protected virtual string BuildKey(T model)
{
    if (string.IsNullOrEmpty(model.Id))
    {
        return Guid.NewGuid().ToString();
    }
    return model.Id.InflectTo().Underscored;
}

BuildKey will default to a GUID string when no Id is provided. It’s also virtual so that subclasses are able to override the default behavior. The BreweryRepository needs to override the default behavior to provide a key based on brewery name.

protected override string BuildKey(Brewery model)
{
    return model.Name.InflectTo().Underscored;
}

When storing a Brewery instance in Couchbase Server, it first has to be serialized into a JSON string. An important consideration is how to map the properties of the Brewery to properties of the JSON document.

JSON.NET (from Newtonsoft.Json) will by default serialize all properties. However, ModelBase objects all have an Id property that shouldn’t be serialized into the stored JSON. That Id is already being used as the document’s key (in the key/value operations), so it would be redundant to store it in the JSON.

JSON.NET supports various serialization settings, including which properties should be included in serialization. In RepositoryBase, create a serializAndIgnoreId method and a private DocumentIdContractResolver class as shown below.

private string serializeAndIgnoreId(T obj)
{
    var json = JsonConvert.SerializeObject(obj,
        new JsonSerializerSettings()
        {
            ContractResolver = new DocumentIdContractResolver(),
        });
    return json;
}

private class DocumentIdContractResolver : CamelCasePropertyNamesContractResolver
{
    protected override List<MemberInfo> GetSerializableMembers(Type objectType)
    {
        return base.GetSerializableMembers(objectType).Where(o => o.Name != "Id").ToList();
    }
}

The DocumentIdContractResolver will prevent the Id property from being saved into the JSON. It also extends CamelCasePropertyNamesContractResolver to provide camel-cased properties in the JSON output.

Note that there is a JsonIgnore attribute that could be added to properties that should be omitted from the serialized JSON, however it is less global in its application. For example, if a class overrides the Id property of ModelBase, it would have to add the attribute.

With this new plumbing in place, it’s now possible to complete the Create, Update and Save methods. Exceptions are caught and wrapped in the IStoreOperationResult’s Exception property. If an exception is detected, it will be thrown up to the caller. These new methods also have an optional durability argument, which will block until a document has been written to disk, or the operation times out. By default, there is no durability requirement imposed.

public virtual int Create(T value, PersistTo persistTo = PersistTo.Zero)
{
    var result = _Client.ExecuteStore(StoreMode.Add, BuildKey(value), serializeAndIgnoreId(value), persistTo);
    if (result.Exception != null) throw result.Exception;
    return result.StatusCode.Value;
}

public virtual int Update(T value, PersistTo persistTo = PersistTo.Zero)
{
    var result = _Client.ExecuteStore(StoreMode.Replace, value.Id, serializeAndIgnoreId(value), persistTo);
    if (result.Exception != null) throw result.Exception;
    return result.StatusCode.Value;
}

public virtual int Save(T value, PersistTo persistTo = PersistTo.Zero)
{
    var key = string.IsNullOrEmpty(value.Id) ? BuildKey(value) : value.Id;
    var result = _Client.ExecuteStore(StoreMode.Set, key, serializeAndIgnoreId(value), persistTo);
    if (result.Exception != null) throw result.Exception;
    return result.StatusCode.Value;
}

The Get method of RepositoryBase requires similar considerations. CouchbaseClient.ExecuteGet returns an IGetOperationResult. To be consistent with the goal of not exposing Couchbase SDK plumbing to the app, Get will return the object or null if not found, while throwing a swallowed exception. Notice also that the Id property of the model is set to the value of the key, since it’s not being stored in the JSON.

public virtual T Get(string key)
{
    var result = _Client.ExecuteGet<string>(key);
    if (result.Exception != null) throw result.Exception;

    if (result.Value == null)
    {
        return null;
    }

    var model = JsonConvert.DeserializeObject<T>(result.Value);
    model.Id = key; //Id is not serialized into the JSON document on store, so need to set it before returning
    return model;
}

Completing the CRUD operations is the Delete method. Delete will also hide its SDK result data structure ( IRemoveOperationResult ) and return a status code, while throwing swallowed exceptions. Delete also supports the durability requirement overload.

public virtual int Delete(string key, PersistTo persistTo = PersistTo.Zero)
{
    var result = _Client.ExecuteRemove(key, persistTo);
    if (result.Exception != null) throw result.Exception;
    return result.StatusCode.HasValue ? result.StatusCode.Value : 0;
}

Brewery Forms¶

With the new methods implemented, it’s time to create the scaffolding for the CRUD forms. The first task will be to create an edit form. Open the BreweriesController and locate the Edit methods that were generated by the Add Controller wizard.

In the HTTP GET override of Edit, modify it as shown below. This action will retrieve the Brewery and pass it to the view as the model. Note the change from an int id parameter to a string id parameter.

public ActionResult Edit(string id)
{
    var brewery = BreweryRepository.Get(id).Item1;
    return View(brewery);
}

Update the Edit method that handles POSTs as shown below. Validation and error handling are intentionally being omitted for brevity.

[HttpPost]
public ActionResult Edit(string id, Brewery brewery)
{
    BreweryRepository.Update(brewery);
    return RedirectToAction("Index");
}

The edit form will be created using scaffolding, as was the case with the listing page. Right click on the “Breweries” folder in the “Views” directory and click Add -> View. Name the view “Edit” and strongly type it to a Brewery with Edit scaffolding.

Rebuild the application and return to the brewery listing page.  Click on an “Edit” link and you should see the edit form loaded with the details for that brewery.  Edit some values on the form and click save. You should see your changes persisted on the listing page.

The Details action looks very much like Edit. Get the Brewery and provide it as the model for the view.

public ActionResult Details(string id)
{
    var brewery = BreweryRepository.Get(id).Item1;
    return View(brewery);
}

Create a scaffolding form for Details using the same process as was used with Edit.

Rebuild and return to the list page. Click on a “Details” link. You should see a page listing the data for that brewery.

The Create and Edit actions of the BreweriesController are quite similar, save for the fact that Create’s GET method doesn’t provide a model to the view. Again, error handling and validation are being omitted for brevity’s sake.

public ActionResult Create()
{
    return View();
}
[HttpPost]
public ActionResult Create(Brewery brewery)
{
    BreweryRepository.Create(brewery);
    return RedirectToAction("Index");
}

Go through the scaffolding process again to add a create view for the Create action.  Rebuild and click the “Create New” link on the list page to test the new form.  Breweries (for now) are sorted by key and limited to 50, so you might not see yours in the list.  If you want to verify your create action worked, use brewery name that starts with a numeric value (e.g., 123 Brewery).

Another reason you wouldn’t see your new brewery appear in the list of breweries is that the view is set to allow stale (eventually consistent) results.  In other words, the incremental update to the “all” index would be performed after the query.  If you refresh, you should see your brewery in the list. 

Allowing the breweries to be sorted by key is convenient, since the key is based on the breweries name.  However, if case-sensitivity is important in sorting or the key creation strategy changes, then explicitly sorting on the brewery’s name is a better idea.  To that end, creating a new view indexed on the Brewery name is the right approach.

The new map function will look similar to the “all” map function, but will add tests on “doc.name” and will emit the doc.name as the key. 

function(doc, meta) {
    if (doc.type == "brewery" && doc.name) {
        emit(doc.name, null);
    }
}

If you are using the web console to manage your design documents, save the map function above as “by_name” in the “breweries” design document.  If you are using the Model Views framework, add an attribute to the Name property of Brewery>.  Then compile and run your application. 

Adding the CouchbaseViewKey attribute will create the view above.  The first argument is the name of the view.  The second is the name of the JSON document property to emit as key. 

[CouchbaseViewKey("by_name", “name”)]
public string Name { get; set; }

The next step is to replace the GetAll call with a call to the new view.  First, add a protected method in RepositoryBase that returns a typed view instance, set with the design doc for that model type.  The isProjection flag is set when the type of T does not properties of the JSON to properties of the class.  It must be used with explicit JSON.NET mappings.

protected IView<T> GetView(string name, bool isProjection = false)
{
    return _Client.GetView<T>(_designDoc, name, ! isProjection);
}

Then in BreweryRepository, implement GetAllByName as shown below. This new method simply returns the view, optionally allowing a limit and stale results.

public IEnumerable<Brewery> GetAllByName(int limit = 0, bool allowStale = false)
{
    var view = GetView("by_name");
    if (limit > 0) view.Limit(limit);
    if (! allowStale) view.Stale(StaleMode.False);
    return view;
}

Next, modify the BreweriesController so that the Index action calls the new GetAllByName method.

public ActionResult Index()
{
    var breweries = BreweryRepository.GetAllByName(50);
    return View(breweries);
}

Compile and run your application.  The list page might be ordered a little differently as the sample database did scrub some keys of punctuation and other non-word or non-digit characters.  Also now (because of the stale setting), if you create a new Brewery, it should appear after a redirect and should not require a refresh.

Note that it is still possible that the view didn’t consider the new Brewery when it was executed with state set to false.  If the document hadn’t persisted to disk before the index was updated, it wouldn’t have been included. 

If that level of consistency is important to your application, you should use an overload of ExecuteStore that includes durability requirements.  See the documentation on ExecuteStore for more information.

The last piece required to complete the CRUD functionality for breweries is to implement the delete form.  Update the Delete actions in BreweriesController as shown below.

public ActionResult Delete(string id)
{
    var brewery = BreweryRepository.Get(id).Item1;
    return View(brewery);
}
[HttpPost]
public ActionResult Delete(string id, Brewery brewery)
{
    BreweryRepository.Delete(id);
    return RedirectToAction("Index");
}

To create the delete form, simply go through the Add View process again and choose scaffolding for delete (don’t forget to choose the Brewery model).

Collated Views¶

At this point, you’ve written a full CRUD app for breweries in the beer-sample database. Another optimization we might want to include is to show the names of beers that belong to a particular brewery. In the relational world, this is typically accomplished using a join between two tables. In Couchbase, the solution is to use a collated view.

Before looking at the map function for this view, it’s useful to inspect a beer document.

{
   "name": "Old Stock Ale 2004",
   "abv": 11.4,
   "ibu": 0,
   "srm": 0,
   "upc": 0,
   "type": "beer",
   "brewery_id": "north_coast_brewing_company",
   "updated": "2010-07-22 20:00:20",
   "description": "",
   "style": "Old Ale",
   "category": "British Ale"
}

Note the “brewery_id” property.  This is the key of a brewery document and can be thought of as a “foreign key.”  Note that this type of document foreign key relationship is not enforced by Couchbase.

The basic idea behind a collated view is to produce an index in which the keys are ordered so that a parent id appears first, followed by its children.  In the beer-sample case that means a brewery appears in a row followed by rows of beers. 

The basic algorithm for the map function is to check the doc.type.  If a brewery is found, emit its key (meta.id).  If a child is found, emit its parent id (brewery_id).  The map function for the view “all_with_beers” is shown below.

function(doc, meta) {
    switch(doc.type) {
        case "brewery":
            emit([meta.id, 0]);
            break;
        case "beer":
            if (doc.name && doc.brewery_id) {
                emit([doc.brewery_id, doc.name, 1], null);
            }
    }
}

The trick to ordering properly the parent/child keys is to use a composite key in the index.  Parent ids are paired with a 0 and children with a 1.  The collated order of the view results is shown conceptually below. 

A Brewery, 0
A Brewery, 1
A Brewery, 1
B Brewery, 0
B Brewery, 1

To use Model Views to create this view, simply add an attribute to an overridden Id property on the Brewery class.

[CouchbaseCollatedViewKey("all_with_beers", "beer", "brewery_id", "name")]
public override string Id { get; set; }

This is a good time to introduce a simple Beer class, of which Brewery will have a collection. Create a new model class named “Beer.” For now, include only the Name property.

public class Beer : ModelBase
{
    public string Name { get; set; }
    public override string Type
    {
        get { return "beer"; }
    }
}

Then add a Beer list property to Brewery. This property shouldn’t be serialized into the doc, so add the JsonIgnore attribute.

private IList<Beer> _beers = new List<Beer>();
[JsonIgnore]
public IList<Beer> Beers
{
    get { return _beers; }
    set { _beers = value; }
}

Since the collated view has a mix of beers and breweries, the generic GetView<T> method won’t work well for deserializing rows. Instead, we’ll use the GetView method that returns IViewRow instances. First add a new GetViewRaw method to RepositoryBase.

protected IView<IViewRow> GetViewRaw(string name)
{
    return _Client.GetView(_designDoc, name);
}

Then in BreweryRepository, add a GetWithBeers method to build the object graph. This new method performs a range query on the view, starting with the brewery id and including all possible beer names for that brewery.

public Tuple<Brewery, bool, string> GetWithBeers(string id)
{
    var rows = GetViewRaw("all_with_beers")
        .StartKey(new object[] { id, 0 })
        .EndKey(new object[] { id, "\uefff", 1 })
        .ToArray();
    var result = Get(rows[0].ItemId);
    result.Item1.Beers = rows.Skip(1)
        .Select(r => new Beer { Id = r.ItemId, Name = r.ViewKey[1].ToString() })
        .ToList();
    return result;
}

Update the Details method of BreweriesController to use this method.

public ActionResult Details(string id)
{
    var brewery = BreweryRepository.GetWithBeers(id).Item1;
    return View(brewery);
}

Before the closing fieldset tag in details template, add a block of Razor code to display the beers.

<div class="display-field">Beers</div>
 <div>
    @foreach (var item in Model.Beers)
    {
        <div style="margin-left:10px;">- @item.Name</div>
    }
</div>

Paging¶

The final feature to implement on the brewery CRUD forms is paging.  It’s important to state up front that paging in Couchbase does not work like paging in a typical RDBMS.  Though views have skip and limit filters that could be used create the standard paging experience, it’s not advisable to take this approach. 

The skip filter still results in a read of index data starting with the first row of the index.  For example, if an index has 5000 rows and skip is set to 500 and limit is set to 50, 500 records are read and 50 returned.  Instead, linked-list style pagination is the recommended approach.  Paging should also consider the document ids because keys may collide.  However, in the breweries example, paging on name is safe because name is the source of the unique key.

First add an HTML footer to the list table in the Index view, right before the final closing table tag.  There is a link back to the first page and links to the previous and next pages.  A default page size of 10 is also used.  Each time the page is rendered, it sets the previous key to the start key of the previous page.  The next key will be explained shortly.

<tr>
    <td colspan="4">
        @Html.ActionLink("List", "Index", new { pagesize = 10 })
        @Html.ActionLink("< Previous", "Index", new { startKey = Request["previousKey"], pagesize = Request["pagesize"] ?? "10" })
        @Html.ActionLink("Next >", "Index", new { startKey = ViewBag.NextStartKey, previousKey =  ViewBag.StartKey, pagesize = Request["pagesize"] ?? "10"})
    </td>
</tr>

Modify the GetAllByName method in BreweryRepository to be able to handle range queries (startkey, endkey).

public IEnumerable<Brewery> GetAllByName(string startKey = null, string endKey = null, int limit = 0, bool allowStale = false)
{
    var view = GetView("by_name");
    if (limit > 0) view.Limit(limit);
    if (! allowStale) view.Stale(StaleMode.False);
    if (! string.IsNullOrEmpty(startKey)) view.StartKey(startKey);
    if (! string.IsNullOrEmpty(endKey)) view.StartKey(endKey);
    return view;
}

For the actual paging, modify the BreweryController ’s Index method to keep track of pages. The trick is to select page size + 1 from the view. The last element is not rendered, but its key is used as the start key of the next page. In simpler terms, the start key of the current page is the next page’s previous key. The last element’s key is not displayed, but is used as the next page’s start key.

public ActionResult Index(string startKey, string nextKey, int pageSize = 25)
{
    var breweries = BreweryRepository.GetAllByName(startKey: startKey, limit: pageSize+1);
    ViewBag.StartKey = breweries.ElementAt(0).Name;
    ViewBag.NextStartKey = breweries.ElementAt(breweries.Count()-1).Name;
    return View(breweries.Take(pageSize));
}

At this point, breweries may be created, detailed (with Children), listed, updated and deleted.  The next step is to look at the brewery data from a different perspective, namely location.

Brewery documents have multiple properties related to their location.  There are state and city properties, as well as detailed geospatial data.  The first question to ask of the data is how many breweries exist for a given country.  Then within each country, the counts can be refined to see how many breweries are in a given state, then city and finally zip code.  All of these questions will be answered by the same view.

Create a view named “by_country” with the code below.  This view will not consider documents that don’t have all location properties.  The reason for this restriction is so that counts are accurate as you drill into the data.

function (doc, meta) {
  if (doc.country && doc.state && doc.city && doc.code) {
     emit([doc.country, doc.state, doc.city, doc.code], null);
  }
}

For this view, you’ll also want a reduce function, which will count the number of rows for a particular grouping by counting how many rows appear for that grouping.  So for example, when the group_level parameter is set to 2 brewery counts will be returned by city and state.  For an analogy, think of a SQL statement selecting a COUNT(*) and having a GROUP BY clause with city and state columns.

Couchbase has three built in reduce functions - _count, _sum and _stats.  For this view, _count and _sum will perform the same duties.  Emitting a 1 as a value means that _sum would sum the 1s for a grouping.  _count would simply count 1 for each row, even with a null value.

If you are using Model Views, then simply add CouchbaseViewKeyCount attributes to each of the properties that should be produced in the view.

[CouchbaseViewKeyCount("by_country", "country", 0, null)]
public string Country { get; set; }

[CouchbaseViewKeyCount("by_country", "state", 1)]
public string State { get; set; }

[CouchbaseViewKeyCount("by_country", "city", 2)]
public string City { get; set; }

[CouchbaseViewKeyCount("by_country", "code", 3)]
public string Code { get; set; }

This view demonstrates how to create ordered, composite keys from domain object properties using the Model Views framework.

The next step is to modify the BreweryRepository to include methods that will return aggregated results grouped at the appropriate levels.  This new method will return key value pairs where the key is the lowest grouped part of the key and the value is the count.  Also add an enum for group levels.

public IEnumerable<KeyValuePair<string, int>> GetGroupedByLocation(BreweryGroupLevels groupLevel, string[] keys = null)
{
    var view = GetViewRaw("by_country")
                .Group(true)
                .GroupAt((int)groupLevel);
    if (keys != null)
    {
        view.StartKey(keys);
        view.EndKey(keys.Concat(new string[] { "\uefff" }));
    }
    foreach (var item in view)
    {
        var key = item.ViewKey[(int)groupLevel-1].ToString();
        var value = Convert.ToInt32(item.Info["value"]);
        yield return new KeyValuePair<string, int>(key, value);
    }
}

Create a new controller named “CountriesController” to contain the actions for the new grouped queries. Use the empty controller template.

Modify the new controller to include the code below, which sets up the BreweryRepositoryReference and loads sends the view results to the MVC View.

public class CountriesController : Controller
{
    public BreweryRepository BreweryRepository { get; set; }
    public CountriesController()
    {
        BreweryRepository = new BreweryRepository();
    }
    public ActionResult Index()
    {
        var grouped = BreweryRepository.GetGroupedByLocation(BreweryGroupLevels.Country);
        return View(grouped);
    }
}

Next create a new directory under “Views” named “Countries.” Add a view named “Index” that is not strongly typed.

To the new view, add the Razor code below, which will simply display the keys and values as a list. It also links to the Provinces action, which you’ll create next.

@model dynamic
<h2>Brewery counts by country</h2>
<ul>
@foreach (KeyValuePair<string, int> item in Model)
{
    <li>
        @Html.ActionLink(item.Key, "Provinces", new { country = item.Key})
        (@item.Value)
    </li>
}
</ul>

Build and run your application and you should see a page like below.

Next, add the Provinces action to the CountriesController. This action will reuse the repository method, but will change the group level to Province (2) and pass the selected country to be used as a key to limit the query results.

public ActionResult Provinces(string country)
{
    var grouped = BreweryRepository.GetGroupedByLocation(
                BreweryGroupLevels.Province, new string[] { country } );
    return View(grouped);
}

Create another empty view named “Provinces” in the “Countries” directory under the “Views” directory. Include the content below, which is similar to the index content.

@model dynamic
<h2>Brewery counts by province in @Request["country"]</h2>
<ul>
@foreach (KeyValuePair<string, int> item in Model)
{
    <li>
        @Html.ActionLink(item.Key, "Cities",
            new { country = Request["country"], province = item.Key})
        (@item.Value)
    </li>
}
</ul>

Compile and run the app. You should see the Provinces page below.

Creating the actions and views for cities and codes is a similar process. Modify CountriesController to include new action methods as shown below.

public ActionResult Cities(string country, string province)
{
    var grouped = BreweryRepository.GetGroupedByLocation(
                BreweryGroupLevels.City, new string[] { country, province });
    return View(grouped);
}
public ActionResult Codes(string country, string province, string city)
{
    var grouped = BreweryRepository.GetGroupedByLocation(
                BreweryGroupLevels.PostalCode, new string[] { country, province, city });
    return View(grouped);
}

Then add a view named “Cities” with the Razor code below.

@model dynamic
<h2>Breweries counts by city in @Request["province"], @Request["country"]</h2>
<ul>
@foreach (KeyValuePair<string, int> item in Model)
{
    <li>
        @Html.ActionLink(item.Key, "Codes",
            new { country = Request["country"],
                  province = Request["province"],
                  city = item.Key})
        (@item.Value)
    </li>
}
</ul>

Then add a view named “Codes” with the Razor code below.

@model dynamic
<h2>Brewery counts by postal code in @Request["city"], @Request["province"], @Request["country"]</h2>
<ul>
@foreach (KeyValuePair<string, int> item in Model)
{
    <li>
       @Html.ActionLink(item.Key, "Details",
            new { country = Request["country"],
                  province = Request["province"],
                  city = Request["city"],
                  code = item.Key})
        (@item.Value)
    </li>
}
</ul>
@Html.ActionLink("Back to Country List", "Index")

Compile and run the app. Navigate through the country and province listings to the cities listing. You should see the page below.

Click through to the codes page and you should see the page below.

The last step for this feature is to display the list of breweries for a given zip code. To implement this page, you need to add a new method to BreweryRepository named GetByLocation. This method will use the same view that we’ve been using, except it won’t execute the reduce step. Not executing the reduce step means that the results come back ungrouped and individual items are returned.

public IEnumerable<Brewery> GetByLocation(string country, string province, string city, string code)
{
    return GetView("by_country").Key(new string[] { country, province, city, code }).Reduce(false);
}

Then add a Details action method to the BreweriesController that calls this method and returns its results to the view.

public ActionResult Details(string country, string province, string city, string code)
{
    var breweries = BreweryRepository.GetByLocation(country, province, city, code);
    return View(breweries);
}

Create a Details view in the “Countries” folder with the Razor code below.

@model IEnumerable<CouchbaseBeersWeb.Models.Brewery>
<h2>Breweries in @Request["code"], @Request["city"], @Request["province"], @Request["country"]</h2>
<ul>
@foreach (var item in Model)
{
    <li>
        @Html.ActionLink(item.Name, "Details", "Breweries", new { id = item.Id }, new { })
    </li>
}
</ul>
@Html.ActionLink("Back to Country List", "Index")

Compile and run the app. Click through country, province and state on to the Codes view. The code above already has a link to this new Details page. When you click on a postal code, you should see a list of breweries as below.

Spatial Indexes¶

The last feature to add to the brewery app is the ability to search for breweries using its longitude and latitude.  The experimental spatial indexes in Couchbase allow for bounding box searches.  Spatial indexes are created by emitting a GeoJSON document as the key.  This document must contain a coordinates property to be indexed.

Using the web console, create a new spatial view (click “Add Spatial View”) in the breweries design document named “points” using the spatial function below.  Note that spatial views do not use the same map/reduce process as standard views.

function (doc, meta) {
    if (doc.type == "brewery" && doc.geo.lng && doc.geo.lat) {
        emit({ "type": "Point", "coordinates": [doc.geo.lng, doc.geo.lat]}, null);

    }
}

If you are using Model Views, then you’ll need to modify the Brewery class. Currently, the Model Views framework doesn’t support object graph navigation, so you’ll need to flatten the “geo” property of the JSON document into the Brewery as shown below. These flattened properties provide Model Views with a way to build the spatial index.

[JsonIgnore]
public string GeoAccuracy
{
    get
    {
        return Geo != null && Geo.ContainsKey("accuracy") ? Geo["accuracy"] as string : "";
    }
}
[CouchbaseSpatialViewKey("points", "geo.lng", 0)]
[JsonIgnore]
public float Longitude
{
    get
    {
        return Geo != null && Geo.ContainsKey("lng") ? Convert.ToSingle(Geo["lng"]) : 0f;
    }
}
[CouchbaseSpatialViewKey("points", "geo.lat", 1)]
[JsonIgnore]
public float Latitude
{
    get
    {
        return Geo != null && Geo.ContainsKey("lat") ? Convert.ToSingle(Geo["lat"]) : 0f;
    }
}

Next, RepositoryBase should be modified to provide support for generic views. As with GetView and GetViewRaw, these new methods are to provide some code reuse to subclasses.

protected virtual ISpatialView<T> GetSpatialView(string name, bool isProjection = false)
{
    return _Client.GetSpatialView<T>(_designDoc, name, !isProjection);
}
protected virtual ISpatialView<ISpatialViewRow> GetSpatialViewRaw(string name)
{
    return _Client.GetSpatialView(_designDoc, name);
}

Then update BreweryRepository with a method to call the new “points” view. Spatial views expect a bounding box with lower left and upper right coordinates, ordered longitude then latitude. The UI will work with a delimited string, so those points must be parsed and parsed as floats.

public IEnumerable<Brewery> GetByPoints(string boundingBox)
{
    var points = boundingBox.Split(',').Select(s => float.Parse(s)).ToArray();
    return GetSpatialView("points").BoundingBox(points[0], points[1], points[2], points[3]);
}

Then add a new class named “LocationsController” to the “Controllers” folder using the code below.

public class LocationsController : Controller
{
    public BreweryRepository BreweryRepository { get; set; }
    public LocationsController()
    {
        BreweryRepository = new BreweryRepository();
    }
    [HttpGet]
    public ActionResult Details()
    {
        return View();
    }
    [HttpPost]
    public ActionResult Details(string bbox)
    {
        var breweriesByPoints = BreweryRepository.GetByPoints(bbox)
                                    .Select(b => new
                                    {
                                        id = b.Id,
                                        name = b.Name,
                                        geo = new float[] { b.Longitude, b.Latitude }
                                    });
        return Json(breweriesByPoints);
    }
}

Most of the code above is boilerplate. A BreweryRepository is declared and initialized in the default constructor. The Details action that handles GET requests simply returns the view. The Details request that handles POST requests calls the new BreweryRepository method and renders a JSON array of brewery projections that will be used in the view.

Next create a new Views folder called “Locations” and add a new view named “Details” to it. This new view will make use of Nokia’s HERE location services API. You can register for free at http://here.com. Add the Razor and JavaScript code below to your view.

@model CouchbaseBeersWeb.Models.Brewery
<style type="text/css">
    #mapContainer {
        width: 80%;
        height: 768px;
        margin-left:10%;
        margin-right:10%;
    }
</style>
<script type="text/javascript" charset="UTF-8" src="http://api.maps.nokia.com/2.2.3/jsl.js?with=all"></script>
<h2>View Breweries</h2>
<div id="mapContainer"></div>
<script type="text/ecmascript">
    nokia.Settings.set("appId", "<YOUR APP ID>");
    nokia.Settings.set("authenticationToken", "<YOUR TOKEN>");
    var mapContainer = document.getElementById("mapContainer");
    var map = new nokia.maps.map.Display(mapContainer, {
        center: [41.763309, -72.67408],
        zoomLevel: 8,
        components: [
            new nokia.maps.map.component.Behavior()
        ]
    });
    $().ready(function () {
        var loadBreweries = function () {
            var mapBoundingBox = map.getViewBounds();
            var queryBoundingBox = mapBoundingBox.topLeft.longitude + "," +                      mapBoundingBox.bottomRight.latitude + "," +
mapBoundingBox.bottomRight.longitude + ","
+ mapBoundingBox.topLeft.latitude;
            $.post("@Url.Action("Details")", { bbox: queryBoundingBox }, function (data) {
            var coordinates = new Array();
            $.each(data, function (idx, item) {
                var coordinate = new nokia.maps.geo.Coordinate(item.geo[1], item.geo[0]);
                var standardMarker = new nokia.maps.map.StandardMarker(coordinate);
                map.objects.add(standardMarker);
            });
        });
    };
    map.addListener("dragend", function (evt) {
        loadBreweries();
    });
    loadBreweries();
});
</script>

The details of the HERE API are beyond the scope of this tutorial.  The basic idea though is that when the map is rendered, the bounding box coordinates are obtained and passed (via AJAX) to the Details POST method on the LocationsController.  The coordinates that come back are used to render points on the map via a standard marker. 

Compile and run these last changes.  Navigate to /locations/details and you should see a map such as the one shown below.

Conclusion¶

At this point, the brewery features are complete.  Creating a set of pages for the beer documents is a similar exercise that is left to the reader.  Using scaffolding and reusing the patterns from working with breweries, it shouldn’t take much effort to build those features. 

The code for this sample app is on GitHub at https://github.com/couchbaselabs/beer-sample-net.  It contains all the code from this tutorial, plus the beer pages.  It also contains some very minor style and navigation improvements (such as a home page). 

Finally, a single tutorial can address only so many concerns.  Clearly some shortcuts were taken with validation, exception handling and the like.  Certain architectural patterns, such as dependency injection and MVVM were also omitted for the sake of brevity.  The intent of this tutorial was to provide an intermediate introduction to Couchbase development with.NET.  Your app should be able to make use of some or all of the patterns described.

.NET Method Summary¶

.Net Connection Operations¶

API Call	object.new CouchbaseClient([ url ] [, username ] [, password ])
Asynchronous	no
Description	Create a connection to Couchbase Server with given parameters, such as node URL. The connection obtains the cluster configuration from the first host to which it has connected. Further communication operates directly with each node in the cluster as required.
Returns	(none)
Arguments
string url	URL for Couchbase Server Instance, or node.
string username	Username for Couchbase bucket.
string password	Password for Couchbase bucket.

The easiest way to specify a connection, or a pool of connections is to provide it in the App.config file of your.Net project. By doing so, you can change the connection information without having to recompile. You can update App.config in Visual Studio as follows:

<servers bucket="private" bucketPassword="private">
      <add uri="http://10.0.0.33:8091/pools"/>
      <add uri="http://10.0.0.34:8091/pools"/>
</servers>

You should change the URI above to point at your server by replacing 10.0.0.33 with the IP address or hostname of your Couchbase server machine. Be sure you set your bucket name and password. You can also set the connection to use the default bucket, by setting the bucket attribute to default and leaving the bucketPassword attribute empty. In this case we have configured the server with a bucket named ‘private’ and with a password ‘private.’

Connections that you create with the.Net SDK are also thread-safe objects; for persisted connections, you can use a connection pool which contains multiple connection objects. You should create only a single static instance of a Couchbase client per bucket, in accordance with.Net framework. The persistent client will maintain connection pools per server node. For more information, see MSDN: AppDomain Class.

Store Operations¶

The Couchbase.NET Client Library store operations set information within the Couchbase database. These are distinct from the update operations in that the key does not have to exist within the Couchbase database before being stored.

Store Methods¶

The Store() methods add or replace a value in the database with the specified key.

The behavior of Store and ExecuteStore operations is defined by setting the first parameter to a value from the StoreMode enumeration.

• StoreMode.Add - Add a key to the database, failing if the key exists

• StoreMode.Replace - Replace a key in the database, failing if the key does not exist

• StoreMode.Set - Add a key to the database, replacing the key if it already exists

JavaScript can store numbers up to a maximum size of 2⁵³. If you are storing 64-bit integers within Couchbase and want to use the numbers through the Map/Reduce engine, numbers larger than 2⁵³ should be stored as a string to prevent number rounding errors.

API Call	object.Store(storemode, key, value)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	Boolean ( Boolean (true/false) )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored

The Store() method is used to persist new values by key. Any class decorated with the Serializable attribute may be stored.

client.Store(StoreMode.Add, "beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Company",
    Name = "American Ale"
});

API Call	object.Store(storemode, key, value, validfor)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	Boolean ( Boolean (true/false) )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
TimeSpan validfor	Expiry time (in seconds) for key

client.Store(StoreMode.Set, "beer", new Beer() {
    Brewer = "Peak Organic Brewing Company",
    Name = "IPA"
}, TimeSpan.FromSeconds(60));

API Call	object.Store(storemode, key, value, expiresat)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	Boolean ( Boolean (true/false) )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
DateTime expiresat	Explicit expiry time for key

client.Store(StoreMode.Replace, "beer", new Beer() {
    Brewer = "Six Point Craft Ales",
    Name = "Righteous Rye"
}, DateTime.Now.Addhours(1));

API Call	object.ExecuteStore(storemode, key, value)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored

The ExecuteStore() methods are similar to the Store methods, but return an instance of an IStoreOperationResult.

var result = client.ExecuteStore(StoreMode.Add, "beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Company",
    Name = "American Ale"
});

if (! result.Success)
{
    Console.WriteLine("Store failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteStore(storemode, key, value, validfor)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
TimeSpan validfor	Expiry time (in seconds) for key

client.ExecuteStore(StoreMode.Set, "beer", new Beer() {
    Brewer = "Peak Organic Brewing Company",
    Name = "IPA"
}, TimeSpan.FromSeconds(60));

API Call	object.ExecuteStore(storemode, key, value, expiresat)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
DateTime expiresat	Explicit expiry time for key

client.ExecuteStore(StoreMode.Replace, "beer", new Beer() {
    Brewer = "Six Point Craft Ales",
    Name = "Righteous Rye"
}, DateTime.Now.Addhours(1));

API Call	object.ExecuteStore(storemode, key, value)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored

The ExecuteStore() methods may define persistence or replciation (durability) requirements. These operations will either return success only when the durability requirements have been met. The operation fails if it times out before meeting the durability requirement.

• When specifying a persistence requirement, the persistTo parameter is set to a value from the PersistTo enumeration. These values specify the number of nodes to which a key must be persisted to disk. PersistTo.One - Require master only persistence

• PersistTo.Two, PersistTo.Three, PersistTo.Four - Persist to master, plus one, two or three replicas

• When specifying a replication requirement, the replicateTo parameter is set to a value from the ReplicateTo enumeration. These values specify the number of nodes to which a key must be replicated. ReplicateTo.One, ReplicateTo.Two, ReplicateTo.Three - Replicate to one, two or three replicas

//master persistence, replicate to two replicas
var result = client.ExecuteStore(StoreMode.Add, "beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Company",
    Name = "American Ale"
}, PersistTo.One, ReplicateTo.Two);

if (! result.Success)
{
    Console.WriteLine("Store failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteStore(storemode, key, value, validfor)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
TimeSpan validfor	Expiry time (in seconds) for key

//master only persistence
client.ExecuteStore(StoreMode.Set, "beer", new Beer() {
    Brewer = "Peak Organic Brewing Company",
    Name = "IPA"
}, TimeSpan.FromSeconds(60), PersistTo.One, ReplicateTo.Zero););

API Call	object.ExecuteStore(storemode, key, value, expiresat)
Asynchronous	no
Description	Store a value using the specified key, whether the key already exists or not. Will overwrite a value if the given key/value already exists.
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
DateTime expiresat	Explicit expiry time for key

//no persistence requirement, replicate to two nodes
client.ExecuteStore(StoreMode.Replace, "beer", new Beer() {
    Brewer = "Six Point Craft Ales",
    Name = "Righteous Rye"
}, DateTime.Now.Addhours(1), PersistTo.Zero, ReplicateTo.Two););

Retrieve Operations¶

The retrieve operations get information from the Couchbase database. A summary of the available API calls is listed below.

Get Methods¶

The Get() methods allow for direct access to a given key/value pair.

API Call	object.Get(key)
Asynchronous	no
Description	Get one or more key values
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value

The generic form of the Get method allows for retrieval without the need to cast. If the stored type cannot be serialized to the generic type provided, an InvalidCastException will be thrown.

var beer = client.Get<Beer>("beer");

API Call	object.Get(key, expiry)
Asynchronous	no
Description	Get a value and update the expiration time for a given key
Returns	(none)
Arguments
string key	Document ID used to identify the value
object expiry	Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

Calling the Get() method with a key and a new expiration value will cause get and touch operations to be performed.

var val = client.Get("beer", DateTime.Now.AddMinutes(5));

API Call	object.Get(keyarray)
Asynchronous	no
Description	Get one or more key values
Returns	Object ( Binary object )
Arguments
List keyarray	Array of keys used to reference one or more values.

Calling Get() with multiple keys returns a dictionary with the associated values.

client.Store(StoreMode.Set, "brewer", "Cottrell Brewing Co.");
client.Store(StoreMode.Set, "beer", "Old Yankee Ale");

var dict = client.Get(new string[] { "brewery", "beer" });
Console.WriteLine(dict["brewery"]);
Console.WriteLine(dict["beer"]);

API Call	object.Get(key)
Asynchronous	no
Description	Get one or more key values
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value

GetWithCas returns a CasResult, which includes the document and its CAS value.

For example:

var casResult = client.GetWithCas("beer");
client.Store(StoreMode.Set, "beer", "some other beer", casResult.Cas)

Calling GetWithCas() with multiple keys returns a dictionary with the associated values. The generic version will return the Result as an instance of T.

var casResult = client.GetWithCas<Beer>("beer");
Console.WriteLine(casResult.Name);

API Call	object.ExecuteGet(key)
Asynchronous	no
Description	Get one or more key values
Returns	IGetOperationResult ( Get operation result )
Arguments
string key	Document ID used to identify the value

The ExecuteGet and generic ExecuteGet methods are used to return detailed results in an instance of an IGetOperationResult.

var result = client.ExecuteGet("beer");

if (! result.Success)
{
    Console.WriteLine("Get failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

var beer = result.Value as Beer;
beer.Brewery = "Cambridge Brewing Company";
var casResult = client.ExecuteCas(StoreMode.Set, "beer", beer, result.Cas); //ExecuteGet returns the CAS for the key

The generic form of ExecuteGet<T> will set the Value property to type T

var result = client.ExecuteGet<Beer>("beer");
var beer = result.Value; //no need to cast beer as a Beer

API Call	object.ExecuteGet(key, expiry)
Asynchronous	no
Description	Get a value and update the expiration time for a given key
Returns	IGetOperationResult ( Get operation result )
Arguments
string key	Document ID used to identify the value
object expiry	Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

Calling the ExecuteGet() method with a key and a new expiration value will cause get and touch operations to be performed.

var val = client.Get("beer", DateTime.Now.AddMinutes(5));

API Call	object.ExecuteGet(keyarray)
Asynchronous	no
Description	Get one or more key values
Returns	IGetOperationResult ( Get operation result )
Arguments
List keyarray	Array of keys used to reference one or more values.

Calling ExecuteGet() with multiple keys returns a dictionary with the associated IGetOperationResult values.

client.Store(StoreMode.Set, "brewery", "Cottrell Brewing Co.");
client.Store(StoreMode.Set, "beer", "Old Yankee Ale");

var dict = client.ExecuteGet(new string[] { "brewery", "beer" });
foreach(var key in dict.Keys)
{
    Console.WriteLine(dict[key]);
}

GetWithLock() prevents a key from being updated for either 30 seconds (default) or the value specified as an optional lock expiration.

var casResult = client.GetWithLock("beer", TimeSpan.FromSeconds(10));
var result = client.Store(StoreMode.Set, "beer", new Beer()); //result will be false

ExecuteGetWithLock() provides similar behavior to GetWithLock, but returns an IGetOperationResult, which allows for status codes to be checked.

var lockResult = client.ExecuteGetWithLock("key", TimeSpan.FromSeconds(30));
var storeResult = client.ExecuteStore(StoreMode.Set, "key", "new value");
//storeResult.Success will be false
//storeResult.StatusCode will be equal to (int)StatusCodeEnums.DataExistsForKey

var getLockResultA = client.ExecuteGetWithLock("key");
var getLockResultB = client.ExecuteGetWithLock("key");
//getLockResultB.StatusCode will be equalt to (int)CouchbaseStatusCodeEnums.LockError)

API Call	object.KeyExists(key)
Asynchronous	no
Description	Get one or more key values
Returns	Boolean ( Boolean (true/false) )
Arguments
string key	Document ID used to identify the value

KeyExists() checks whether a key has been either a) written to RAM or b) written to disk on the master node for a key. If the key exists, the value is not returned.

var result = client.KeyExists("foo"); //result is true when "foo" exists

Update Operations¶

The update methods support different methods of updating and changing existing information within Couchbase. A list of the available methods is listed below.

Append Methods¶

The Append() methods allow you to add information to an existing key/value pair in the database. You can use this to add information to a string or other data after the existing data.

The Append() methods append raw serialized data on to the end of the existing data in the key. If you have previously stored a serialized object into Couchbase and then use Append, the content of the serialized object will not be extended. For example, adding an List of integers into the database, and then using Append() to add another integer will result in the key referring to a serialized version of the list, immediately followed by a serialized version of the integer. It will not contain an updated list with the new integer appended to it. De-serialization of objects that have had data appended may result in data corruption.

API Call	object.Append(key, value)
Asynchronous	no
Description	Append a value to an existing key
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value
object value	Value to be stored

The Append() method appends information to the end of an existing key/value pair.

The sample below demonstrates how to create a csv string by appending new values.

client.Store(StoreMode.Set, "beers", "Abbey Ale");
Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
client.Append("beers", new ArraySegment<byte>(stringToBytes(",Three Philosophers")));
client.Append("beers", new ArraySegment<byte>(stringToBytes(",Witte")));

You can check if the Append operation succeeded by checking the return value.

var result = client.Append("beers", new ArraySegment<byte>(stringToBytes(",Hennepin")));
if (result) {
    Console.WriteLine("Append succeeded");
} else {
    Console.WriteLine("Append failed");
}

API Call	object.Append(key, casunique, value)
Asynchronous	no
Description	Append a value to an existing key
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value
ulong casunique	Unique value used to verify a key/value combination
object value	Value to be stored

The Append operation may also be used with a CAS value.

var storeResult = client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");

Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
client.Append("beers", storeResult.Cas, new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

API Call	object.ExecuteAppend(key, value)
Asynchronous	no
Description	Append a value to an existing key
Returns	IConcatOperationResult ( Concat operation result )
Arguments
string key	Document ID used to identify the value
object value	Value to be stored

The ExecuteAppend operation is used to get an instance of an IConcatOperationResult.

client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");
Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
var result = client.ExecuteAppend("beers", new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

if (! result.)
{
    Console.WriteLine("Append failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteAppend(key, casunique, value)
Asynchronous	no
Description	Append a value to an existing key
Returns	IConcatOperationResult ( Concat operation result )
Arguments
string key	Document ID used to identify the value
ulong casunique	Unique value used to verify a key/value combination
object value	Value to be stored

The ExecuteAppend operation may also be used with a CAS value.

var storeResult = client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");

Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
var appendResult = client.ExecuteAppend("beers", storeResult.Cas, new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

if (! appendResult.)
{
    Console.WriteLine("Append failed with message {0} and status code {1}", appendResult.Message, appendResult.StatusCode);

    if (appendResult.Exception != null)
    {
        throw appendResult.Exception;
    }
}

Decrement Methods¶

The Decrement() methods reduce the value of a given key if the corresponding value can be parsed to an integer value. These operations are provided at a protocol level to eliminate the need to get, update, and reset a simple integer value in the database. All the.NET Client Library methods support the use of an explicit offset value that will be used to reduce the stored value in the database. Note that the Decrement methods may not be used with keys that were first created with a Store method. To initialize a counter, you must first use either Increment or Decrement with a default value.

API Call	object.Decrement(key, defaultvalue, offset)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist.

client.Remove("inventory"); //reset the counter
client.Decrement("inventory", 100, 1); //counter will be 100
client.Decrement("inventory", 100, 1); //counter will be 99

API Call	object.Decrement(key, defaultvalue, offset, validfor)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds.

client.Decrement("inventory", 100, 1, TimeSpan.FromSeconds(60));

API Call	object.Decrement(key, defaultvalue, offset, expiresat)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes.

client.Decrement("inventory", 100, 1, DateTime.Now.AddMinutes(5));

API Call	object.Decrement(key, defaultvalue, offset, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Decrement("inventory", 100, 1, result.Cas);

API Call	object.Decrement(key, defaultvalue, offset, validfor, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Decrement("inventory", 100, 1, TimeSpan.FromSeconds(60), result.Cas);

API Call	object.Decrement(key, defaultvalue, offset, expiresat, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Decrement("inventory", 100, 1, DateTime.Now.AddMinutes(5), result.Cas);

API Call	object.ExecuteDecrement(key, defaultvalue, offset)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)

ExecuteDecrement will return an instance of an IMutateOperationResult

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist.

client.Remove("inventory"); //reset the counter
client.ExecuteDecrement("inventory", 100, 1); //counter will be 100
var result = client.ExecuteDecrement("inventory", 100, 1); //counter will be 99

if (! result.Success)
{
    Console.WriteLine("Decrement failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteDecrement(key, defaultvalue, offset, validfor)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds.

client.ExecuteDecrement("inventory", 100, 1, TimeSpan.FromSeconds(60));

API Call	object.ExecuteDecrement(key, defaultvalue, offset, expiresat)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes.

client.ExecuteDecrement("inventory", 100, 1, DateTime.Now.AddMinutes(5));

API Call	object.ExecuteDecrement(key, defaultvalue, offset, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteDecrement("inventory", 100, 1, result.Cas);

API Call	object.ExecuteDecrement(key, defaultvalue, offset, validfor, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteDecrement("inventory", 100, 1, TimeSpan.FromSeconds(60), result.Cas);

API Call	object.ExecuteDecrement(key, defaultvalue, offset, expiresat, casunique)
Asynchronous	no
Description	Decrement the value of an existing numeric key. The Couchbase Server stores numbers as unsigned values. Therefore the lowest you can decrement is to zero.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

Decrement the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteDecrement("inventory", 100, 1, DateTime.Now.AddMinutes(5), result.Cas);

Remove Methods¶

The Remove() method deletes an item in the database with the specified key.

API Call	object.Remove(key)
Asynchronous	no
Description	Delete a key/value
Returns	Object ; supported values:
	COUCHBASE_ETMPFAIL
	COUCHBASE_KEY_ENOENT
	COUCHBASE_NOT_MY_VBUCKET
	COUCHBASE_NOT_STORED
	docid
Arguments
string key	Document ID used to identify the value

Remove the item with a specified key

client.Remove("badkey");

API Call	object.ExecuteRemove(key)
Asynchronous	no
Description	Delete a key/value
Returns	IRemoveOperationResult ( Remove operation result )
Arguments
string key	Document ID used to identify the value

ExecuteRemove removes an item by key and returns an instance of an IRemoveOperationResult

var result = client.ExecuteRemove("badkey");

if (! result.Succes)
{
    Console.WriteLine("Remove failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteRemove-cas(key, casunique)
Asynchronous	no
Description	Delete a key/value
Returns	IRemoveOperationResult ( Remove operation result )
Arguments
string key	Document ID used to identify the value
ulong casunique	Unique value used to verify a key/value combination

ExecuteRemove removes an item by key using a CAS operation and returns an instance of an IRemoveOperationResult

var result = client.ExecuteRemove("badkey", 86753091234);

if (! result.Succes)
{
    Console.WriteLine("Remove failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteRemove(key)
Asynchronous	no
Description	Delete a key/value
Returns	IRemoveOperationResult ( Remove operation result )
Arguments
string key	Document ID used to identify the value

The ExecuteRemove() method may define persistence requirements. This operation will return success only when the key has been removed from the specified number of nodes.

PersistTo.One will ensure removal from the key’s master node and not consider removal of its replicas. A common use of this option is to combine it with a non-stale view query, to guarantee that a deleted key is not returned in a view result.

var result = client.ExecuteRemove("city_NC_Raleigh", PersistTo.One);

if (! result.Succes)
{
    Console.WriteLine("Remove failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}
else
{
    var view = client.GetView("cities", "by_name").Stale(StaleMode.False);
    //safe to iterate this view, because the key has been removed from disk
    //and the index was updated.
}

Increment Methods¶

The Increment() methods reduce the value of a given key if the corresponding value can be parsed to an integer value. These operations are provided at a protocol level to eliminate the need to get, update, and reset a simple integer value in the database. All the.NET Client Library methods support the use of an explicit offset value that will be used to reduce the stored value in the database. Note that the Increment methods may not be used with keys that were first created with a Store method. To initialize a counter, you must first use either Increment or Increment with a default value.

API Call	object.Increment(key, defaultvalue, offset)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist.

client.Remove("inventory"); //reset the counter
client.Increment("inventory", 100, 1); //counter will be 100
client.Increment("inventory", 100, 1); //counter will be 101

API Call	object.Increment(key, defaultvalue, offset, validfor)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds.

client.Increment("inventory", 100, 1, TimeSpan.FromSeconds(60));

API Call	object.Increment(key, defaultvalue, offset, expiresat)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes.

client.Increment("inventory", 100, 1, DateTime.Now.AddMinutes(5));

API Call	object.Increment(key, defaultvalue, offset, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Increment("inventory", 100, 1, result.Cas);

API Call	object.Increment(key, defaultvalue, offset, validfor, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Increment("inventory", 100, 1, TimeSpan.FromSeconds(60), result.Cas);

API Call	object.Increment(key, defaultvalue, offset, expiresat, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	CasResult<ulong> ( Cas result of bool )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.Increment("inventory", 100, 1, DateTime.Now.AddMinutes(5), result.Cas);

API Call	object.ExecuteIncrement(key, defaultvalue, offset)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)

ExecuteIncrement will return an instance of an IMutateOperationResult

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist.

client.Remove("inventory"); //reset the counter
client.ExecuteIncrement("inventory", 100, 1); //counter will be 100
var result = client.ExecuteIncrement("inventory", 100, 1); //counter will be 101

if (! result.Success)
{
    Console.WriteLine("Increment failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecuteIncrement(key, defaultvalue, offset, validfor)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds.

client.ExecuteIncrement("inventory", 100, 1, TimeSpan.FromSeconds(60));

API Call	object.ExecuteIncrement(key, defaultvalue, offset, expiresat)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes.

client.ExecuteIncrement("inventory", 100, 1, DateTime.Now.AddMinutes(5));

API Call	object.ExecuteIncrement(key, defaultvalue, offset, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteIncrement("inventory", 100, 1, result.Cas);

API Call	object.ExecuteIncrement(key, defaultvalue, offset, validfor, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 60 seconds. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteIncrement("inventory", 100, 1, TimeSpan.FromSeconds(60), result.Cas);

API Call	object.ExecuteIncrement(key, defaultvalue, offset, expiresat, casunique)
Asynchronous	no
Description	Increment the value of an existing numeric key. Couchbase Server stores numbers as unsigned numbers, therefore if you try to increment an existing negative number, it will cause an integer overflow and return a non-logical numeric result. If a key does not exist, this method will initialize it with the zero or a specified value.
Returns	IMutateOperationResult ( Mutate operation result )
Arguments
string key	Document ID used to identify the value
object defaultvalue	Value to be stored if key does not already exist
Integer offset	Integer offset value to increment/decrement (default 1)
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

Increment the inventory counter by 1, defaulting to 100 if the key doesn’t exist and set an expiry of 5 minutes. Fail if CAS value doesn’t match CAS value on server.

var result = client.ExecuteGet("inventory");
client.ExecuteIncrement("inventory", 100, 1, DateTime.Now.AddMinutes(5), result.Cas);

Prepend Methods¶

The Prepend() methods allow you to add information to an existing key/value pair in the database. You can use this to add information to a string or other data after the existing data.

The Prepend() methods prepend raw serialized data on to the end of the existing data in the key. If you have previously stored a serialized object into Couchbase and then use Prepend, the content of the serialized object will not be extended. For example, adding an List of integers into the database, and then using Prepend() to add another integer will result in the key referring to a serialized version of the list, immediately followed by a serialized version of the integer. It will not contain an updated list with the new integer prepended to it. De-serialization of objects that have had data prepended may result in data corruption.

API Call	object.Prepend(key, value)
Asynchronous	no
Description	Prepend a value to an existing key
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value
object value	Value to be stored

The Prepend() method prepends information to the end of an existing key/value pair.

The sample below demonstrates how to create a csv string by prepending new values.

client.Store(StoreMode.Set, "beers", "Abbey Ale");
Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
client.Prepend("beers", new ArraySegment<byte>(stringToBytes(",Three Philosophers")));
client.Prepend("beers", new ArraySegment<byte>(stringToBytes(",Witte")));

You can check if the Prepend operation succeeded by checking the return value.

var result = client.Prepend("beers", new ArraySegment<byte>(stringToBytes(",Hennepin")));
if (result) {
    Console.WriteLine("Prepend succeeded");
} else {
    Console.WriteLine("Prepend failed");
}

API Call	object.Prepend(key, casunique, value)
Asynchronous	no
Description	Prepend a value to an existing key
Returns	Object ( Binary object )
Arguments
string key	Document ID used to identify the value
ulong casunique	Unique value used to verify a key/value combination
object value	Value to be stored

The Prepend operation may also be used with a CAS value.

var storeResult = client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");

Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
client.Prepend("beers", storeResult.Cas, new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

API Call	object.ExecutePrepend(key, value)
Asynchronous	no
Description	Prepend a value to an existing key
Returns	IConcatOperationResult ( Concat operation result )
Arguments
string key	Document ID used to identify the value
object value	Value to be stored

The ExecutePrepend operation is used to get an instance of an IConcatOperationResult.

client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");
Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
var result = client.ExecutePrepend("beers", new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

if (! result.)
{
    Console.WriteLine("Prepend failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

API Call	object.ExecutePrepend(key, casunique, value)
Asynchronous	no
Description	Prepend a value to an existing key
Returns	IConcatOperationResult ( Concat operation result )
Arguments
string key	Document ID used to identify the value
ulong casunique	Unique value used to verify a key/value combination
object value	Value to be stored

The ExecutePrepend operation may also be used with a CAS value.

var storeResult = client.ExecuteStore(StoreMode.Set, "beers", "Abbey Ale");

Func<string, byte[]> stringToBytes = (s) => Encoding.Default.GetBytes(s);
var prependResult = client.ExecutePrepend("beers", storeResult.Cas, new ArraySegment<byte>(stringToBytes(",Three Philosophers")));

if (! prependResult.)
{
    Console.WriteLine("Prepend failed with message {0} and status code {1}", prependResult.Message, prependResult.StatusCode);

    if (prependResult.Exception != null)
    {
        throw prependResult.Exception;
    }
}

Touch Methods¶

The Touch() methods allow you to update the expiration time on a given key. This can be useful for situations where you want to prevent an item from expiring without resetting the associated value. For example, for a session database you might want to keep the session alive in the database each time the user accesses a web page without explicitly updating the session value, keeping the user’s session active and available.

API Call	object.Touch(key, expiry)
Asynchronous	no
Description	Update the expiry time of an item
Returns	Boolean ( Boolean (true/false) )
Arguments
string key	Document ID used to identify the value
object expiry	Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

The Touch method provides a simple key/expiry call to update the expiry time on a given key. For example, to update the expiry time on a session for another 60 seconds:

client.Touch("session", TimeSpan.FromSeconds(60));

To update the expiry time on the session for another day:

client.Touch("session", DateTime.Now.AddDays(1));

CAS Methods¶

The check-and-set methods provide a mechanism for updating information only if the client knows the check (CAS) value. This can be used to prevent clients from updating values in the database that may have changed since the client obtained the value. Methods for storing and updating information support a CAS method that allows you to ensure that the client is updating the version of the data that the client retrieved.

The check value is in the form of a 64-bit integer which is updated every time the value is modified, even if the update of the value does not modify the binary data. Attempting to set or update a key/value pair where the CAS value does not match the value stored on the server will fail.

• The behavior of Cas and ExecuteCas operations is defined by setting the first parameter to a value from the StoreMode enumeration. StoreMode.Add - Add a key to the database, failing if the key exists

• StoreMode.Replace - Replace a key in the database, failing if the key does not exist

• StoreMode.Set - Add a key to the database, replacing the key if it already exists

API Call	object.Cas(storemode, key, value)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	CasResult<bool> ( Cas result of bool )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored

The Cas() method is used to persist new values by key. Any class decorated with the Serializable attribute may be stored. The CAS value is returned by way of a CasResult

var casResult = client.Cas(StoreMode.Add, "beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Company",
    Name = "American Ale"
});

if (casResult.Result)
{
    Console.WriteLine("Cas: ", casResult.Cas);
}

API Call	object.Cas(storemode, key, value, validfor, casunique)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	CasResult<bool> ( Cas result of bool )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

client.Cas(StoreMode.Set, "beer", new Beer() {
    Brewer = "Peak Organic Brewing Company",
    Name = "IPA"
}, TimeSpan.FromSeconds(60));

API Call	object.Cas(storemode, key, value, expiresat, casunique)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	CasResult<bool> ( Cas result of bool )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

client.Cas(StoreMode.Replace, "beer", new Beer() {
    Brewer = "Six Point Craft Ales",
    Name = "Righteous Rye"
}, DateTime.Now.Addhours(1));

API Call	object.ExecuteCas(storemode, key, value)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored

The ExecuteCas() methods are similar to the Cas methods, but return an instance of an IStoreOperationResult.

var result = client.ExecuteCas(StoreMode.Add, "beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Company",
    Name = "American Ale"
});

if (! result.Success)
{
    Console.WriteLine("Store failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

client.ExecuteCas(StoreMode.Replace"beer", new Beer() {
    Brewer = "Thomas Hooker Brewing Co.",
    Name = "American Ale"
}, result.Cas);

API Call	object.ExecuteCas(storemode, key, value, validfor, casunique)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
TimeSpan validfor	Expiry time (in seconds) for key
ulong casunique	Unique value used to verify a key/value combination

client.ExecuteCas(StoreMode.Set, "beer", new Beer() {
    Brewer = "Peak Organic Brewing Company",
    Name = "IPA"
}, TimeSpan.FromSeconds(60));

API Call	object.ExecuteCas(storemode, key, value, expiresat, casunique)
Asynchronous	no
Description	Compare and set a value providing the supplied CAS key matches
Returns	IStoreOperationResult ( Store operation result )
Arguments
StoreMode storemode	Storage mode for a given key/value pair
string key	Document ID used to identify the value
object value	Value to be stored
DateTime expiresat	Explicit expiry time for key
ulong casunique	Unique value used to verify a key/value combination

client.ExecuteCas(StoreMode.Replace, "beer", new Beer() {
    Brewer = "Six Point Craft Ales",
    Name = "Righteous Rye"
}, DateTime.Now.Addhours(1));

View/Query Interface¶

Provides support for views. For more information about using views for indexing and querying from Couchbase Server, here are some useful resources:

• For more information on Views, how they operate, and how to write effective map/reduce queries, see Couchbase Server 2.0: Views and Couchbase Sever 2.0: Writing Views.

• Sample Patterns: to see examples and patterns you can use for views, see Couchbase Views, Sample Patterns.

• Timestamp Pattern: many developers frequently ask about extracting information based on date or time. To find out more, see Couchbase Views, Sample Patterns.

View Interface

GetView(designName, viewName)

GetView takes a

• designName

  Design document name.

• viewName

  View name.

There is also a generic version of GetView, which returns view items that are stongly typed.

GetData<T>(designName, viewName)

Both versions of GetView return an IView, which implements IEnumerable. Therefore, when you query for the items in a view, you can iterate over the returned collection as folows:

var beersByNameAndABV = client.GetView<Beer>("beers", "by_name_and_abv");
foreach(var beer in beersByNameAndABV) {
            Console.WriteLine(beer.Name);
}

or the non-generic version:

var beersByNameAndABV = client.GetView("beers", "by_name_and_abv");
foreach(var row in beersByNameAndABV) {
            Console.WriteLine((row.GetItem() as Beer).Name);
}

As you can see, when you iterate over a strongly typed view each item is of the type you specified. If you use the non-generic version, each item you enumerate over will be of type IViewRow. IViewRow provides methods for accessing details of the row that are not present when using strongly typed views.

To get the original document from the datastore:

row.GetItem();

To get a Dictionary representation of the row:

row.Info;

To get the original document’s ID (key):

row.ItemId;

To get the key emitted by the map function:

row.ViewKey;

Before iterating over the view results, you can modify the query that is sent to the server by using the fluent methods of IView. Refer to the sample document and view below when exploring the IView API.

//map function
function(doc) {
              if (doc.type == "beer") {
                 emit([doc.name, doc.abv], doc);
                 }
}

//sample json document
{
  "_id" : "beer_harpoon_ipa",
  "name" : "Harpoon IPA",
  "brewery" : "brewery_harpoon",
  "abv" : 5.9
}

To find beers with names starting with “H” and an ABV of at least 5:

var beersByNameAndABV = client.GetView("beers", "by_name_and_abv")
                                                                       .StartKey(new object[] { "H", 5 });

To limit the number of beers returned by the query to 10:

var beersByNameAndABV = client.GetView("beers", "by_name_and_abv")
                                                                       .Limit(10);

To group the results (when using _count for example):

var beersByNameAndABV = client.GetView("breweries", "breweries_by_state")
                                                                       .Group(true);

To disallow stale results in the view:

var beersByNameAndABV = client.GetView("beers", "by_name_and_abv")
                                                                       .Stale(StaleMode.False);

IView API methods may be chained. To limit the number of results to 5 and order the results descending:

var beersByNameAndABV = client.GetView("beers", "by_name_and_abv")
                                                                       .Limit(5).Descending(true);

.Net Troubleshooting¶

Bulk Load and Exponential Backoff¶

When you bulk load data to Couchbase Server, you can accidentally overwhelm available memory in the Couchbase cluster before it can store data on disk. If this happens, Couchbase Server will immediately send a response indicating the operation cannot be handled at the moment but can be handled later.

This is sometimes referred to as “handling Temp OOM”, where where OOM means out of memory. Note though that the actual temporary failure could be sent back for reasons other than OOM. However, temporary OOM is the most common underlying cause for this error.

To handle this problem, you could perform an exponential backoff as part of your bulk load. The backoff essentially reduces the number of requests sent to Couchbase Server as it receives OOM errors:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Couchbase;
using Couchbase.Configuration;
using Enyim.Caching.Memcached.Results;
using Enyim.Caching.Memcached;
using System.Threading;

namespace BulkLoader
{
    public class StoreHandler
    {
        CouchbaseClient _cbc;

        public StoreHandler(IList<Uri> uris, string bucketName, string bucketPassword)
        {
            var config = new CouchbaseClientConfiguration();
            foreach (var uri in uris)
            {
                config.Urls.Add(uri);
            }
            config.Bucket = bucketName;
            config.BucketPassword = bucketPassword;

            _cbc = new CouchbaseClient(config);
        }


        /// Perform a  regular Store with storeMode.Set

        public IStoreOperationResult Set(string key, object value)
        {
            return _cbc.ExecuteStore(StoreMode.Set, key, value);
        }

        /// Continuously try a set with exponential backoff until number of tries or
        /// successful.  The exponential backoff will wait a maximum of 1 second, or whatever

        public IStoreOperationResult Set(string key, object value, int tries)
        {
            var backoffExp = 0;
            var tryAgain = false;
            IStoreOperationResult result = null;

            try
            {
                do
                {
                    if (backoffExp > tries)
                    {
                        throw new ApplicationException("Could not perform a set after " + tries + " tries.");
                    }

                    result = _cbc.ExecuteStore(StoreMode.Set, key, value);
                    if (result.Success) break;

                    if (backoffExp > 0)
                    {
                        var backOffMillis = Math.Pow(2, backoffExp);
                        backOffMillis = Math.Min(1000, backOffMillis); //1 sec max
                        Thread.Sleep((int)backOffMillis);
                        Console.WriteLine("Backing off, tries so far: " + backoffExp);
                    }
                    backoffExp++;

                    if (! result.Success)
                    {
                        var message = result.InnerResult != null ? result.InnerResult.Message : result.Message;
                        Console.WriteLine("Failed with status: " + message);
                    }

                    //Future versions of the .NET client will flatten the results and make checking for
                    //InnerResult objects unnecessary
                    tryAgain = (result.Message != null && result.Message.Contains("Temporary failure") ||
                                result.InnerResult != null && result.InnerResult.Message.Contains("Temporary failure"));

                } while (tryAgain);

            }
            catch (Exception ex)
            {
                Console.WriteLine("Interrupted while trying to set.  Exception:" + ex.Message);
            }

            // note that other failure cases fall through.  status.isSuccess() can be
            // checked for success or failure or the message can be retrieved.
            return result;

        }
    }
}

Appendix: Working with Operation Results¶

The following sections provide details on working with the IOperationResult interface.

CouchbaseClient ’s standard CRUD operations return Boolean values. When exceptions or failures occur, they are swallowed and false is returned.

While there might be scenarios where the cause of a failure is not important (e.g., non-persistent cache), it is likely that access to error information is necessary. To that end, the CouchbaseClient provides a set of complimentary ExecuteXXX methods, where XXX is the name of a standard CRUD operation.

var success = client.Get("foo"); //returns a Boolean

var result = client.ExecuteGet("foo"); //returns an IOperationResult

All ExecuteXXX methods return an instance of an implementation of the IOperationResult interface.

public interface IOperationResult
{
    bool Success { get; set; }

    string Message { get; set; }

    Exception Exception { get; set; }

    int? StatusCode { get; set; }

    IOperationResult InnerResult { get; set; }
}

For each of the ExecuteXXX methods, a typical use pattern would be to interrogate the possible error values on failure.

var result = client.ExecuteStore(StoreMode.Add, "foo", "bar");

if (! result.Success)
{
    Console.WriteLine("Store operation failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

The Message property will contain details as to why an operation failed. The message might be from the server or it could be from the client. The StatusCode property is a Nullable<int> that will be populated from the server’s response.

Note that the 1.1 release of the OperationResult API wrapped lower level (networking) exceptions in an InnerResult object. Since release 1.2, InnerResult is no longer populated. The property still remains so as to be backwards compatible.

Like the standard CRUD methods, the Execute methods will swallow exceptions. However, caught exceptions are passed back to the caller by way of the Exception property. This allows the caller to check for an exception and throw it if exception behavior is desired.

There are several interfaces that extend IOperationResult to provide additional properties. Two important interfaces are the INullableOperationResult<T> and ICasOperationResult

public interface INullableOperationResult<T> : IOperationResult
{
    bool HasValue { get; }
    T Value { get; set; }
}

public interface ICasOperationResult : IOperationResult
{
    ulong Cas { get; set; }
}

The INullableOperationResult<T> interface is extended by the IGetOperationResult, providing Get operations with properties to get the retrieved value.

var result = client.ExecuteGet("foo");

if (! result.Success)
{
    Console.WriteLine("Get operation failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

if (result.HasValue)
{
    var value = result.Value;
}
else if (result.StatusCode == 1)
{
    Console.WriteLine("Key does not exist");
}

IGetOperationResult also extends ICasOperationResult. Therefore, it is possible to get the CAS value from an ExecuteGet operation. The snippet below demonstrates the generic ExecuteGet method.

var result = client.ExecuteGet<City>("CT_Hartford");

if (result.Success)
{
    var city = result.Value;
    city.Population = 124775;
    client.ExecuteStore(StoreMode.Set, "CT_Hartford", city, result.Cas); //will fail if Cas is not the same value on server
}

ExecuteStore methods return IStoreOperationResult instances.

var result = client.ExecuteStore(StoreMode.Add, "foo", "bar");

if (! result.Success)
{
    Console.WriteLine("Get operation failed with message {0} and status code {1}", result.Message, result.StatusCode);

    if (result.StatusCode == 2)
    {
        Console.WriteLine("Key already exists");
    }

    if (result.Exception != null)
    {
        throw result.Exception;
    }
}

IStoreOperationResult also extends ICasOperationResult. Therefore, it is possible to get the CAS value from an ExecuteStore operation.

var city = new City() { Name = "Hartford", State = "CT" };
var result = client.ExecuteStore(StoreMode.Add, "CT_Hartford", city);

if (result.Success)
{
    city.Population = 124775;
    client.ExecuteStore(StoreMode.Set, "CT_Hartford", city, result.Cas); //will fail if Cas is not the same value on server
}

The IMutateOperationResult, IConcatOperationResult interfaces also return the CAS value. These interfaces are returned by ExecuteIncrement/ExecuteDecrement and ExecuteAppend/ExecutePrepend respectively. IRemoveOperationResult includes only the properties found in IOperationResult.

For more information on which API methods support ExecuteXXX variants, see the API reference.

Appendix: JSON Extension Methods¶

The following sections provide details on how to use the CouchbaseClient JSON extensions.

The Couchbase.Extensions namespace contains a series of extension methods that provide out of the box support for storing and retrieving JSON with Couchbase Server. These methods use JSON.NET, and provide only limited customization. If your JSON serialization needs are advanced, you will need to provide your own methods to work with JSON.

To use the JSON extensions in your application, you’ll first need to include a using block for the extensions namespace

using Couchbase.Extensions;

Once that using directive has been added, an instance of an ICouchbaseClient will be able to execute various JSON methods.

Generally speaking, for each store or get method, there is a corresponding Json method.

//Person will be stored using binary serialization
    var storeResult = client.ExecuteStore(StoreMode.Set, "person1", new Person { Name = "John" });

    //Person will be stored as a view-ready, JSON string { name : "John" }
    var storeJsonResult = client.ExecuteStoreJson(StoreMode.Set, "person2", new Person { Name = "John" });

    //getResult.Value will contain an instance of a Person
    var getResult = client.ExecuteGet<Person>("person1");

    //InvalidCastException will be thrown, since "person1" contains a binary value
    var getJsonResult = client.ExecuteGetJson<Person>("person1");

    //Invalid cast exception, because person2 contains a string
    var getResult = client.ExecuteGet<Person>("person2");

    //getJsonResult.Value will contain an instance of a Person
    var getJsonResult = client.ExecuteGetJson<Person>("person2");

ExecuteStoreJson is overloaded to provide support for key expiration, and durability requirements.

var person = new Person { Name = "John" };

    //key will expire in 10 minutes
    var storeJsonResult1 = client.ExecuteStoreJson(StoreMode.Set, "john", person, DateTime.Now.AddMinutes(10));

    //key will expire in 10 minutes
    var storeJsonResult2 = client.ExecuteStoreJson(StoreMode.Set, "john", person, TimeSpan.FromMinutes(10));

    //storeJsonResult3 will fail unless the key is written to disk on its master node, and replicated to two nodes
    var storeJsonResult3 = client.ExecuteStoreJson(StoreMode.Set, "john", person, PersistTo.One, ReplicateTo.Two);

CAS operations are also available via the ExecuteCasJson extension method.

var person = new Person { Name = "John" };

    var getResult = client.ExecuteGetJson("key");
    getResult.Value.Name = "John Z";

    //would fail if the CAS value has changed on the server since it was retrieved
    var casResult = client.ExecuteCasJson(StoreMode.Set, "key", getResult.Value, getResult.Cas);

The JSON extensions make an important assumption about your model objects, and how they serialize and deserialize them. It is important that you understand this assumption before using these methods. Consider the following Person class:

public class Person
{
  public string Id { get; set; }

  public string Type { get { return "person"; } }

  public string Name { get; set; }
}

The assumption is that the Id property of a domain object is meant to be mapped to the key in the key/value used to store your data.

var person = new Person { Id = "person_12345", Name = "Tony Soprano" };

var storeResult = client.ExecuteStoreJson(StoreMode.Set, person.Id, person);

//the JSON would be:
//{ "name" : "Tony Soprano", type : "person" }

When the JSON is saved, it will ignore the Id property and its value. Since it is assumed that the Id is the key, it would be redundant to include it in the saved JSON. Moreover, it would also be a challenge to keep the key in sync with the JSON.

When the Person is retrieved, the ExecuteGetJson method will automatically map the Id property to the key. This mapping is achieved by inserting the key as an “id” property in the JSON document before it is deserialized.

var getResult = client.ExecuteGetJson<Person>("person_12345");

Console.WriteLine("Id: " + Person.Id);
//Id: person_12345

The importance of how the “id” property is mapped is that you are able to take advantage of JSON.NET attributes to have some control over which property is your “Id” property. If you wanted to map the key to a Key property, then you could use the JsonProperty attribute as below. Note however, that should you use this mapping, it will override the ignore “id” on write and you’ll have your key in the JSON.

public class Person
{
  [JsonProperty("Id")]
  public string Key { get; set; }

  public string Type { get { return "person"; } }

  public string Name { get; set; }
}

The default behavior of the JSON extensions works well with strongly typed views, which will also map an Id property of a class to its key as you iterate over the view.

var view = client.GetView<Person>("people", "by_name", true).Key("Tony Soprano");
var person = view.FirstOrDefault();

Console.WriteLine("Id: " + Person.Id);
//Id: person_12345

Appendix: Configuring the.NET Client Library¶

The following sections provide details on the App|Web.config configuration options for the.NET Client Library

The CouchbaseClientSection class is the configuration section handler.

<section name="couchbase" type="Couchbase.Configuration.CouchbaseClientSection, Couchbase"/>

The minimum configuration options are to include a couchbase section with a servers element with at least one URI, which is used to bootstrap the client. At least two node URIs should be provided, so that in the event that the client can’t reach the first, it will try the second.

• bucket (default) The bucket against which the client instance will perform operations

• bucketPassword The password for authenticated buckets.

• username The username used to secure a cluster.

• password The password associated with the cluster username

• retryCount The number of times to retry a failed attempt to read cluster config

• retryTimeout (00:00:02) The amount of time to wait in between failed attempts to read cluster config

• observeTimeout (00:01:00) The amount of time to wait for persistence or replication checks when using ExecuteStore or ExecuteRemove with durability requirements

• httpRequestTimeout (00:01:00) The amount of time to wait for the HTTP streaming connection to receive cluster configuration

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
</couchbase>

The “bucket” and “bucketPassword” attributes of the servers element default to “default” and an empty string respectively.

<couchbase>
    <servers bucket="default" bucketPassword="H0p$">
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
</couchbase>

The client may also be configured in code.

var config = new CouchbaseClientConfiguration();
config.Urls.Add(new Uri("http://localhost:8091/pools/"));
config.Bucket = "default";

var client = new CouchbaseClient(config);

• The socketPool element is used to configure the behavior of the client as it connects to the Couchbase cluster. Defaults are in parentheses. minPoolSize (10) The minimum number of connections in the connection pool

• maxPoolSize (20) The maximum number of connections in the connection pool

• connectionTimeout (00:00:10) The amount of time the client is waiting to a) eastablish a connection to the memcached server, b) get a free connection from the pool. If it times out the operation will fail. (And return false or null, depending on the operation.)

• deadTimeout (00:00:10) When all pool urls are unavailable the client will check the first one again after deadTimeout time elapses. Additionally, the client has a basic dead node detection mechanism which will also use this timeout to reconnect servers which went offline.

• queueTimeout (00:00:00.100) Specifies the amount of time after which the getting of a connection from the pool will fail. The default is 100 msec.

• receiveTimeout (00:00:10) The amount of time after which receiving data from the socket fails.

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <socketPool minPoolSize="10" maxPoolSize="20" />
</couchbase>

The client will periodically check the health of its connection to the cluster by performing a heartbeat check. By default, this test is done every 10 seconds against the bootstrap URI defined in the servers element.

• uri (defaults to first server Uri from servers element) The Uri used for the heartbeat check

• interval (10000ms) Frequency with which heartbeat check executes

• enabled (true) Enables or disables heartbeat check.

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <heartbeatMonitor uri="http://127.0.0.1:8091/pools/heartbeat" interval="60000" enabled="true" />
</couchbase>

When executing view queries, the client will make requests over HTTP. That connection may be managed using the httpClient element.

• initializeConnection (true) When true, the ServicePointManager is initialized asynchronously on client creation rather than on the first view request

• timeout (00:01:15) How long to wait for a view request before timing out

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <httpClient initializeConnection="false" timeout="00:00:45"/>
</couchbase>

When executing view queries, HTTP requests are made by IHttpClient instances which are created by factories. The factory is defined in the httpClientFactory element.

• type (Couchbase.RestSharpHttpClientFactory, Couchbase) The fully qualified type name of an IHttpClientFactory implementation, RestSharpHttpClientFactory is the default. HammockHttpClientFactory is also supported, but has known issues.

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <httpClientFactory type="Couchbase.RestSharpHttpClientFactory, Couchbase" />
</couchbase>

When executing view queries, the design document is toggled between dev mode (prefixed by dev_) and production mode by setting the documentNameTransformer element.

• type (Couchbase.Configuration.ProductionModeNameTransformer, Couchbase) The fully qualified type name of an INameTransformer implementation

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <documentNameTransformer type="Couchbase.Configuration.ProductionModeNameTransformer, Couchbase" />
</couchbase>

The keyTransformer is used to normalize/validate the item keys before sending them to the server.

• type (Enyim.Caching.Memcached.DefaultKeyTransformer) must be the fully qualified name of a type implementing IMemcachedKeyTransformer

• factory must be the fully qualified name of a type implementing IProviderFactory<IMemcachedKeyTransformer>

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <keyTransformer type="Enyim.Caching.Memcached.DefaultKeyTransformer, Enyim.Caching" />
</couchbase>

The transcoder is used to serialize stored/retrieved objects.

• type (Enyim.Caching.Memcached.DefaultKeyTransformer) must be the fully qualified name of a Type implementing ITranscoder

• factory must be the fully qualified name of a type implementing IProviderFactory<ITranscoder>

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <keyTransformer type="Enyim.Caching.Memcached.DefaultTranscoder, Enyim.Caching" />
</couchbase>

The transcoder is used to map objects to servers in the pool.

• type (Enyim.Caching.Memcached.DefaultKeyTransformer) must be the fully qualified name of a type implementing IMemcachedNodeLocator

• factory must be the fully qualified name of a type implementing IProviderFactory<IMemcachedNodeLocator>

<couchbase>
    <servers>
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
    <keyTransformer type="Enyim.Caching.Memcached.DefaultNodeLocator, Enyim.Caching" />
</couchbase>

It is not possible to configure (in app|web.config) a single instance of a CouchbaseClient to work with multiple buckets. Though it is possible to programmatically reconstruct a client to work with multiple buckets, it is not recommended. The process of creating a client is expensive (relative to other Couchbase operations) and should ideally be done once per app domain.

It is possible however to set multiple config sections in app|web.config to allow for multiple client instances to be created, while still maintaining bucket affinity.

<?xml version="1.0"?>
<configuration>
  <configSections>
    <sectionGroup name="couchbase">
      <section name="bucket-a" type="Couchbase.Configuration.CouchbaseClientSection, Couchbase"/>
      <section name="bucket-b" type="Couchbase.Configuration.CouchbaseClientSection, Couchbase"/>
    </sectionGroup>
  </configSections>

  <couchbase>
    <bucket-a>
      <servers bucket="default">
        <add uri="http://127.0.0.1:8091/pools" />
      </servers>
    </bucket-a>
    <bucket-b>
      <servers bucket="beernique" bucketPassword="b33rs">
        <add uri="http://127.0.0.1:8091/pools" />
      </servers>
    </bucket-b>
  </couchbase>

  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>
  </startup>
</configuration>

After defining the config sections, bucket specific clients are created by reading the appropriate config sections and passing the config section reference to the constructor of the CouchbaseClient. Again, constructing the client should not be done per operation, but rather per app domain.

var bucketASection = (CouchbaseClientSection)ConfigurationManager.GetSection("couchbase/bucket-a");
var bucketBSection = (CouchbaseClientSection)ConfigurationManager.GetSection("couchbase/bucket-b");

var clientA = new CouchbaseClient(bucketASection);
var clientB = new CouchbaseClient(bucketBSection);

clientA.ExecuteStore(StoreMode.Set, "fooA", "barA");
var itemA = clientA.Get<string>("fooA");
Console.WriteLine(itemA);

clientB.ExecuteStore(StoreMode.Set, "fooB", "barB");
var itemB = clientB.Get<string>("fooB");
Console.WriteLine(itemB);

Appendix: Configuring Logging¶

The following sections provide details on how to enable logging for the.NET Client Library

To enable logging, you can tap into the logging capabilities provided by the Enyim.Caching dependency. Enyim logging currently supports either log4net or NLog.

Start by adding a reference to either Enyim.Caching.Log4NetAdapter or Enyim.Caching.NLogAdapter. Both are available as part of the part of the client library zip file, or as separate NuGet packages.

To install via NuGet, look for either the CouchbaseLog4NetAdapter or CouchbaseNLogAdapter package.

You could also get the projects from . If you use these Visual Studio projects, you’ll need NuGet installed, as dependencies to NLog and log4Net are managed using NuGet.

For log4net, your configuration should include an enyim.com section that defines which log factory to use along with standard log4net configuration.

The log4net configuration will vary by the type of appender you are using. For more information on log4net configuration, see .

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <sectionGroup name="enyim.com">
      <section name="log" type="Enyim.Caching.Configuration.LoggerSection, Enyim.Caching" />
    </sectionGroup>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  </configSections>
  <enyim.com>
    <log factory="Enyim.Caching.Log4NetFactory, Enyim.Caching.Log4NetAdapter" />
  </enyim.com>
  <log4net debug="false">
    <appender name="LogFileAppender" type="log4net.Appender.FileAppender,log4net">
      <param name="File" value="c:\\temp\\error-log.txt" />
      <param name="AppendToFile" value="true" />
      <layout type="log4net.Layout.PatternLayout,log4net">
        <param name="ConversionPattern" value="%d [%t] %-5p %c [%x] &lt;%X{auth}&gt; - %m%n" />
      </layout>
    </appender>
    <root>
      <priority value="ALL" />
      <level value="DEBUG" />
      <appender-ref ref="LogFileAppender" />
    </root>
  </log4net>
</configuration>

You’ll also need to initialize (only once in your app) log4net in your code with the standard log4net initializer.

log4net.Config.XmlConfigurator.Configure();

NLog configuration requires setting the log factory to NLogAdapter and including the appropriate NLog configuration section.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <sectionGroup name="enyim.com">
      <section name="log" type="Enyim.Caching.Configuration.LoggerSection, Enyim.Caching" />
    </sectionGroup>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" />
  </configSections>
  <enyim.com>
    <log factory="Enyim.Caching.NLogFactory, Enyim.Caching.NLogAdapter" />
  </enyim.com>
  <nlog>
    <targets>
      <target name="logfile" type="File" fileName="c:\temp\error-log.txt" />
    </targets>
    <rules>
      <logger name="*" minlevel="Info" writeTo="logfile" />
    </rules>
  </nlog>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0" />
  </startup>
</configuration>

See https://github.com/nlog/nlog/wiki for more NLog configuration details.

Appendix: Cluster Management with the.NET Client Library¶

The following sections provide details about using the Couchbase.NET Client to manage buckets and design documents.

Cluster management is performed by using methods of the CouchbaseCluster class, which implements the ICouchbaseCluster interface, both of which are in the Couchbase.Management namespace.

using Couchbase.Management;

The CouchbaseCluster is configured using the same config definitions (code or XML) used to create instances of a CouchbaseClient. When managing the cluster with the.NET client, the cluster username and password must be provided.

<couchbase>
    <servers username="Administrator" password="qwerty" >
      <add uri="http://127.0.0.1:8091/pools"/>
    </servers>
</couchbase>

The default constructor for CouchbaseCluster looks for a section named “couchbase”. It is possible to use a named section, as follows:

var config = ConfigurationManager.GetSection("anothersection") as CouchbaseClientSection;
var cluster = new CouchbaseCluster(_config);

To configure CouchbaseCluster in code, pass an instance of an ICouchbaseClientConfiguration to the constructor.

var config = new CouchbaseClientConfiguration();
config.Urls.Add(new Uri("http://localhost:8091/pools/"));
config.Username = "Administrator";
config.Password = "qwerty";

var cluster = new CouchbaseCluster(config);

• To get a list of buckets from the server, there are two methods. Bucket[] ListBuckets() returns an array of Bucket instances, one for each bucket in the cluster

• bool TryListBuckets(out Bucket[] buckets) returns true when no errors and provides the list of buckets as an out param. When errors occur, returns false and a null buckets array

• To get a single of bucket from the server, there are two methods. Bucket GetBucket(string bucketName) returns a Bucket instance for a bucket with the given name

• bool TryGetBucket(string bucketName, out Bucket bucket) returns true when no errors and provides the named bucket as an out param. When errors occur, returns false and a null bucket

• To get the count of items in a bucket, or across buckets use the following methods: long GetItemCount(string bucketName) returns the count of items in a bucket with the given name

• long GetItemCount() returns the count of items in all buckets in a cluster

• To get the count of items in a bucket, or across buckets use the following methods: long GetItemCount(string bucketName) returns the count of items in a bucket with the given name

• long GetItemCount() returns the count of items in all buckets in a cluster

• To manage the buckets in a cluster, there are three methods. void CreateBucket(Bucket bucket) create a bucket with the given bucket properties

  //create an authenticated Couchbase bucket
   cluster.CreateBucket(
       new Bucket
           {
               Name = "newBucket",
               AuthType = AuthTypes.Sasl,
               BucketType = BucketTypes.Membase,
               Quota = new Quota { RAM = 100 },
               ReplicaNumber = ReplicaNumbers.Zero
           }
   );
  
   //create an unauthenticated Couchbase bucket
   cluster.CreateBucket(
       new Bucket
           {
               Name = "newBucket",
               AuthType = AuthTypes.None,
               BucketType = BucketTypes.Membase,
               Quota = new Quota { RAM = 100 },
               ProxyPort = 9090,
               ReplicaNumber = ReplicaNumbers.Two
           }
   );
  
   //create a memcached bucket
   cluster.CreateBucket(
       new Bucket
       {
         Name = "newBucket",
            AuthType = AuthTypes.None,
            BucketType = BucketTypes.Memcached,
            Quota = new Quota { RAM = 100 },
            ProxyPort = 9090,
            ReplicaNumber = ReplicaNumbers.Zero
       }
   );
  

• void UpdateBucket(Bucket bucket) recreates an existing bucket, updating only changed parameters.

  cluster.UpdateBucket(
       new Bucket
       {
         Name = "newBucket",
            Quota = new Quota { RAM = 128 },
            ProxyPort = 9090,
            AuthType = AuthTypes.None
       }
   );
  

• void DeleteBucket(string bucketName) deletes an existing bucket

  cluster.DeleteBucket("bucketName");
  

• To remove the data (but not design documents) from a bucket, use the FlushBucket method. void FlushBucket(string bucketName) flushes data from a bucket

  cluster.FlushBucket("bucketName");
  

• There are four methods for managing design documents with the CouchbaseCluster. bool CreateDesignDocument(string bucket, string name, string document) creates a design document on the server, using the provided JSON string as the source of the document.

  //create a production mode design document
   var json =
   @"{
       ""views"": {
           ""by_name"": {
               ""map"": ""function (doc) { if (doc.type == ""city"") { emit(doc.name, null); } }""
           }
       }
   }";
  
   var result = cluster.CreateDesignDocument("default", "cities", json);
  
   //create the same view using development mode
   var devResult = custer.CreateDesignDocument("default", "dev_cities", json);
  

• bool CreateDesignDocument(string bucket, string name, Stream source) create a design document on the server using a readable Stream instance as the source of the document.

  var stream = new FileStream("Data\CityViews.json", FileMode.Open);
   var result = cluster.CreateDesignDocument("default", "cities", stream);
  

• string RetrieveDesignDocument(string bucket, string name) Retreive a design document from a bucket

  var document = cluster.RetrieveDesignDocument("default", "cities");
  

• bool DeleteDesignDocument(string bucket, string name) Deletes a design document from a bucket

  var result = cluster.DeleteDesignDocument("default", "cities");
  

Appendix: Release Notes¶

The following sections provide release notes for individual release versions of Couchbase Client Library .NET. To browse or submit new issues, see Couchbase Client Library.NET Issues Tracker.

Release Notes for Couchbase Client Library .NET 1.2.9 GA (04 October 2013)¶

.NET Couchbase Client 1.2.9 is a follow up release to 1.2.8 and fixes the following issue:

• NCBC-308: KeyExists does not release socket pool if not found.

Release Notes for Couchbase Client Library .NET 1.2.8 GA (01 October 2013)¶

.NET Couchbase Client 1.2.8 release is a fixes the following issues:

• NCBC-301: added a new StatusCode enumeration for unifying client and server status results of operations across all clients. This also fixes a bug where socket time-out messages on the client were not returned with the operation result.
• NCBC-250: unit test improvements.
• NCBC-257: Improvements to ensure that Disposed objects do not make it through to the finalization phase of garbage collection. This should improve issues with socket time-outs and generally improve client stability and performance.

Release Notes for Couchbase Client Library .NET 1.2.6 GA (07 May 2013)¶

.NET Couchbase Client 1.2.6 fixes an issue where the 1.2.5 NuGet package contained an unsigned Enyim.Caching assembly (3.5 only). The 4.0 NuGet package was not affected.

Release Notes for Couchbase Client Library .NET 1.2.5 GA (07 May 2013)¶

.NET Couchbase Client 1.2.5 removes the RestSharp and Hammock dependencies, adds support for.NET 3.5, along with new features and bug fixes.

New Features and Behavior Changes in 1.2.5

• NCBC-231: Support for Unlock without CAS operation

  var lockResult = client.ExecuteGetWithLock("key", TimeSpan.FromSeconds(20));
  
    var storeResult = client.ExecuteStore(StoreMode.Set, "key", "new value");
    Assert.That(storeResult.Success, Is.False);
  
    var unlockResult = client.ExecuteUnlock("key"); //unlock before the timeout
    //may also use Boolean form (e.g., var boolVal = client.Unlock("key");
    Assert.That(unlockResult.Success, Is.True);
  
    var storeResult2 = client.ExecuteStore(StoreMode.Set, "key", "another new value");
    Assert.That(storeResult.Success, Is.True);
  

• The logging assemblies are now available via separate NuGet pacakges, which reference NLog and log4net via NuGet, instead of local assemblies. See CouchbaseLog4NetAdapter and CouchbaseNLogAdapater on NuGet.

• NCBC-254: JSON extensions should default to ignore Id property on add/replace/set. This change allows for compatibility with the generic view queries, which map the key to an Id property.

  var thing = new Thing { Id = key, SomeProperty = "Foo", SomeOtherProperty = 17 };
    var result = _Client.StoreJson(StoreMode.Set, key, thing);
    Assert.That(result, Is.True);
  
    //An "Id" property will be removed from the stored JSON
    var obj = _Client.Get<string>(key);
    Assert.That(obj, Is.Not.StringContaining("&quot;id&quot;"));
  
    //GetJson will automatically assign the key to an Id property
    var savedThing = _Client.GetJson<Thing>(key);
    Assert.That(savedThing.Id, Is.StringContaining(key));
  

• NCBC-246: The.NET Client Library is now code compatible with the .NET Framework version 3.5. The NuGet package and release zip file contain both 4.0 and 3.5 assemblies. The solution (see GitHub) now includes a Couchbase .Net35 project.

• NCBC-247: RestSharp and Hammock are no longer dependencies of the Couchbase.NET Client Library.

  No change should be necessary, unless using explicit RestSharp or Hammock configuration for the HttpClientFactory. If not, the default configuration will use the new HttpClientFactory, which relies only on WebClient. In 1.2.4, the default HttpClientFactory relied on RestSharp.

  RestSharp and Hammock will be usable via a separate NuGet project, or from the Couchbase.HttpClients project (via GitHub). These assemblies will not be signed, to avoid collisions with a custom RestSharp, which is unsigned.

Fixes in 1.2.5

• NCBC-256: Throw exception when lock expiry exceeds server limit (30 seconds)

  try {
    var lockResult = client.ExecuteGetWithLock("key", TimeSpan.FromSeconds(40));
    } catch (ArgumentOutOfRangeException ex) {
    //handle exception
    }
  

Release Notes for Couchbase Client Library .NET 1.2.4 GA (02 April 2013)¶

.NET Couchbase Client 1.2.4 adds support for Get with Lock feature, along with bug fixes.

New Features and Behavior Changes in 1.2.4

• NCBC-238: Support for key exists check without getting value.

  Observe is used behind the scenes to support the check. KeyExists method checks that key is either in FoundPersisted or FoundNotPersisted state on master node.

  var exists = client.KeyExists("foo");
  

• NCBC-231: Support for Get with Lock

  var lockResult = client.ExecuteGetWithLock("key", TimeSpan.FromSeconds(30));
    var storeResult = client.ExecuteStore(StoreMode.Set, "key", "new value");
    Assert.That(storeResult.Success, Is.False);
    Assert.That(storeResult.StatusCode.Value, Is.EqualTo((int)StatusCodeEnums.DataExistsForKey));
  
    //or
    var getLockResultA = client.ExecuteGetWithLock("key");
    var getLockResultB = client.ExecuteGetWithLock("key");
    Assert.That(getLockResultB.StatusCode, Is.EqualTo((int)CouchbaseStatusCodeEnums.LockError));
  

Fixes in 1.2.4

• NCBC-239: Fix to set RestSharpHttpClient.Timeout property correctly. Was previously being set to TimeSpan.Milliseconds instead of total TimeSpan.Milliseconds.

• NCBC-243: Fix to fail store operations when PersistTo or ReplicateTo durability requirements could not be satisfied by number of online nodes.

Release Notes for Couchbase Client Library .NET 1.2.3 GA (08 March 2013)¶

.NET Couchbase Client 1.2.3 GA addresses an invalid strong name issue with Enyim.Caching in release 1.2.2.

Release Notes for Couchbase Client Library .NET 1.2.2 GA (05 March 2013)¶

.NET Couchbase Client 1.2.2 GA provides stability fixes and new API methods.

New Features and Behavior Changes in 1.2.2

• NCBC-229: Support Remove with CAS operation.

  var getResult = client.ExecuteGet("key");
    var removeResult = client.ExecuteRemove("key", getResult.Cas);
  

Fixes in 1.2.2

• NCBC-234: Fix to include CAS on return of ExecuteGetJson extension method.

• NCBC-228: Fix for concurrency issues during rebalance lead to frequent PooledSocket errors.

Known Issues in 1.2.2

• The 1.2.2 release contains an Enyim.Caching assembly with an invalid strong name.

Release Notes for Couchbase Client Library .NET 1.2.1 GA (05 February 2013)¶

.NET Couchbase Client 1.2.1 GA provides stability fixes and new API methods.

New Features and Behavior Changes in 1.2.1

• NCBC-165: IView now includes a CheckExists method, which will allow callers to verifiy that a view exists in a design document prior to executing a view query. This method will perform an HTTP request to get the design document contents.

  var view = client.GetView("cities", "by_name");
  
    if (view.CheckExists())
    {
    foreach(var item in view)
    {
    //do something
    }
    }
  

• NCBC-179: Additional JSON extensions are now available. For each Store or ExecuteStore method in the ICouchbaseClient API, there is now a corresponding JSON method. These additions include methods for CAS and expiry overloads. An ExecuteGetJson method has also been provided. Note these methods are intentionally not included in the ICouchbaseClient interface as they are explicitly tied to Newtonsoft.Json and its default serialization rules.

  //store
    var city = new City { Name = "Hartford", State = "CT", Type = "city" };
    var result = client.ExecuteStoreJson(StoreMode.Set, "city_Hartford_CT", city, DateTime.Now.AddMinutes(30));
    //get
    var otherCity = client.ExecuteGetJson<City>("city_Bridgeport_CT");
  

• NCBC-159: Support for getting debug info from views.

  var view = client.GetView("cities", "by_name").Debug(true);
    view.Count(); //need to execute the query to get debug info
    var local = view.DebugInfo["local"]; //DebugInfo is a dictionary
  

• NCBC-190: CouchbaseCluster now has method FlushBucket. Creating buckets with flush enabled is also supported.

  var cluster = new CouchbaseCluster(config);
    cluster.CreateBucket(new Bucket
    {
    Name = "transaction",
    AuthType = AuthTypes.Sasl,
    BucketType = BucketTypes.Membase,
    Quota = new Quota { RAM = 100 },
    ReplicaNumber = ReplicaNumbers.Zero,
    FlushOption = FlushOptions.Enabled
    });
    //and flushing
    cluster.FlushBucket("transaction");
  

Fixes in 1.2.1

• NCBC-166: The DefaultKeyTransformer no longer forbids chars 0x00-0x20 and space. To provide support for legacy Memcached key rules, the LegacyMemcachedKeyTransformer may be used.

  <keyTransformer type="Enyim.Caching.Memcached.LegacyMemcachedKeyTransformer, Enyim.Caching" />
  

• NCBC-189: Fix to NRE when ExecuteIncrement or ExecuteDecrement returned null StatusCode.

• NCBC-195: NRE no longer thrown when client cannot locate a node on which to execute a view. The lack of available nodes is logged in the debug log and an InvalidOperationException is intentionally raised. NCBC-222: is tracking a 1.2.2 fix for an improved exception type.

• NCBC-172: 1.2.0 Hammock dependency was throwing a null reference exception when executing a view query against an offline node. The 1.2.1 release replaces Hammock with RestSharp for view execution. Hammock is still supported, but RestSharp is the new default. If Hammock is explicitly configured, then Hammock will still be used for view execution. RestSharp is the suggested view REST library. To ensure RestSharp is in use, App|Web.config must not contain snippet below. If configured in code, the HttpClientFactory should not be set.

  <httpClientFactory type="Couchbase.HammockHttpClientFactory, Couchbase" />
  

• NCBC-197: When 0 bytes are received on sockets, but read was valid, Enyim client was throwing an exception with the message “?.” A descriptive exception message is now included.

• NCBC-192: NRE was being thrown when executing ops against a down node. NRE was also the symptom displayed when app client configuration was incorrect. Ops against a bad node should now return the message “Unable to locate node” when using the IOperationResult methods. There is a constant for this error.

  var result = client.ExecuteGet("somekey");
   if (! result.Success && result.Message == ClientErrors.FAILURE_NODE_NOT_FOUND)
   {
    //couldn’t reach the node, check config if first run of app
   }
  

• NCBC-212: ExecuteRemove is no longer swallowing status codes on errors. StatusCode property was always null previously on errors.

Known Issues in 1.2.1

• NCBC-223: Mono support not included for 1.2.1. ServicePointManager.SetTcpKeepAlive is not supported by Mono. A 1.2.0 build was released with this call removed, however a better solution should be in place for 1.2.2.

Release Notes for Couchbase Client Library .NET 1.2.0 GA (12 December 2012)¶

Couchbase Client 1.2 GA is the first GA release to support Couchbase Server 2.0. 1.2 is backwards compatible with Couchbase Server 1.8.

In addition to support for new features of Couchbase Server 2.0, the Couchbase.NET Client Library 1.2 adds stability improvements to iteself and its dependent Enyim.Caching library.

The Couchbase.NET Client Library 1.2 requires the.NET Framework 4.0 or higher.

Fixes in 1.2.0

• NCBC-168: Socket errors were previously being swallowed and did not bubble up through ExecuteXXX method return values.

• NCBC-161: Run views only on nodes in cluster supporting couchApiBase (Couchbase nodes)

Known Issues in 1.2.0

• NCBC-172: During a rebalance or fail over, view queries may result in an unhandled NullReferenceException. This exception is raised by a thread in the dependency Hammock.

• NCBC-170: If an exception occurs before data are read, the PooledSocket may be returned to the pool marked still alive and with a dirty buffer. In some situations, a wrong magic value error may result.

• NCBC-176: Flushing of buckets is not yet supported in Couchbase.Management API

Release Notes for Couchbase Client Library .NET 1.2.0-BETA-3 Beta (28 November 2012)¶

New Features and Behavior Changes in 1.2.0-BETA-3

• New CouchbaseCluster GetItemCount method (NCBC-92)

• View timeout is now configuragble (NCBC-158)

• Implemented remove with observe (NCBC-163)

• ListBucket object graph now matches full server JSON (NCBC-142)

• New UpdateBucket method on CouchbaseCluster (NCBC-143)

• ICouchbaseClient interface completed to match CouchbaseClient public methods (NCBC-151)

• Auto-map Id property to “id” field in view rows on generic view queries (NCBC-154)

• Debug now supported as view parameter (NCBC-159)

• Add support to build under Mono (NCBC-132)

• (Experimental) support for spatial views (NCBC-47).

• New CouchbaseCluster GetBucket and TryGetBucket methods to get single bucket (NCBC-72)

Fixes in 1.2.0-BETA-3

• ExecuteGet no longer reports “failed to locate node” on cache misses (NCBC-130)

• Don’t swallow pooled socket errors (NCBC-168)

• View requests are now made to a randomly selected node from cluster (NCBC-146)

• Observe reliability fixes (NCBC-129, NCBC-128, NCBC-124, NCBC-127)

• Failed bootstrap node no longer puts client in invalid state (NCBC-134).

• Null reference exceptions now longer (occasionally) thrown during rebalancing.

• Updated Enyim submodule reference to latest commit (NCBC-167)

• Pre-fetch views to cache network pools for view requests (NCBC-149)

• Client now handles correctly -1 vbucket indexes in cluster config (NCBC-148)

• Null reference exceptions now longer (occasionally) thrown during rebalancing (NCBC-121).

• HTTP and connection timeouts are now separate (NCBC-34)

• Deleted keys return null during generic view queries with non-stale iterations (NCBC-157)

• Delete bucket handles 500 error from server (NCBC-119)

• No longer disposing Timer in heartbeat check when it’s disabled (NCBC-136)

Known Issues in 1.2.0-BETA-3

• Delete bucket request succeeds but exception is thrown.

Release Notes for Couchbase Client Library .NET 1.2.0-DP4 Alpha (27 August 2012)¶

New Features and Behavior Changes in 1.2.0-DP4

• New bucket administration methods

  var cluster = new CouchbaseCluster("couchbase"); //name of config section with credentials
    cluster.CreateBucket(new Bucket { … });
    var buckets = cluster.ListBuckets();
    cluster.DeleteBucket();
  

• New, basic JSON conversion extension methods for serializing objects to and from JSON. Methods use Newtonsoft.Json for JSON conversions.

  using Couchbase.Extensions;
    var result = client.StoreJson<Beer>(StoreMode.Set, "foo", new Beer { … });
    var beer = client.GetJson<Beer>("foo");
  

• 1.2.0 specific configuration elements (HttpClientFactory and DocumentNameTransformer) now have defaults and 1.1 configuration will work with 1.2.0.

  using Couchbase.Extensions;
    var result = client.StoreJson<Beer>(StoreMode.Set, "foo", new Beer { … });
    var beer = client.GetJson<Beer>("foo");
  

• New design document administration methods

  var cluster = new CouchbaseCluster("couchbase"); //name of config section with credentials
    cluster.CreateDesignDocument("bucketname", "{ … }");
    var designDoc = cluster.RetrieveDesignDocument("bucketname", "designdocname");
    cluster.DeleteDesignDocument("bucketname", "designdocname");
  

Fixes in 1.2.0-DP4

• Observe tests no longer fail on multi-node persistence/replication checks.

Release Notes for Couchbase Client Library .NET 1.2.0-DP3 Alpha (27 August 2012)¶

New Features and Behavior Changes in 1.2.0-DP3

• Initial implementation of Observe and Store with durability checks.

  //check for master persistence
    var result = client.ExecuteStore(StoreMode.Set, "foo", "bar", PersistTo.One);
  
    //check for master persistence with replication to 2 nodes
    var result = client.ExecuteStore(StoreMode.Set, "foo", "bar", PersistTo.One, ReplicateTo.Two);
  

Known Issues in 1.2.0-DP3

• Multi-node persistence/replication checks fail sporadically on observe.

Release Notes for Couchbase Client Library .NET 1.2.0-DP2 Alpha (25 July 2012)¶

Fixes in 1.2.0-DP2

• Generic view requests no longer emitting the original document as value. Client Get method is used instead to retrieve original document.

• Reduced views no longer break from missing “id” field in row.

• Paging no longer breaks.

• DevelopmentModeNameTransformer now correctly prepends dev_ on view requests.

Release Notes for Couchbase Client Library .NET 1.2-DP Alpha (27 March 2012)¶

New Features and Behavior Changes in 1.2-DP

• Initial support for Couchbase Server 2.0 view API.

  var view = client.GetView("designdoc", "viewname");
    foreach(var item in view)
    {
    Console.WriteLine(item.ItemId);
    }
  

• Couchbase.dll is now compiled against the.NET Framework 4.0