MongoDB C# Driver 快速入门指南

这是MongoDB driver的第一部分。在这一部分，你可以看到如何去执行一些数据库的基本CRUD（C-创建，R-读取，U-更新，D-删除）操作。

# 连接

以下展示了三种连接到MongoDB远程服务器和本地服务器的方式 :

// 连接到单实例MongoDB服务
// 这种连接方式不会自动检测连接的节点是主节点还是复制集的成员节点
var client = new MongoClient();

// 或者使用string连接本地服务器,localhost=127.0.0.1,连接到单实例
var client = new MongoClient("mongodb://localhost:27017");

// 连接到复制集（多节点）
var client = new MongoClient("mongodb://localhost:27017,localhost:27018,localhost:27019");

客户端实例现在可以拥有连接到连接字符串中指定的服务器或服务器的连接池。

# MongoClient

MongoClient 实例实际上表示一个连接数据库的连接池；

你仅仅只需要一个MongoClient 类实例，即使在多线程情况下；

标注：实际上，你只需要为给定的集群创建一个MongoClient实例，并在应用程序中使用它。但是，如果连接字符串是相同的，那么创建多个MongoClient将仍然共享相同的连接池。

# Get a Database

获取一个数据库实例，列举数据库的名称可以通过client中的GetDatabase方法，在数据库存在的情况下，该方式都是可行的。它将在首次被调用时创建。

var database = client.GetDatabase("foo");

现在，database变量保存了对数据库“foo”的引用.

# Get a Collection

获取一个集合实例，列举集合的名称可以通过database中GetCollection<TDocument>.在集合存在的情况下，它将在首次被调用时创建。

var collection = database.GetCollection<BsonDocument>("bar");

现在，collection变量保存了对数据库“foo”下“bar”集合的引用.

标注：泛型参数TDocument表示集合中存在的模式，使用一个BsonDocument来表示没有预定的模式。

# Insert a Document

一旦你拥有了collection实例，你就可以插入一个文档到集合中。例如，考虑下面的JSON文档，它是一个包含了一个字段信息的嵌入式文档。

{
     "name": "MongoDB",
     "type": "database",
     "count": 1,
     "info": {
         x: 203,
         y: 102
     }
}

你可以使用.NET driver中的BsonDocument类创建这个文档，方式如下：

var document = new BsonDocument
{
    { "name", "MongoDB" },
    { "type", "Database" },
    { "count", 1 },
    { "info", new BsonDocument
        {
            { "x", 203 },
            { "y", 102 }
        }
    }
};

把这个文档插入到集合中，可以是使用InsertOne或者InsertOneAsync方法

collection.InsertOne(document);//同步
await collection.InsertOneAsycn(document);//异步

标注：
.NET driver 当前已全部支持异步操作。关于更多的async和await的信息，参见MSDN documentation
https://msdn.microsoft.com/en-us/library/hh191443.aspx
驱动中所有的API都已经同时支持同步和异步.

# Insert Multiple Documents

插入多条数据到数据库，可以使用InsertMany或者InsertManyAsync两种方式.

// 生成 100 个counter从0~99递增的文档
var documents = Enumerable.Range(0, 100).Select(i => new BsonDocument("counter", i));

插入数据

collection.InsertManh(documnets);
await collection.InsertManyAsycn(documents);

# Counting Documents

现在，我们插入了101个文档到数据库里面（100在循环中，首次插入1）,我们可以核查这些数据，如果我们使用Count或者CountAsycn方法. 下面的代码应该可以使得count的值为101.

var count = collection.Count(new BsonDocument());
or
var count = await collection.CountAsync(new BsonDocument());

标注：空的BsonDocument参数是一个过滤器。在这里，指的是要计算所有的文档.

# Query the Collection

使用Find方法去集合中查询. 该方法会返回一个IFindFluent<TDocument, TProjection> 实例，它提供一个接口链接find操作设置.

# Find the First Document in a Collection

调用FirstOrDefault 或者FirstOrDefaultAsync 方法，可以获取集合的第一个文档.FirstOrDefault返回第一个文档或者null. 当你只需要一个匹配的文档或只对第一个文档感兴趣时，该方法非常有用.

下面的例子将会打印出再集合中查询出来的第一个文档：

var document = collection.Find(new BsonDocument()).FirstOrDefault();
Consloe.WriteLine(document.ToString());

var document = await collection.Find(new BsonDocument()).FirstOrDefaultAsync();
Console.WriteLine(document.ToString());

该例子将会打印出以下内容:

{ 
    "_id": ObjectId("5940f2b98198abd6a5eea7b1") },
    "name": "MongoDB", 
    "type": "database", 
    "count": 1,
    "info": { "x" : 203, "y" : 102 } 
}

元素 “id” 为 MongoDB 数据库自动添加到文档中，这是打印出来的内容与插入的内容不一致的原因。MongoDB数据库内部保留所有以 “_” 和 “$” 开头的字段名称.

# Find All Documents in a Collection

使用ToList或者ToListAsycn方法可以检索到集合中的所有文档，当需要返回的文档比较少量时，该方法非常有用.

var documents = collection.Find(new BsonDocument()).ToList();

var documents = await collection.Find(new BsonDocument()).ToListAsync();

如果返回的文档数量比预期的大，可以使用通过迭代的方式进行处理。ForEachAsync将会为每个返回的文档调用一个回调。

await collection.Find(new BsonDocument()).ForEachAsync(d => Console.WriteLined(d));

如果使用的是同步的API，则要使用C#中的ToEnumerable抽象方法去迭代每个文档：

var cursor = collection.Find(new BsonDocument()).ToCursor();
foreach (var document in cursor.ToEnumerable())
{
    Console.WriteLine(document);   
}

上面的例子将会打印出相同的信息。更多的信息参见reference documention

# Get a Single Document With a Filter

在一个集合中，我们可以创建一个筛选器传递给Find方法去获取一个文档的子集。例如，如果我们想查找“i”字段的值为71的文档，我们可以使用如下的方式:

var filter = Builders<BsonDocument>.Filter.Eq("i", 71);

var document = collection.Find(filter).First();
Console.WriteLine(document);

var document = await collection.Find(filter).FirstAsync();
Console.WriteLine(document);

以上应该仅打印出一个文档:

{ "_id" : ObjectId("5515836e58c7b4fbc756320b"), "i" : 71 }

标注：

使用 Filter，Sort 和 Projection 以简单和简洁的方式创建一个查询.

# Get a Set of Documents With a Filter

我们也可以从集合中获取一组文档。例如，如果我们获取所有符合 i > 50 条件的文档，可以使用如下的方式:

var filter = Builders<BsonDocument>.Filter.Gt("i", 50);// Gt表示大于

var cursor = collection.Find(filter).ToCursor();
foreach (var document in cursor.ToEnumerable())
{
    Console.WriteLine(document);   
}

await collection.Find(filter).ForEachAsync(document => Console.WriteLine(document));

还可以限定一个范围查询，例如 50 < i <= 100;

var filterBuilder = Builders<BsonDocument>.Filter;
var filter = filterBuilder.Gt("i", 50) & filterBuilder.Lte("i", 100);//Lt表示小于，Lte表示小于等于

var cursor = collection.Find(filter).ToCursor();
foreach (var document in cursor.ToEnumerable())
{
    Console.WriteLine(document);   
}

await collection.Find(filter).ForEachAsync(document => Console.WriteLine(document));

# Sorting Documents

我们可以通过调用 Sort 方法来创建一个排序匹配查询。在现有的 filter 构造方法下，我们可以使用 Descending 建立一个降序构造器来排序我们的文档：

var filter = Builders<BsonDocument>.Filter.Exists("i");
var sort = Builders<BsonDocument>.Sort.Descending("i");

var document = collection.Find(filter).Sort(sort).First();

var document = await collection.Find(filter).Sort(sort).FirstAsync();

# Projecting Fields（映射字段）

很多时候，我们不需要文档中包含的所有字段，Projection 构造器可以在一个查询操作中构造映射字段。下面的例子中，我们排除了“_id”字段，并且输出第一个匹配的文档：

var projection = Builders<BsonDocument>.Projection.Exclude("_id");

var document = collection.Find(new BsonDocument()).Project(projection).First();
Console.WriteLine(document.ToString());

var document = await collection.Find(new BsonDocument()).Project(projection).FirstAsync();
Console.WriteLine(document.ToString());

# Updating Documents

MongoDB 支持多种更新操作方式

更新最多一个文档（如果没有匹配筛选器，可能为零个文档），使用UpdateOne或者UpdateOneAsync去指定筛选器并更新匹配的文档。下面，我们更新筛选器为 i == 10 匹配的第一个文档，并将该文档 i 的值更新为110:

var filter = Builders<BsonDocument>.Filter.Eq("i", 10);
var update = Builders<BsonDocument>.Update.Set("i", 110);

collection.UpdateOne(filter, update);

await collection.UpdateOneAsync(filter, update);

更新筛选器匹配的所有文档，使用UpdateMany或者UpdateManyAsync方法。下面例子，将把所有 i < 100 匹配的文档中 i 的值增加 100。

var filter = Builders<BsonDocument>.Filter.Lt("i", 100);
var update = Builders<BsonDocument>.Update.Inc("i", 100);// Inc操作符表示：给i字段增加某个大小的值

var result = collection.UpdateOne(filter, update);

if (result.IsModifiedCountAvailable)
{
    Console.WriteLine(result.ModifiedCount);
}

var result = await collection.UpdateOneAsync(filter, update);

if (result.IsModifiedCountAvailable)
{
    Console.WriteLine(result.ModifiedCount);
}

更新方法返回的结果为UpdateResult，它提供关于该操作的信息，包括更新后修改的文档的数量。

标注:

根据MongoDB数据库的版本，某些特性可能无法使用。在这些情况下，我们已经尝试了检查是否有能力检查它们的可用性。

# Deleting Documents

删除最多一个文档（如果没有匹配筛选器，可能为零个文档），使用 DeleteOne 或者 DeleteOneAsync方法：

var filter = Builders<BsonDocument>.Filter.Eq("i", 110));

collection.DeleteOne(filter);

await collection.DeleteOneAsync(filter);

删除筛选器匹配的所有文档，使用DeleteMany 或者 DeleteManyAsync 方法。下面是删除所有 i >= 100 匹配的文档：

var filter = Builders<BsonDocument>.Filter.Gte("i", 100));// Gte表示大于等于

var result = collection.DeleteMany(filter);

Console.WriteLine(result.DeletedCount);

var result = await collection.DeleteManyAsync(filter);

Console.WriteLine(result.DeletedCount);

删除方法返回的结果为DeleteResult ，它提供关于该操作的信息，包括删除的文档数量。

# Bulk Writes （批量操作）

Bulk 操作有两种类型：

有序Bulk操作

以有序的方式执行所有的操作，并且在首次遇到异常时抛出异常。

无序Bulk操作

执行所有的操作，并记录操作过程中的全部异常。无序的批量操作不能保证执行的顺序。

让我们看一看下面的两个关于有序和无序的操作例子：

var models = new WriteModel<BsonDocument>[] 
{
    new InsertOneModel<BsonDocument>(new BsonDocument("_id", 4)),
    new InsertOneModel<BsonDocument>(new BsonDocument("_id", 5)),
    new InsertOneModel<BsonDocument>(new BsonDocument("_id", 6)),
    new UpdateOneModel<BsonDocument>(
        new BsonDocument("_id", 1), 
        new BsonDocument("$set", new BsonDocument("x", 2))),
    new DeleteOneModel<BsonDocument>(new BsonDocument("_id", 3)),
    new ReplaceOneModel<BsonDocument>(
        new BsonDocument("_id", 3), 
        new BsonDocument("_id", 3).Add("x", 4))
};

// 1. 有序的批量操作 - 保证操作的顺序
collection.BulkWrite(models);

// 2. 无序的批量操作 - 无法保证操作的顺序
collection.BulkWrite(models, new BulkWriteOptions { IsOrdered = false });

异步

// 1. 有序的批量操作 - 保证操作的顺序
await collection.BulkWriteAsync(models);

// 2. 无序的批量操作 - 无法保证操作的顺序
await collection.BulkWriteAsync(models, new BulkWriteOptions { IsOrdered = false });

重要:

批量操作功能在MongoDB数据库版本为2.6及之前的版本不被推荐使用，在性能上有较大的影响。

← Dapper框架 NLog教程 →