（翻译）Couchbase-sdk-net 使用手册 1.2 -Chapter 1. 启程

Chapter 1. 启程

1.1. 取得服务端程序

下载并安装Couchbase 服务端，安装完回到这里然后继续。

1.2. 取得客户端类库

两个途径都可以：

1、直接下载类库

2、通过执行NuGet Package Manger命令：

PM> Install-Package CouchbaseNetClient

1.3. 试用

1.3.1 建立项目

通过visual studio 新建一个控制台程序，并且添加Couchbase.dll, Enyim.Memcached.dll,

Newtonsoft.Json.dll and RestSharp.dll这几个程序集的引用（这几个动态链接库可在下载的类库包中找到）

1.3.2 添加配置

你可以使用编程方式或者使用couchbase 配置节在app.config文件中配置。使用app.config文件更新灵活，是优先采用的方法。

按照下面配置你的app.config:

<?xml version="1.0"?>

</configSections>

</servers>

</couchbase>

</configuration>

上面在Servers列表中的多个URI，是客户端获取信息的集群配置。如果在本机上运行，则只需要设置一个127.0.0.1的配置就可以了。

默认的Couchbase 服务端安装是创建一个名为default、没有密码的存储区（bucket），所以这里存储区密码（bucketpassword）的属性为可选。如果你创建了一个已认证的存储区，你必须在上面的设置中配置那个值。

警告：

在Windows系统默认分配了一些TCP/IP端口用于系统通信用。关于这个问题的更多信息，包括怎么去调整配置和增加可用的端口可以看Avoiding TCP/IP Port Exhaustion。

1.3.3 客户端举例

在Program.cs文件中添加下面的声明：

using Couchbase;

using Enyim.Caching.Memcached;

using Newtonsoft.Json;

Couchbase命名空间中包含我们将会用到的客户端和配置类。

Enyim.Caching.Memcached包含基础设施的支持，记得Couchbase支持Memcached协议，因此可以使用流行的Enyim Memcached客户端的key/Value操作方式。

下一步在Main方法中创建一个客户端实例。

var client = new CouchbaseClient();

在这个练习中，这是一个不好的创建客户端的方式。这个客户端会引发创建连接池，并且建立一个线程去取得集群配置。因此，最好的方式是每个应用程序域和每个存储区（bucket）只创建一个客户端实例。为了这个目的，可以在一个类里面创建一个静态属性。

public class CouchbaseManager

{

private readonly static CouchbaseClient _instance;

static CouchbaseManager()

{

_instance = new CouchbaseClient();

}

public static CouchbaseClient Instance { get { return _instance; } }

}

1.3.4 CRUD操作

在.Net 客户端，主要的CRUP API是使用标准的Key/Value存储方式。你创建或者更新文本需要提供一个key和value。检索和移除文本需要根据提供的key进行。举个例子：

如果安装Couchbase Server和设置集群的时候把一个名为“beer-sample”存储区选中的话，可以在这个存储区中找到一个文本的key为“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 "style": "American-Style Amber/Red Ale",

"category": "North American Ale"

}

可以简单的调用get方法，就能得到这个文本的内容。

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

如果添加一行代码打印savedBeer到控制台，可以看到里面包含了一个json格式的字符串：

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

Console.WriteLine(savedBeer);

在这个例子里savedBeer 是一个Object类型，如果想得到一个string类型的对象，可以使用泛型版本的get

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

为了演示添加文本，首先创建一个Json字符串。

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""

}";

这里简单的创建一个key，key的名字使用啤酒厂的名字和啤酒的名字使用破折号连接而成，空白替换成下换线，文字全部小写。这里要强调的一点，key的产生规则是必须始终不变的。如果你通过key去检索数据，你必须能预测到使用哪个key。

如var key = "cottrell_brewing-old_yankee_ale";

通过这个新的key，json文本可以简单的保存。

var result = client.Store(StoreMode.Add, key, newBeer);

这里使用了三个参数去保存。第一个参数是保存的模式，是一个枚举，Add表示添加一个新的key，Replace表示更新一个已经存在的key，set表示如果key不存在则添加、存在则更新。如果key已经存在add就会失败，如果key不存在Replace操作会失败。第二和第三个参数分别是key和value。

返回值是一个bool类型，表示操作是成功还是失败。

删除操作使用key去调用Remove方法，类似其他方法，Remove返回一个bool类型的返回值，表示操作是否成功。

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

1.3.5. 存储为Json文本

存储为Json格式的字符串是一个比较简单直接的操作，但是实际上我们很多时候会有存储领域对象的需求，更明白的讲我们会有很多直接存储数据的对象的需求。这个.Net 客户端类库支持存储可序列化的对象。当然这些可序列话的对象会作为Joson文本的二进制附件保存。它的影响是附件在查看的时候是没有索引的。更好的解决方案是在保存前，先把数据序列化成Json字符串；取出数据后，再反序列话Json字符串成对象。

1.3.6. CouchbaseClient JSON 扩展方法

如果想简单的读写JSON, 在Couchbase.Extensions命名空间下 CouchbaseClientExtensions类提供了两个方法, StoreJson 和 GetJson。这两个方法都是依赖于开源类库： Newtonsoft.Json library, （已经在Couchbase .NET类库的压缩包里面）。这两个只是简单的对get和store方法的重写，当前不支持复杂的CAS和TTL操作。

这里创建POCO类Beer，需要添加声明

using Newtonsoft.Json;

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; }

}

使用new 一个实例：

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

检索：

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

在Program里面可以如下：

class Program

{

static void Main(string[] args)

{