MongoDB的C＃驱动程序教程（译） 转

1.概述

本教程是10gen支持C＃驱动程序MongoDB的介绍。假定您熟悉使用MongoDB，因此主要集中在如何使用C＃访问MongoDB的。 它分为两个部分：C＃ 驱动程序 ，BSON图书馆。C＃驱动程序是建立在顶部，其目的是单独使用的C＃驱动程序的的BSON图书馆，。

在第1部分中，我们将介绍C＃驱动程序的主类：MongoServer，MongoDatabase，MongoCollection，MongoCursor，MongoGridFS，MongoGridFSFileInfo和SafeMode。

在第2部分，我们将讨论的主要类的BSON Library的：BsonType，BsonValue（及其子类），BsonElement，BsonDocument和BsonArray。

第1部分：C＃驱动程序

本教程的第1部分组织自顶向下的方式，所以你有时可能提前偷看，如果事情是没有意义。您甚至可能想要读第2，如果你是完全陌生的的BSON概念，如文档和元素与前第1部分。

参考文献和命名空间

为了从你的程序中使用C＃的驱动程序，您必须添加以下两个DLL文件：

• MongoDB.BsonLibrary.dll
• MongoDB.CSharpDriver.dll

您还应该添加以下语句到你的源文件：

using MongoDB.BsonLibrary;

using MongoDB.CSharpDriver;

除了 极少数例外，你将要使用的类的名称前缀与任何“BSON”的，如果他们的BsonLibrary或“Mongo”的一部分，如果他们的C＃驱动程序的一部分 。这样做是为了获得名称冲突的可能性降至最低，当您添加到你的程序的两个使用语句。预计将方法的参数（主要是枚举和标志）的一些类，具有较短的名称，不使用任何前缀。

我们喜欢使用C＃的var语句声明 的变量，因为它会导致更短，我们的感觉，更可读的代码。Visual Studio可以很容易地看到一个变量的类型 ，如果您需要通过将鼠标指针悬停在变量 或使用IntelliSense。然而，当阅读本文档，你没有这个能力，所以在这个文件中，而不是写：

var server = MongoServer.Create(connectionString);

var test = server[“test”];

var books = test[“books”];

按照我们的建议，我们会来写：

MongoServer server = MongoServer.Create(connectionString);

MongoDatabase test = server[“test”];

MongoCollection<BsonDocument> books = test[“books”];

所以，你可以看到什么类型正在使用。

线程安全

只有少数的C＃驱动程序 类是线程安全的。其中：MongoServer的，MongoDatabase，MongoCollection MongoGridFS。通用类，你会使用很多是不是线程安全包括MongoCursor的所有类的BsonLibrary（除BsonSymbolTable）的。A类不是线程安全的，除非特别记载是线程安全的。

所有的所有类的静态属性和方法是线程安全的。

MongoServer类

这个类服务 s的工作与MongoDB的根对象。这个类的一个实例的客户端是一个MongoDB服务器，你想沟通。虽然这个类有公共的构造函数，推荐的方式来获得这个类的一个实例是使用工厂方法。

每个实例MongoServer保持与服务器的连接池。这些连接之间共享所有的呼叫到服务器。你可能要调用构造函数，而不是直接调用创建工厂方法MongoServer的几个原因之一是，如果你要保持一个单独的连接池的一些操作。

这个类的实例是线程安全的。

连接字符串

最简单的方法是使用一个连接字符串连接到MongoDB的。标准 MongoDB的连接字符串的格式是一个以下列格式的URL：

mongodb://[username:password@]hostname[:port][/database]

如果您使用的是MongoDB服务器的身份验证的用户名和密码，只应。这些凭据将适用于一个单一的数据库，如果数据库名称是存在的，否则他们将所有的数据库的默认凭据。要进行身份验证对管理数据库追加“（管理）”的用户名的。

端口号是可选的，默认为27017。

如果数据库名是存在的，那么这个连接字符串，也可以与创建方法MongoDatabase的使用。创建方法MongoServer忽略的数据库名称（如果存在）（以外的凭据，以确定是否适用于一个单一的数据库或所有数据库的默认凭据）。

要连接到一个副本设置指定的种子提供多个以逗号分隔的主机名列表。例如:

mongodb://server1,server2:27017,server2:27018

该连接字符串指定的种子名单，由三个服务器（其中两个是在同一台机器上，但在不同的端口号）。

C＃驱动程序 能够连接到副本集，即使种子名单是不完整的。它会发现在主服务器即使主只要不是种子列表中的种子列表上的至少一个次级服务器响应（响应将包含完整副本集和当前的主的名称）。

工厂方法

最好的方式得到的一个实例MongoServer是，使用CREATE工厂方法。使用相同的连接字符串时，此方法将返回相同的实例MongoServer，所以你不必担心一大堆的情况下，如果你调用Create不止一次。此外，如果你只使用一个数据库时，你可能会发现它更容易跳过调用此方法，并呼吁建立 工厂方法MongoDatabase。

要连接到MongoDB的本地，你会写这样的代码：

string connectionString = “mongodb://localhost”;

MongoServer server = MongoServer.Create(connectionString);

或许......

MongoServer server = MongoServer.Create();

因为连接到本地主机是默认的。

中的Create方法MongoServer忽略了数据库名称，如果存在的话。但是，如果省略数据库名称，但存在凭据，然后MongoServer将承担这些凭据要使用的所有数据库，将它们存储在MongoServer的Credentials属性，并利用它们时GetDatabase被称为无凭据的默认凭据。这使得它真正易于使用相同的凭证与所有的数据库。

Create方法使用的种子列表中的服务器的身份时，如果已经有一个现有的实例MongoServer返回（而不是实际的副本集的成员，直到建立连接后，不知道是受改变）。

安全模式属性

此属性表示此服务器的默认安全模式。返回此服务器实例的MongoDatabase任何情况下，它会被继承，但可以改变indepently服务器的数据库的默认安全模式。安全模式类有进一步的描述。

GetDatabase方法

，从一个实例MongoServer你可以代表该服务器上的数据库使用GetDatabase方法的对象的实例。要得到一个数据库对象，你可以这样写：

MongoDatabase test = server.GetDatabase（“”）;

或

MongoDatabase test = server[“test”];

这两种形式是完全等效的。如果您使用的认证，就必须写略有不同的代码，如：

MongoCredentials credentials =

new MongoCredentials(“username”, “password”);

MongoDatabase test = server.GetDatabase(“test”, credentials);

或

MongoDatabase test = server[“test”, credentials];

MongoServer维护一个表的MongoDatabase实例的数据库/凭据组合，并每次你问相同的数据库/凭据组合，你得到相同的实例MongoDatabase，所以你无需担心不必要的重复的实例存在。

MongoDatabase类

这个类表示一个MongoDB服务器上的数据库。除非你正在使用的身份验证，你通常有 您要为每个数据库这一类 只有 一个实例。如果您正在使用的身份验证，那么 ， 你 最终会为每个数据库/凭据的组合，你要使用这个类的一个实例。

这个类的实例是线程安全的。

但是，如果你正在编写一个多线程程序，并做了一系列的相关操作（这是很常见的！），你可能希望使用的RequestStart，/ RequestDone，以确保一个线程的相关操作都发生在同一连接上的服务器。

工厂方法

通常情况下你的服务器实例上调用GetDatabase获得的MongoDatabase的实例，但 MongoDatabase也有创建工厂方法，这需要一个URL作为一个参数。但在这种情况下，数据库的名称是 必需的，将抛出一个异常，如果它缺少的URL。如果你选择到使用的创建工厂方法在MongoDatabase你做不有来电的创建工厂方法在MongoServer（虽然它会被称为为您和的导致服务器对象是提供给您，如果需要的新的数据库实例的服务器属性） 。

使用创建工厂方法，你能写的MongoDatabase要创建一个实例：

string connectionString = “mongodb://localhost/test”;

MongoDatabase test = MongoDatabase.Create(connectionString);

MongoServer server = test.Server; // 如果需要的话

请注意，这是完全等价于下面的代码：

string connectionString = “mongodb://localhost/test”;

MongoServer server = MongoServer.Create(connectionString);

MongoDatabase test = server.GetDatabase（“”）;

第一种形式是有利的，如果你不直接访问服务器对象，也因为来自URL的数据库名称（如果存在的凭据），并没有硬编码。

服务器属性

这个属性允许你导航回从MongoDatabase对象，的MongoServer对象，它属于。

Credentials属性

这个属性允许你检查这个的MongoDatabase实例关联的凭据。你不能改变的凭据。如果你想用不同的凭据，你必须回到服务器对象并得到一个新的数据库对象的新的 凭证。这通常是由许多部分的 代码 共享因为MongoDatabase的一个实例 ，并更改凭证，可能会产生意想不到的副作用。

安全模式属性

此属性表示该数据库的默认安全模式。返回该数据库实例的MongoCollection任何情况下，它会被继承，但可以改变一个集合的默认安全模式indepently数据库的。安全模式类有进一步的描述。

GridFS property

此属性使您可以访问这个数据库关联的的GridFS对象的。请参阅下面的MongoGridFS类的描述。MongoGridFS类的方法，如上传，下载，查找，让您的GridFS文件系统进行交互。

GetCollection方法

，从一个实例MongoDatabase你可以得到代表在该数据库使用GetCollection方法的集合对象的实例。为了得到一个集合对象，你可以这样写：

MongoCollection<BsonDocument> books =

database.GetCollection(“books”);

或

MongoCollection<BsonDocument> books = database[“books”];

这两种形式是完全等效的。

MongoDatabase维护一个表，至今已经使用的集合，每一次你问的同一个集合中，你得到相同的实例，所以你就不需要担心不必要的重复的实例存在。

GetCollection <TDefaultDocument>方法

在MongoDB中集合的特点之一是，他们是无架构。然而，它也是不寻常的一个集合 主要 持有 一种类型 的文件。我们称此为默认文档类型。通常情况下，默认的文件类型是BsonDocument，但你可以指定一个不同的默认文件类型的集合通过使用GetCollection <TDefaultDocument> 方法。例如:

MongoCollection<Employee> employees =

Database.GetCollection<Employee>(“employees”);

有没有索引等效的，因为C＃不允许的类型参数索引。

即使一个集合有一个默认的文件类型，你可以随时查询任何其他类型的文件，使用查找<TQuery, TDocument>方法，而不是查找<TQuery>（查找的<TQuery>仅仅是一个方便的快捷键<TQuery的， TDefaultDocument>）。

C＃驱动程序的最初版本只支持与文件类型BsonDocument的（因为BSON序列化/反序列化的支持尚未实现，对于其他类型）。

DropCollection方法

此方法可以用于从数据库中删除一个集合。MongoCollection也有一个方法叫做removeall过下降的数据，但在叶集（及任何索引）。要使用此方法写：

BsonDocument result = database.DropCollection(“books”);

DropCollection实际上是一个数据库命令的包装。所有的方法来包装一个命令返回命令的结果，这在某些情况下，可能有您感兴趣的信息。

RequestStart方法/ RequestDone方法

它经常发生，一个线程执行一系列数据库操作 有关重新 。更重要的是，线程 有时确实是依赖于早期写的读入。如果读出的发生比写要完成的一个不同的连接有时结果将尚未提供。一个线程可以表明它已被使用RequestStart一个 第二，它是一系列相关的操作由Cal 灵RequestDone 做了一系列的相关操作 。例如:

database.RequestStart（）;

/ /数据库的操作做了一系列的

database.RequestDone（）;

这个例子其实是有一个小问题：如果抛出一个异常，而这样做 对数据库的操作RequestDone永远不会被调用。要预防，你可以把到RequestDone在一个最后的块，或更容易的调用，利用，RequestStart返回一个帮手对象实现IDisposable的实例 ， 并使用了C＃使用陈述保证，RequestDone被称为自动。在这种情况下，你这样写：

using (database.RequestStart（））{

/ /数据库的操作做了一系列的

}

请注意，在这种情况下，你不叫RequestDone自己，这种情况发生时，会自动离开using语句的范围。

RequestStart的增量一计数器和RequestDone的的减少，所以你可以嵌套调用到RequestStart和RequestDone的要求实际上是不开 ，直到 再次达到零。这有助于当你执行方法，需要调用RequestStart / RequestDone的 ， 但 称为的代码本身RequestStart的在转。 这方面的一个例子是上载的方法在MongoGridFS，这要求RequestStart / RequestDone的。由于RequestStart筑巢产卵的行为是完全没有上传代码，已经本身称为RequestStart的调用。

MongoCollection <TDefaultDocument>类

在MongoDB数据库中， 这个类的实例 参阅下文的集合。你会得到一个的MongoCollection实例通过调用 GetCollection或GetCollection <TDefaultDocument>的方法MongoDatabase。 的类型参数TDefaultDocument的 是这个集合中的默认文档类型（如果你不指定，否则这将是BsonDocument）。

这个类的实例是线程安全的。

数据库属性

这个属性允许你导航回从MongoCollection对象，的MongoDatabase对象，它属于。

安全模式属性

此属性表示该集合中的默认安全模式。这将是对这个集合进行操作的默认安全模式，但已有许多方法提供了一种方法来覆盖安全模式只是一个操作。安全模式类有进一步的描述。

插入<TDocument>方法

之前，我们可以从集合中获取任何信息，我们需要把它放在那里。Insert方法的一种方式插入到一个集合中的文件（也可以查看保存的方法和UPSERT版本的Update方法）。例如:

BsonDocument book = new BsonDocument {

{ “author”, “Ernest Hemingway” },

{ “title”, “For Whom the Bell Tolls” }

};

books.Insert(book);

INSERT语句也可以写成：

books.Insert<BsonDocument>(book);

但是这是没有必要的，因为编译器可以推断 从参数 类型 TDocument的。需要注意的是TDocument 必须是一个类型，可以被序列化到一个BSON文档。C＃驱动程序 的最初版本 只知道如何序列化的BsonDocument类的实例。

当你要插入一个以上的文件，使用InsertBatch方法 。例如:

BsonDocument[] batch = {

new BsonDocument {

{ “author”, “Kurt Vonnegut” },

{ “title”, “Cat’s Cradle” }

}

new BsonDocument {

{ “author”, “Kurt Vonnegut” },

{ “title”, “Slaughterhouse-Five” }

}

};

books.InsertBatch(batch);

在一次插入多个文件的优点是，它最大限度地减少了网络传输。被插入的所有文件被发送到服务器在一个消息中（除非序列化的文件的总大小超过16MB，在这种情况下，它们将被在多个消息发送各保持为尽可能多的文件）。

<TQuery>方法

最常见的操作，您将执行对集合进行查询。这样做的find方法的几个变化。在本教程中，我们只显示简单的表格S， 但也有其他形式，让您使用JavaScript where子句而不是一个查询对象和/或指定要返回的字段。

下面是一些示例代码来读取的文件，我们刚刚插入的藏书：

BsonDocument query = new BsonDocument {

{ “author”, “Kurt Vonnegut” }

};

MongoCursor<BsonDocument> cursor = books.Find(query);

foreach (BsonDocument book in cursor) {

ConsoleWriteLine。

“{0} {1}”，

book[“title”].AsString，

book[“author”].AsString

）;

}

如果该文件被退回是不是默认的文件类型，然后使用一个版本的查找，可以让你指定的文件类型：

MongoCursor<Employee> cursor =

employees.Find<BsonDocument, Employee>(query);

有很多形式的查询对象的支持，但他们不是具体 到C＃驱动程序 ，我们没有足够的空间来形容他们。一个空的查询对象检索的所有文件， 相当于一个空的查询对象 的 C＃驱动程序允许空。

还有很多说关于MongoCursor，但有一整节以下使用游标在那里寻找更多详细信息。

FindAll方法

这种方法仅仅是一个快捷方式FindAll扩展<TDefaultDocument> 和检索的所有文件的集合。例如:

MongoCursor<BsonDocument> cursor = books.FindAll();

foreach (BsonDocument book in cursor) {

Console.WriteLine(

“{0} {1}”，

book[“title”].AsString，

book[“author”].AsString

）;

}

要查询一个文件，是不是默认的文件类型使用FindAll扩展<TDocument>。

FindOne <TQuery>方法

如果你知道有只有一个匹配的文件或如果你只是想第一个匹配的文件，你可以使用FindOne方法。例如:

BsonDocument query = new BsonDocument {

{ “author”, “Kurt Vonnegut” }

};

BsonDocument book = books.FindOne(query);

FindOne返回它找到第一个匹配的文件或C＃NULL，如果 是没有的。如果进一步 e是一个以上的匹配文档，它没有指定哪一个将被退回。

FindOne <TQuery>实际上是一个快捷方式：

FindOne<TQuery, TDefaultDocument>(query);

这又是一个快捷方式：

Find<TQuery, TDefaultDocument>(query).Limit(1).FirstOrDefault();

瓦特 HICH是有用的，要知道，如果你认为可能有多个匹配的文件和要控制哪一个是返回。FirstOrDefault方法的MongoCursor下面 的例子 。

要查询一个文件，是不是默认的文档类型使用FindOne <TQuery,的TDocument>。

保存<TDocument>方法

保存方法是插入和更新的组合。检查提供的文件，如果该文件是缺乏一个“_id”的元素，它假定这是一个新的文档和调用上的插入。如果该文件有一个“_id”的元素，它假定这可能是现有的文件，并调用Update就可以了，但以防万一，所以该文件将被插入，如果它不存在，将UPSERT标志。例如，您可以纠正错误使用的一本书的标题：

BsonDocument query = new BsonDocument {

{ “author”, “Kurt Vonnegut” }

{ “title”, “Cats Craddle” }

};

BsonDocument book = books.FindOne(query);

if (book != null) {

book[“title”] = “Cat’s Cradle”;

books.Save(book);

}

需要注意的是，我们的FindOne检查返回值，以确认它实际上找到了一个匹配的文档。

更新<TQuery, TUpdate>方法

更新方法用于更新现有的文件（见 下面的 UPSERT标志 ）。的代码示例所示的保存方法也可以写为：

BsonDocument query = new BsonDocument {

{ “author”, “Kurt Vonnegut” }

{ “title”, “Cats Craddle” }

};

BsonDocument update = new BsonDocument {

{ “$set”, new BsonDocument(“title”, “Cat’s Cradle”) }

};

BsonDocument updatedBoook = books.Update(query, update);

Update方法支持许多不同种类的更新文件，但再次，我们没有足够的空间来形容他们在本教程中。使用上面的例子中的“$集” 更新修饰符更新匹配的文件的一个元素的值。

此外，还有一个过载的更新，使您可以指定一个或多个UpdateFlags。的值是和多UPSERT。 正常情况下，更新只影响一个文件，但使用UpdateFlags。多，你可以要求所有匹配的文件被更新。此外，指定UpdateFlags。UPSERT您可以要求的 更新文件被插入，如果无法找到符合条件的文件（注意，UPSERT功能需要更新文件是一个完整的文件，而不是在上面的示例中，只是一个更新操作）。

计算方法

有时候，你只需要知道一个集合有多少文件。 有两个版本的指望 。2-15 方法，首先计算所有的文件，和第二计数匹配的文件。例如:

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

int total = books..Count();

int booksByHemingway = books.Count(query);

删除方法

可以使用此方法，从集合中删除文件。例如，要删除所有收集海明威的书，我们写的：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

books.Remove(query);

如果我们只是想删除一本书 - 海明威，我们可以这样写：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

books.Remove(query, RemoveFlags.Single);

虽然我们没有控制过这本书完全去除，但是这将是一个由海明威。

RemoveAll方法

如果你想删除一个集合中的所有文件，请使用：

books.RemoveAll();

请谨慎使用！ RemoveAll只是一个快捷方式删除（空）。 也参看的DropCollection在MongoDatabase方法，这种方法虽然不同从 DropCollection中，只有数据被删除，而不是集合本身或任何索引。

的CreateIndex方法

此方法用于创建索引的集合。在其最简单的形式中，你只需要提供一个列表的元素名称被编入索引。还有更复杂的形式，使用一个 参数来指定要创建的索引的详细信息，但它们超出了本文的讨论范围。

要建立索引的藏书作者，我们可以这样写：

books.CreateIndex(“author”);

注意，MongoDB是宽容的，如果您尝试创建一个索引已经存在，但要减少次数的服务器被要求创建相同的索引方法，而不是使用EnsureIndex。

EnsureIndex方法

您通常会调用此方法，而不是的CreateIndex。驱动跟踪的索引， 它 创造 了 只调用一次，每个索引（索引是否存在于服务器上，所以它必须调用的CreateIndex至少一次，以确保指数存在的驱动程序不知道）的CreateIndex。就像调用的CreateIndex调用EnsureIndex是：

books.EnsureIndex(“author”);

EnsureIndex也不能判断索引是否已被删除，因为它是在服务器上创建。你可以，知道任何索引的EnsureIndex忘记通过调用ResetIndexCache。被称为接下来的时间EnsureIndex的，它会调用的CreateIndex再次后，该指数将再次在索引缓存和createindex将不会被调用了该指数。

不同的方法

此方法用于对于一个给定的密钥，找到所有的不同的值。例如，要查找所有作者的藏书中，你可以这样写：

IEnumerable<BsonValue> authors = books.Distinct(“author”);

foreach (string author in authors) {

Console.WriteLine(author.AsString）;

}

也有一个过载的不同的方法，该方法的查询，所以你可以找到不同的值，对于一个给定键的只是那些与查询匹配的文件。

FindAndModify方法

文本缺失。

Group method

文本缺失。

MapReduce的方法

文本缺失。

MongoCursor <TQuery, TDocument>类

找到方法（及其变化）不返回的实际结果的发现 。相反， 他们返回一个游标，可以列举出 检索结果的发现。该查询实际上并没有发送到服务器之前，我们 首先对试图枚举光标，这不仅意味着，查找方法不沟通与服务器（它们只返回一个游标）时，但我们可以控制的结果，通过改变光标之前列举的有用的方法。

在C＃中的 光标列举 了最便捷的方式 是使用foreach语句。但是，如果必要的话，你可以调用一个游标的的GetEnumerator方法和 工作直接用枚举。 您可以列举许多倍，你想一个光标。每次你调用GetEnumerator（通常是间接地通过foreach语句）一个新的查询发送到服务器。

一旦你列举游标被冻结，并没有进一步的变化可以向它提出的。

这个类的实例不是线程安全的。 然而，一旦光标被冻结，成为线程安全的枚举（请记住，每一次的GetEnumerator被称为一个单独的查询将被发送到服务器）。

集合属性

您可以使用此属性来定位光标集合查询。

修改光标之前执行的方法

在此类别的使用方法修改之前以某种方式被列举的光标控制游标返回的结果。请注意，所有这些方法都返回游标本身，让他们链接起来（“流利接口”）。

Skip方法

这种方法控制服务器应该跳过多少文件，然后返回结果。它往往是有用的分页，虽然是大值跳过知道，会变得非常低效的。例如，假设我们有很多由Isaac Asimov的书，想跳过第5：

BsonDocument query = new BsonDocument {

{ “author”, “Isaac Asimov” }

};

MongoCursor<BsonDocument> cursor = books.Find(query);

foreach (BsonDocument book in cursor.Skip(5)) {

Console.WriteLine(book[“title”].AsString）;

}

限制方法

限制的方法可以让我们控制游标返回多少个文件 。此例子是类似于前一个，并告诉光标 返回至多10匹配文档：

BsonDocument query = new BsonDocument {

{ “author”, “Isaac Asimov” }

};

MongoCursor<BsonDocument> cursor = books.Find(query);

foreach (BsonDocument book in cursor.Limit(10)) {

Console.WriteLine(book[“title”].AsString）;

}

强制执行该限制是客户端，它是可能的服务器可能返回比需要更多的文件，在这种情况下，额外的将被忽略 。枚举中的某些值的查询发送到服务器，告诉它有多少文件发回的消息，但这些有时被视为暗示的服务器。对于小的范围内，你可以用一个负价值，让服务器知道在一个消息中返回所有的结果（实际限制 客户端将是负数的绝对值）。

排序方法

通常情况下，我们希望在一个特定的顺序返回结果。排序方法，让我们来告诉 服务器 ， 什么样的顺序返回结果中。在其最简单的形式中，我们只需提供姓名的关键，我们要排序的结果，如：

MongoCursor<BsonDocument> cursor = books.FindAll();

foreach (BsonDocument book in cursor.Sort(“author”, “title”)) {

Console.WriteLine。

“{0}: {1}”,

book.[“author”].AsString,

book.[“title”].AsString

）;

}

其他重载的排序方法让你单独控制每个键的排列顺序。

其他光标修改方法

改性方法有更多的光标不会在这里描述，但他们的名字就建议他们使用AddOption，批次，字段，标志，提示，和快照。

触发列举的方法，

下面的方法所有触发列举的光标。这意味着，必须先完成，光标使用上面的方法修改，光标前的枚举，并成为冻结。

计算方法

如果你不需要个别的结果，但只是想知道的计数匹配的文档，你可以使用此方法。这种方法相当于调用计数的收集。请注意，这种方法忽略任何跳过“或”限价已经设置光标（但看到“大小”的方法）。

尺寸的方法

这种方法是类似的计数方法，但任何荣誉跳过或限制已设置的选项上的光标。

的GetEnumerator方法（或foreach语句）

这种方法可以用来枚举 的结果 返回一个IEnumerator <TDocument>的 。通常你不会调用此方法，而是使用C＃foreach语句来 枚举的结果。 请注意，实际与服务器的通信不会发生，直到 第一次的MoveNext方法被调用的枚举，但光标并成为冻结尽快的GetEnumerator被称为。

FirstOrDefault方法

有时，你只是想要或期望的一个结果，在这种情况下，您可以使用 此方法，这是更方便，比列举光标。在简单的情况下，你可能更喜欢，到使用FindOne方法MongoCollection的，但FirstOrDefault方法上的光标在检索一个文件，让你提供有趣的选项上的光标。例如，假设你想找到海明威出版的第一本书：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

MongoCursor<BsonDocument> cursor = books.Find(query);

cursor.Sort(“publicationDate”);

BsonDocument firstBook = cursor.FirstOrDefault();

因为游标的修改方法支持流畅的界面，你也可以链的召集中：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

BsonDocument firstBook = books.Find(query)

.Sort(“publicationDate”)

.FirstOrDefault();

FirstOrDefault实际上是一个IEnumerable的扩展方法，可以用一个MongoCursor，，因为MongoCursor <TQuery, TDocument>实现IEnumerable的<TDocument>的 。正因为如此，你可以使用任何IEnumerable的扩展方法与MongoCursor。

ToArray方法

这IEnumerable的扩展方法为您列举了光标，并返回一个数组的T.例如：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

BsonDocument[] books = books.Find(query).ToArray();

如果没有匹配的文档的返回值将是一个空数组，而不是C＃空。

ToList方法

这IEnumerable的扩展方法为你列举了光标，并返回 列表 <T>的。例如:

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

List<BsonDocument> books = books.Find(query).ToList（）;

如果没有匹配的文档的返回值将是一个空列表，而不是C＃空。

IEnumerable的扩展方法，触发枚举

由于MongoCursor <TQuery, TDocument>实现IEnumerable <TDocument> 所有的为IEnumerable <T>的定义的扩展方法可以与MongoCursor使用，以及他们的大部分触发光标的枚举的。以下是一些比较常见的方法的列表：

• First
• FirstOrDefault
• Last
• LastOrDefault
• Single
• SingleOrDefault
• ToArray
• Tolist

请记住，所有的扩展方法“看”的序列，当然列举的光标。另外要指出的是，一些IEnumerable的扩展方法具有相同的名称的方法 MongoCursor <TQuery, TDocument>，在这种情况下定义的方法，在MongoCursor <TQuery, TDocument>优先（除非你投您的光标移动到IEnumerable <TDocument>）。

安全消耗光标的

在列举上的光标触发一个连接从连接池获得，并不会被释放，直到它不再需要返回到连接池 。重要的 是 要确保枚举器得到一个机会释放连接，确保连接被返回到连接池 。实施的 一个MongoCursor的枚举释放连接，因为它可以（甚至可能的结果是在统计前完成）的连接丢失的可能性降至最低 。如果 枚举没有正确配置你的程序不会崩溃，但连接将不会被返回到连接池，将丢失（并且最终将被关闭，当它被垃圾回收），这将导致你的程序中打开连接数多于必要的。

如果MongoCursor枚举消耗了所有的连接释放回连接池（其实，你可以肯定的，它会被退回尽快答复查询，或能获得更多产品信息就没有额外的结果）。

确保连接被返回到连接池在所有情况下，关键是要保证Dispose方法调用的GetEnumerator返回的枚举。这是唯一真正的问题，如果你是消费手动枚举。所有的IEnumerable的扩展方法调用Dispose的枚举。C＃foreach语句也可以保证在调用Dispose的枚举，因此，如果你坚持 IEnumerable的扩展方法和foreach语句，你将被罚款。

说明方法

此方法是从任何其他光标 方法 不同 ，因为它实际上并不返回查询的结果。相反，服务器返回的信息如何查询将被执行。这些信息可以是有用时，试图弄清楚为什么一个查询效果不理想。要使用此方法，你可以这样写：

BsonDocument query = new BsonDocument {

{ “author”, “Ernest Hemingway” }

};

MongoCursor<BsonDocument> cursor = books.Find(query);

BsonDocument explanation = cursor.Explain();

MongoGridFS类

这个类是 C＃GridFS规范将文件存储在MongoDB数据库 驱动程序 实现的。使用GridFS财产MongoDatabase，你通常会得到这个类的一个实例。

这个类的实例是线程安全的。但是，如果你打算修改设置这种情况下，你应该做的，所以在多线程访问 的一个实例。

数据库属性

这个属性允许你来浏览，从实例MongoGridFS的数据库，它是与。

设置属性

此属性使您可以访问这种情况下的设置。您可以更改根目录名称GridFS集合（默认为“FS”）和DefaultChunkSize新的文件（默认为256KB）。需要注意的是缺省的块大小只适用于新的文件。不同的块尺寸与先前创建的任何文件将继续使用现有的块大小进行处理。这是不可能改变的块大小的文件，一旦它被创建。

上传方法

此方法上传的文件从客户端计算机的数据库。它总是GridFS文件系统中创建一个新的文件，所以，如果你上传的文件超过一次，将有多个版本的文件在数据库中。要使用此方法写：

MongoGridFS gridFS = database.GridFS;

MongoGridFSFileInfo的fileInfo = gridFS.Upload（“volcano.jpg”）;

上传的返回值是刚刚上传的文件的信息。如果你愿意，你可以忽略返回值。上传将抛出一个异常，如果它失败。

有其他重载上传，让您指定不同的本地和远程的文件名，或者从一个流，而不是从一个文件直接上传。

下载方式

此方法下载一个文件，从数据库到客户端计算机。如果该文件已存在用户端电脑上，它会被覆盖。要使用此方法写：

MongoGridFS gridFS = database.GridFS;

gridFS.Download（“volcano.jpg”）;

正如前面提到的，可能有多个版本的相同的文件名在数据库中。缺省情况下，下载下载最新的版本（如所定义的“uploadDate”的文件的元数据的元素）。你可以下载一个不同的版本，提供一个完整版本参数。一个版本号的值可以是：

1              The first version

2              The second version

n              The nth version

-1              The newest version

-2              The second newest version

-n              The nth newest version

0              Any version (not very useful unless there’s only one)

因此，例如，检索最新版本的文件，你可以这样写：

MongoGridFS gridFS = database.GridFS;

gridFS.Download（“volcano.jpg”，-2）; / /第二个版本

其他的下载方法的重载让你指定不同的本地和远程的文件名，或者直接下载到一个流，而不是一个文件。

查找方法

Find方法查询GridFS文件系统的有关文件的信息。如果有一个以上的文件匹配 ，然后 将返回所有的信息（即使在提供特定的文件名 相同的文件名 可能有多个匹配，如果已上载超过一次）。例如:

MongoGridFS gridFS = database.GridFS;

IEnumerable<MongoGridFSFileInfo> files =

gridFS.Find（“volcano.jpg”）;

如果没有相匹配的列表将是空的（不是C＃NULL）。

FindOne方法

如果您希望只有一个匹配的文件名或愿意指定一个版本号的话，那就更方便的使用FindOne方法。例如:

MongoGridFS gridFS = database.GridFS;

MongoGridFSFileInfo file = gridFS.FindOne(“volcano.jpg”);

或获得的第二个版本的文件信息：

MongoGridFS gridFS = database.GridFS;

MongoGridFSFileInfo file = gridFS.FindOne(“volcano.jpg”, 2);

在这两种情况下，如果没有匹配的文件C＃NULL被返回。

Exists方法

如果你只是想知道，如果该文件存在，但不需要任何的文件的元数据，你可以使用此方法。例如:

MongoGridFS gridFS = database.GridFS;

if (gridFS.Exists(“volcano.jpg”)) {

/ /现在你知道该文件是否存在

}

删除方法

该方法将删除从GridFS文件系统匹配的文件。如果有一个以上的文件匹配，他们都将被删除（见下面的示例中如何删除的文件只有一个版本）。例如:

MongoGridFS gridFS = database.GridFS;

gridFS.Delete（“volcano.jpg”）;

如果你只是想删除的最新版本写的东西一样：

MongoGridFS gridFS = database.GridFS;

MongoGridFSFileInfo的fileInfo = gridFS.FindOne（“volcano.jpg”，-2）;

if (fileInfo != null) {

gridFS.DeleteById（fileInfo.Id）; / /删除_id

}

MongoGridFSFileInfo class

这个类表示GridFS文件系统中存储的文件的信息。此类设计是类似的 。NET的FileInfo类的 POSS IBLE。

ChunkSize property

使用的块大小时，创建此文件。

GridFS property

您可以使用这个属性来导航从MongoGridFSFileInro实例的MongoGridFS它所属的对象。

Id property

此属性具有价值的“_id”元素这个文件。这个值是第一次上传文件时，分配，并保证是唯一的。 对于使用 C＃驱动程序 上载的文件， 这将是一个ObjectID，虽然有可能你会遇到不同的驱动器上载的文件的ID可能是不同类型的。

Length属性

以字节为单位的文件的总长度。

MD5 property

该文件的MD5哈希计算在服务器上，当它被上传。

Name属性

远程GridFS文件系统中的文件的文件名。

UploadDate财产

该文件已被上传时的日期时间。这的DateTime是始终在UTC。

即将实施的方法

这个类还实现方法，返回一个流对象（流的一个子类），使您可以读取和写入GridFS文件相同的方式，做本地文件（一个可能的替代使用上传/下载方法，虽然可能没有那么快 ）。这些方法都返回一个实例的MongoGridFSStream， 流的一个子类，支持读，写和S 伊克。，返回一个MongoGridFSStream的一个StreamWriter（或包裹着它的）的方法是：AppendText，创建，CreateText，打开，打开读取 ，OpenText，OpenWrite。

安全模式类

有好几次在本教程前面我们所提到的 安全模式。有各种级别的安全模式，并且这个类被用来 表示 这些级别。将SafeMode仅适用于不已经返回的值（因此，它并不适用于查询或命令）的操作。它适用于的方法MongoCollection：插入，删除，保存和更新。它也适用于到一个MongoGridFS的对象作为一个整体，使所有GridFS的操作都在相同的安全模式级别。

安全模式的要点是后插入，删除，保存或更新信息发送到服务器后面是一个GetLastError函数命令使C＃D 河可以确认操作成功。此外，当使用副本集，有SafeModes，让我们指定我们要等待多少次重复前完成GetLastError返回。进入安全模式 的值 的标准方法 是使用静态的类的属性和方法，如：

SafeMode.False

SafeMode.True

SafeMode.WaitForReplications(n);

的“n”的值包括伯，所以等待至少一个从已完成的复制，我们将使用“2”的值。

我们也提到安全模式是继承了从服务器到数据库收集和操作。这种继承的时刻发生在创建相应的对象，但可以修改indepently 其后。因此，例如，如果我们 想要安全模式是在普通（默认是出于性能原因），但我们有一个集合，我们希望它被关闭，我们可以这样写：

MongoServer server = MongoServer.Create(connectionString);

server.SafeMode = SafeMode.True; // default to SafeMode.True

MongoDatabase test = server[“test”]; // inherits SafeMode.True

MongoCollection log = test[“log”]; // inherits SafeMode.True

log.SafeMode = SafeMode.False; // turn off SafeMode for log

BsonDocument importantMessage = new BsonDocument {

/ /内容的重要信息

};

log.Insert(importantMessage, SafeMode.TRUE）; / /覆盖安全模式

代码的最后一行说明了安全模式，可以覆盖在个人的操作水平。

第2部分：BSON图书馆

本教程的其余部分是的BSON 图书馆。此库实现了序列化和反序列化BSON格式（我们将不包括）的数据中，还提供了一个BSON文档（我们将 ） 在内存中的表示 。的重要类BsonType，BsonValue（及其子类），BsonElement，BsonDocument和BsonArray。

第1部分，其中有一个自上而下的结构不同，我们将在第2部分的的BSON库底检查后，开始对元素，文件和阵列类型和值，和工作。

BsonType枚举

BSON中的每个值都有一个类型，这是一个BSON支持一组固定的类型。以下列举列出了所有BSON支持的数据类型：

public enum BsonType {

Double = 0x01,

String = 0x02,

Document = 0x03,

Array = 0x04,

Binary = 0x05,

ObjectId = 0x07,

Boolean = 0x08,

DateTime = 0x09,

Null = 0x0a,

RegularExpression = 0x0b,

JavaScript = 0x0d,

Symbol = 0x0e,

JavaScriptWithScope = 0x0f,

Int32 = 0x10,

Timestamp = 0x11,

Int64 = 0x12,

MinKey = 0xff,

MaxKey = 0x7f

}

我们将研究这些类型的更多细节，我们讨论BsonValues。

BsonValue类

这是一个抽象类，它代表一个类型的BSON值的概念。有一个子类BsonValue的每一个 值 在 BsonType枚举。BsonValue定义一些属性和方法是共同所有 BSON类型（或在某些情况下，将其转换从BsonValue到一些它的子类或。NET类型）。

，因为BsonValue是一个抽象类，不能构造这个类的实例，你只能构建其具体子类的实例。另一方面，你经常会看到这种类型的变量，参数和返回值。

创建BsonValues

有几种方法来创建实例BsonValues（所有）：

1.       使用静态创建方法BsonValue

2. 使用的一个的BsonValue子类的静态Create方法

3利用隐式转换。NET类型的BsonValue

4：的BsonValue子类调用公共的构造函数（如果有的话）

所有的BsonValue子类有一个静态的创建方法。我们鼓励您使用的静态Create方法，使子类可以处理特殊情况的要求（通常返回常用值预先创建的对象的一个实例，以避免造成不必要的对象）。在某些情况下，有没有公共的构造函数，你必须使用静态创建方法。

BsonType财产

这个属性可以用来确定实际的的 BsonValue 类型 。当然，你可以使用实际的类的对象做同样的事情，但它往往是更方便，速度更快，使用此属性。下面的例子显示了 几种方法：

BsonValue value;

if (value.BsonType == BsonType.INT32）

/ /我们知道的值是一个实例BsonInt32

}

if (value is BsonInt32) {

/ /另一种方式告诉该值是一个BsonInt32

}

if (value.IsInt32) {

/ /最简单的方法，告诉该值是一个BsonInt32

}

另请参阅[类型]最便捷的方式来测试，如果值是一个特定类型的属性。

[类型]属性

BsonValue定义一些属性，可用于沮丧的一个BsonValue一个具体的类型。的结果[类型]属性的一个子类的BsonValue或在适当的时候。NET的原始值。作为[类型]属性的完整列表是：

AsBoolean (bool)

AsBsonArray

AsBsonBinaryData

AsBsonDocument

AsBsonJavaScript / /也可以，如果BsonType == JavaScriptWithScope

AsBsonJavaScriptWithScope

AsBsonMaxKey

AsBsonMinKey

AsBsonNull

AsBsonRegularExpression

AsBsonSymbol

AsBsonTimestamp

AsByteArray

AsDateTime (DateTime)

AsDouble (double)

AsGuid (Guid)

AsInt32 (int)

AsInt64 (long)

AsObjectId

AsString (string)

的回报。NET基本类型的属性后，他们在上面的列表中，括号中的一个。NET类型的。

所有这些属性抛出一个InvalidCastException，如果实际类型的BsonValue是不是必需的。如果你不确定类型 的BsonValue，你可以事先测试使用的是[类型]属性如下所述。

AsBsonJavaScript是一个特殊的情况下，即使成功，因为它的实际类型的价值是BsonJavaScriptWithScope的，因为BsonJavaScriptWithScope是一个子类，BsonJavaScript。

[类型]属性，它可以将某些类型之间的更为有限。

[类型]属性

BsonValue定义一些属性，可以用来查询特定类型的一个实例BsonValue。这些便利，让你写的更紧凑的代码。例如:

if (value.IsString) {

/ /我们知道的值是一个实例BsonString

/ /我们也知道价值。AsString不会失败

}

的完整列表[类型]属性是：

IsBoolean

IsBsonArray

IsBsonBinaryData

IsBsonDocument

IsBsonJavaScript

IsBsonJavaScriptWithCode

IsBsonMaxKey

IsBsonMinKey

IsBsonNull

IsBsonRegularExpression

IsBsonSymbol

IsBsonTimestamp

IsDateTime

IsDouble

IsGuid

IsInt32

IsInt64

IsObjectId

ISSTRING

[类型]的方法

BsonValue提供了一些方法 ，可以进行有限的类型之间的转换。这些转换的，在大多数情况下是安全的，被预期不会失败。在[类型]的 方法是：

ToBoolean

ToDouble

ToInt32

ToInt64

ToBoolean方法 永远不会失败。它使用JavaScript定义2006：。2006年：内感真相，假，0，0.0，南，BsonNull和“是假的，一切是”真“（包括字符串”假“！）。

ToBoolean方法 是非常有用的，当你正在处理的文件有不一致的方式记录true / false值。例如:

if (employee[“ismanager”].ToBoolean（））{

/ /我们知道员工是经理

/ /即使价值有时是正确的，有时1

}

将工作，即使混合使用的文件类型 代表true / false值。相比之下，AsBoolean的属性将只 当值被记录下来使用严格BsonBoolean值。

ToDouble，ToInt32犯法，ToInt64方法将失败，如果转换之间的数值类型（虽然可能会被截断值！）。如果转换的一些目标类型，如果该字符串可以被解析为一个字符串，他们会取得成功 ，否则，抛出一个异常。

创建方法

虽然你不能创建实例BsonValue，在BsonValue类有一个 静态方法调用创建，你可以用它来 创建具体的实例BsonValue。在运行时的基础上提供的值的实际类型 决定所产生的BsonValue。A N 异常被抛出，如果提供的价值不能被映射到一个BsonValue。例如:

BsonValue value = BsonValue.Create(1); // creates a BsonInt32

BsonValue value = BsonValue.Create(1.0); // creates a BsonDouble

BsonValue value = BsonValue.Create(“abc”); // a BsonString

如果你想选择的BsonValue类型，使用的子类BsonValue，而不是一个静态的创建方法：

BsonDouble value = BsonDouble.Create(1);

BsonJavaScript value = BsonJavaScript.Create(“this.a == 4”);

BsonSymbol value = BsonSymbol.Create(“+”);

在第一种情况将创建一个BsonDouble，和int值将被转换为双精度值1.0。在第二个例子将创建一个BsonJavaScript，编码值将是“this.a == 4”。在第三种情况下将创建一个BsonSymbol的“+”定定地看着在BsonSymbolTable的。 如果提供的值不能转换为需要的类型的BsonValue子类抛出一个异常。

。NET类型的隐式转换BsonValue

BsonValue类还定义了一些隐式转换BsonValue的。这使得它非常容易地创建BsonValues。下面是一些例子：

BsonValue value = 1; // converts 1 to a BsonInt32

BsonValue value = 1.0; // converts 1.0 to a BsonDouble

BsonValue value = “abc”; // converts “abc” to a BsonString

这些隐式转换是特别方便。NET值作为参数调用函数时，采取BsonValue的一个参数，允许你使用原始 。这些隐式转换的一个重要优势是映射。NET类型的 匹配 BsonType，发生在编译的时候，这样的创作是非常快的BsonValues。也有非常小的开销的事实是，我们 正在创建一个实例BsonValue，因为如果我们不使用BsonValue和使用的对象，而不是 所有的原始。NET值将不得不盒装的。从本质上讲，BsonValue就是我们的方式拳。NET类型（但我们的方法，我们得到，以标记值与BsonType的和我们得到了很多有用的属性和方法定义）。

下列隐式转换定义如下：

NET类型。	BsonType
bool	Boolean
byte[]	Binary (subtype Binary)
DateTime	DateTime
double	Double
GUID	Binary (subtype Uuid)
int	Int32
long	Int64
Regex	RegularExpression
string（字符串）	String

隐式转换的列表是相当短的目的。我们只定义了隐式转换的情况下，有一个完全匹配的。NET类型和相应的BsonType，其中有可以不丢失信息的转换。

从BsonValue。NET类型的显式转换

作为一种替代[类型]属性BsonValue类也定义了一组明确一些。NET原始类型的转换。例如，下面的两个语句是等价的：

int age = person[“age”].AsInt32;

int age = (int) person[“age”];

所提供的显式转换的一组是完全相反的组提供的隐式转换，所以在上一节的表可以读取由右至左，以寻找可用的显式转换。

你可以使用任何你喜欢的，但 由于[类型]的方法往往更具可读性。考虑这些：

string zip = person[“address”].AsBsonDocument[“zip”].AsString;

string zip = (string) ((BsonDocument) person[“address”])[“zip”];

在第二种形式中，你学会更好地得到所有这些括号恰到好处！

Equals和GetHashCode方法 （和运算符==和！=）

的BsonValue类的所有重载equals和GetHashCode的因此，BsonValue的情况下，安全使用字典中的键。

BsonValue子类

前面我们提到过，有一个子类BsonValue每BsonType。下面是的完整列表BsonValue子类：

BsonArray

BsonBinaryData

BsonBoolean

BsonDateTime

BsonDocument

BsonDouble

BsonInt32

BsonInt64

BsonJavaScript

BsonJavaScriptWithScope

BsonMaxKey

BsonMinKey

BsonObjectId

BsonRegularExpression

BsonString

BsonSymbol

BsonTimestamp

我们将讨论这些子类的简单地说，离开BsonDocument BsonArray的结束，因为他们是最复杂的。

BsonBinaryData类

这个类持有BSON类型 的二进制 值 。它具有 以下的属性和方法（除了继承自BsonValue）：

BsonBinaryData(byte[] bytes)

BsonBinaryData(byte[] bytes, BsonBinarySubType subType)

BsonBinaryData（GUID GUID）

byte[] Bytes

BsonBinarySubType SubType

implicit conversion from byte[]

implicit conversion from Guid

static BsonBinaryData Create(byte[] bytes)

static BsonBinaryData Create(byte[] bytes,

BsonBinarySubType subType)

static BsonBinaryData Create(Guid guid)

static BsonBinaryData Create(object value)

Guid ToGuid()

BsonBoolean类

这个类包含的BSON类型 布尔 值 。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonBoolean(bool value)

static BsonBoolean False

static BsonBoolean True

object RawValue

bool Value

implicit conversion from bool

static BsonBoolean Create(bool value)

static BsonBoolean Create(object value)

这个类有一些预先创建的实例（FALSE，TRUE）。您可以使用他们自己，和Create方法返回他们在适当的时候。

BsonDateTime类

这个类持有BSON DateTime类型的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonDateTime(DateTime value)

object RawValue

DateTime Value

implicit conversion from DateTime

static BsonDateTime Create(DateTime value)

static BsonDateTime Create(object value)

需要注意的是BSON DateTime值始终在UTC。

BsonDouble类

这个类持有BSON类型双值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonDouble(double value)

object RawValue

double Value

implicit conversion from double

static BsonDouble Create(double value)

static BsonDouble Create(object value)

BsonInt32类

这个类持有BSON Int32类型的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonInt32(int value)

static BsonInt32 MinusOne

static BsonInt32 Zero

static BsonInt32 One

static BsonInt32 Two

static BsonInt32 Three

object RawValue

int Value

implicit conversion from int

static BsonInt32 Create(int value)

static BsonInt32 Create(object value)

这个类有一些预先创建的实例（MinusOne，零，一，二，三）。静态创建方法将返回他们在适当的时候。

BsonInt64类

此类包含BSON类型的Int64值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonInt64(long value)

object RawValue

long Value

implicit conversion from long

static BsonInt64 Create(long value)

static BsonInt64 Create(object value)

BsonJavaScript类

这个类拥有的BSON JavaScript类型的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonJavaScript(string code)

object RawValue

string Code

implicit conversion from string

static BsonBinaryData Create(object value)

static BsonJavaScript Create(string code)

BsonJavaScriptWithScope类

这个类包含值BSON类型JavaScriptScope的。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonJavaScriptWithScope(string code, BsonDocument scope)

string Code // inherited from BsonJavaScript

BsonDocument Scope

static BsonJavaScriptWithScope Create(object value)

static BsonJavaScriptWithScope Create(string code,

BsonDocument scope)

请注意，BsonJavaScriptWithScope是一个子类的BsonJavaScript。

BsonMaxKey类

这个类持有单一值BSON类型MaxKey的。它 具有以下的属性和方法（除了继承自BsonValue）：

static BsonMaxKey Singleton // can use Bson.MaxKey instead

请注意，这个类实现独立的，并因此它只有一个实例存在。您可以在你的代码中访问此单一值在两个方面：

BsonMaxKey mk = BsonMaxKey.Singleton;

BsonMaxKey mk = Bson.MaxKey / /更方便

BsonMinKey类

这个类持有单一值BSON类型MinKey的。它 具有以下的属性和方法（除了继承自BsonValue）：

static BsonMinKey Singleton // can use Bson.MinKey instead

请注意，这个类实现独立的，并因此它只有一个实例存在。您可以在你的代码中访问此单一值在两个方面：

BsonMinKey mk = BsonMinKey.Singleton;

BsonMinKey mk = Bson.MinKey / /更方便

BsonNull类

这个类包含的单身BSON类型的空值。它 具有以下的属性和方法（除了继承自BsonValue）：

static BsonNull Singleton // can use Bson.Null instead

请注意，这个类实现独立的，并因此它只有一个实例存在。您可以在你的代码中访问此单一值在两个方面：

BsonNull n = BsonNull. // Singleton

BsonNull n = Bson.NULL; / /更方便

注意，也有BsonElement永远不会有一个C＃NULL作为它的值，取而代之的是BsonNull单身是用来表示的BSON空值。

BsonObjectId类

这个类包含的值BSON类型的ObjectId的 。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonObjectId(byte[] bytes) // must be exactly 12 bytes

BsonObjectId(int timestamp, long machinePidIncrement)

BsonObjectId(ObjectId value)

BsonObjectId(string value)

int Timestamp // first 4 bytes of ObjectId

long MachinePidIncrement // last 8 bytes of ObjectId

int Machine

int Pid

int Increment

object RawValue

ObjectId Value

DateTime CreationTime // derived from Timestamp

implicit conversion from ObjectId

static BsonObjectId Create(byte[] bytes)

static BsonObjectId Create(int timestamp,

long machinePidIncrement)

static BsonObjectId Create(object value)

static BsonObjectId Create(ObjectId value)

static BsonObjectId Create(string value)

static BsonObjectId GenerateNewId()

static BsonObjectId Parse(string value)

static bool TryParse(string value, out BsonObjectId objectId)

byte[] ToByteArray()

的ObjectId结构在下一节。之间的差异BsonObjectId和OBJECTID是BsonObjectId是一个子类，BsonValue可以的BsonElement的价值，而objectid是一个结构和包含的实际 物理表示一个ObjectID（这样的Value属性的BsonObjectId类型的ObjectId）。 的ObjectID的属性回荡在BsonObjectId，只需调用底层的ObjectId属性。

OBJECTID STRUCT

这个结构持有一个 ObjectID的物理表示 。它具有以下 的属性和方法：

ObjectId(byte[] bytes) // must be exactly 12 bytes

ObjectId(int timestamp, long machinePidIncrement)

ObjectId(string value)

int Timestamp // first 4 bytes of ObjectId

long MachinePidIncrement // last 8 bytes of ObjectId

int Machine

int Pid

int Increment

DateTime CreationTime // derived from Timestamp

static ObjectId GenerateNewId()

static ObjectId Parse(string value)

static bool TryParse(string value, out ObjectId objectId)

byte[] ToByteArray()

BsonRegularExpression类

此类包含BSON类型正则表达式的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonRegularExpression(string pattern) // options == “”

BsonRegularExpression(string pattern, string options)

BsonRegularExpression(Regex regex)

string Pattern

string Options

implicit conversion from Regex

implicit conversion from string

static BsonRegularExpression Create(object value)

static BsonRegularExpression Create(string pattern)

static BsonRegularExpression Create(string pattern,

string options)

static BsonRegularExpression Create(Regex regex)

Regex ToRegex()

BsonString类

这个类持有BSON String类型的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonString (string value)

static BsonString Empty

object RawValue

string Value

implicit conversion from string

static BsonString Create(object value)

static BsonString Create(string value)

这个类有一个预先创建的实例（空）。您可以使用它自己的Create方法返回在适当的时候。

BsonSymbol类

这个类持有BSON类型符号的值。它 具有以下的属性和方法（除了继承自BsonValue）：

string Name

implicit conversion from string

static BsonSymbol Create(object value)

static BsonSymbol Create(string name)

这个类没有一个公共的构造函数，因为BsonSymbols保证是唯一的，因此你必须使用静态Create方法，而不是（它看起来的BsonSymbol的BsonSymbolTable和创建一个新的的实例BsonSymbol仅在必要时）。

BsonTimestamp类

这个类持有的BSON Timestamp类型的值。它 具有以下的属性和方法（除了继承自BsonValue）：

BsonTimestamp(int timestamp, int increment)

BsonTimestamp(long value)

object RawValue

long Value

int Timestamp // high order 32 bits of Value

int Increment // low order 32 bits of Value

implicit conversion from long

static BsonTimestamp Create(int timestamp, int increment)

static BsonTimestamp Create(long value)

static BsonTimestamp Create(object value)

BsonElement类

这个类表示的BSON元素 的名称/值对的 实例 。它是什么BsonDocuments包含（不像BsonArrays，其中包含BsonValues）。这是一个非常简单的类，包含以下方法和属性：

BsonElement(string name, BsonValue value)

string Name

BsonValue Value

static BsonElement Create(string name, BsonValue value)

static BsonElement Create(bool condition, string name,

BsonValue值）

你可能不会有明确地建立BsonElement，很多时候，他们就越有可能将创建自动为您调用的Add方法BsonDocument之一当你。

静态创建方法的返回值是C＃空C＃空（或者，如果条件为假）。

需要注意的是BsonElement实现Equals和GetHashCode，所以BsonElements的，可以作为字典键。

BsonDocument类

这个类是C＃驱动程序的主力 。您将使用了很多！因为它是用来这么多的接口是有点复杂的，以提供许多常见的用例。基本上有三种方式创建和填充BsonDocument的：

1.       创建一个新的文件，并调用添加和设置方法

2. 创建一个新的文件，并使用C＃集合初始化器的语法

3创建一个新的文件，并使用流畅的界面风格，支持添加和设置

首先是简单，易于使用，但第二，要求您要熟悉与集合初始化器的语法，更具有可读性和推荐的方法是创建BsonDocuments。

BsonDocument构造函数

您可以使用BsonDocument的构造函数来创建一个空的BsonDocument或作为一个简单 的方法来创建一个单一的元素BsonDocument。所有重载BsonDocument（有两个例外），只是简单的调用提供的参数匹配的Add方法。

，要创建一个空BsonDocument的写：

BsonDocument document = new BsonDocument();

要创建一个文档填充一个元素写：

BsonDocument query = new BsonDocument(“author”, “Hemmingway”);

默认情况下，BsonDocument不重复的元素名称，如果您尝试添加一个元素与现有名称抛出一个异常。如果你想允许重复的元素的名称，您必须使用下面的构造函数：

BsonDocument document = new BsonDocument(true); // allow dups

document.Add(“hobby”, “hiking”);

document.Add(“hobby”, “cycling”); // only acessible via index

BsonValue h1 = document[“hobby”]; // returns “hiking”

BsonValue h2 = document[0]; // also returns “hiking”

BsonValue h3 = document[1]; // returns “cycling”

也有过载的BsonDocument的构造函数，它接受一个：

• BsonElement
• IDictionary<string, object>
• IEnumerable<BsonElement>
• params BsonElement[]

请参阅相应的Add方法的说明，每一个。

BsonDocument构造函数与集合初始化器的语法

这是首选的方式来创建和填充BsonDocuments，（除单元素文件的 名称和值 传递 给构造函数 更容易地创建 ）。C＃集合初始化器语法的工作方式是，它可以让你提供的值的列表（可以是元组），被 传递到一个匹配的Add方法 。简单的编译器将调用 匹配 的 Add方法 。许多中创建示例代码，您见过这么远的BsonDocuments使用此语法。例如:

BsonDocument book = new BsonDocument {

{ “author”, “Ernest Hemingway” },

{ “title”, “For Whom the Bell Tolls” }

};

由编译器被转换为以下：

BsonDocument book = new BsonDocument();

book.Add(“author”, “Ernest Hemingway”);

book.Add(“title”, “For Whom the Bell Tolls”);

这两者是完全等效的，但首先是更加优雅和可读性，因为它反映了结构的BsonDocument正在创建更加简洁。

使用集合初始化器的语法时，一个常见的错误是忘记了一个括号套。这不起作用的原因是明显的，当我们看到，编译器将其转换：

BsonDocument wrong = new BsonDocument { “name”, “value” };

到：

BsonDocument wrong = new BsonDocument();

错误。添加NAME

错误。扩大广告价值。

编译时错误，因为没有相匹配的签名（幸好）的Add方法。

BsonDocument构造函数用流利的接口方法

到构建一个BsonDocument的另一种方式是使用流畅的界面风格Add方法来填充文件。例如:

BsonDocument book = new BsonDocument()

.Add(“author”, “Ernest Hemingway”)

.Add(“title”, “For Whom the Bell Tolls”);

我们并不网友的这种风格，因为我们觉得C＃集合初始化器的语法是优越的，但如果你从另一个驱动程序的移植代码，你会发现这种风格有用的。

AllowDuplicateNames财产

确定该文件是否被允许包含重复的名称或。BSON标准规定，重复的名字是不允许的，但在某些情况下，它可能是有用的（例如，当一个XML文档映射到BsonDocument）。

Count属性

此属性返回该文件包含的元素的数量。

元素属性

此属性返回一个可用于列举了文档的元素的IEnumerable的<BsonElement>值。您也可以枚举元素在一个BsonDocument的直接（不使用元素属性）因为 BsonDocument 实现了IEnumerable <BsonElement>。的名字也，价值观和RawValues的性能。

名称属性

此属性返回的IEnumerable的<String>的值，可以用来列举了文档的元素的名称。

RawValues财产

该属性返回一个的IEnumerable的<OBJECT>值，可以用来列举了为原料的对象（而不是所有BsonValues的原始值，布尔，日期时间，双，INT32，的Int64，String和时间戳的文件的元素的值这样做）。返回的序列包含C＃空为任何BsonValue的 s的类型，没有RawValue。

Values属性

此属性返回一个枚举的值的的文件，BsonValues的元素，可用于的IEnumerable的<BsonValue>值。

添加方法

有很多重载的Add方法。请注意，在所有情况下，C＃空值将被忽略，所以你就不必把if语句添加在你的电话，以检查是否你的价值是空的（假设你希望它被忽略）。当 一个Add方法传递一个C＃空值，它根本什么都不做。

添加（BsonElement）方法

这是基本的Add方法。所有其他的Add方法调用这一个。此方法的行为略有不同，具体取决于是否允许重复的元素名称或没有。如果重复的名字是不允许的元素具有相同的名称存在，则抛出一个异常，否则它被添加到集合末尾，并且只能通过索引访问（访问将返回现有的元素，而不是新的名字1）。

添加方法（IEnumerable的<BsonElement>）

这个方法只是简单地调用的添加（BsonElement）的每个元素传递的。

添加（名称，值）的方法

此方法创建和一个BsonElement添加到文档中，如果提供的值是C＃空 。例如:

BsonDocument book = new BsonDocument();

book.Add(“author”, “Ernest Hemingway”);

由于这Add方法将其参数直接通过的BsonElement构造，你可以参考下面的讨论中有关创建BsonElements的和。NET提供的价值映射到一个BsonValue的。

重要的是要记住，Add方法不执行任何操作，如果该值suplied是一个C＃空。如果你想一个BSON的NULL被存储为一个缺失值，您必须提供的BSON空值自己。一个方便的方式做到这一点是使用C＃的空合并运算符：

BsonDocument book = new BsonDocument {

{ “author”, author ?? Bson.Null }

};

添加方法（条件，名称，值）

此方法创建并添加了一个新的BsonElement的文件，如果条件为真时提供的值是C＃空 。这种方法的存在是为了支持有条件地将元素添加到文档时，使用C＃集合初始化器的语法。例如:

BsonDocument book = new BsonDocument {

{ “author”, “Ernest Hemingway” },

{ “title”, “For Whom the Bell Tolls” },

{havePublicationDate，“publicationDate”，publicationDate}

};

这是唯一真正必要的结构值（因为它们不能被C＃NULL）。例如，假设您只是想添加的“字幕”元素，如果它不是C＃空。我们可以简单的写：

BsonDocument book = new BsonDocument {

{ “author”, “Ernest Hemingway” },

{ “title”, “For Whom the Bell Tolls” },

{ “subtitle”, subTitle }

};

如果该值的副标题是C＃空“字幕”元素将被添加到文档中。

添加方法（IEnumerable的<BsonElement>）

每一个元素将被添加这BsonDocument。需要注意的是不被复制的元素。

由于BsonDocument实现了IEnumerable <BsonElement>，你可以传递一个的实例BsonDocument这种方法。然而，由于该元素不被克隆，相同的BsonElements是在两个BsonDocuments的。这意味着，如果你改变了价值的BsonElement在一个文档中，它会改变其他。如果你不希望这种行为，那么你之前，必须复制的元素添加到 文档中。例如:

BsonDocument order = new BsonDocument();

BsonDocument items; // passed in from somewhere

order.Add(items); // 元素现在在这两份文件

或者，如果你不想共享的元素，这两个文件之间使用之一：

order.Add((BsonDocument) items.Clone

order.Add((BsonDocument) items.DeepClone（））;

这取决于你是否需要浅或深的克隆。

默认的行为是不能克隆，因为克隆是昂贵的，这样一来，我们默认情况下，最有效的行为，你会得到来决定何时克隆的成本是必要的。

（IDictionary的<string,的对象）的方法

这种方法增加了新的元素到基于一个BsonDocument的一本字典的内容。在字典中的每个键成为新元素的名称，以及每个对应的值成为新的元件的值。与往常一样，这个方法调用每个新元素的添加（BsonElement）的处理，所以重复的名称所描述的添加（BsonElement）。

清除方法

该方法将删除所有文档中的元素。

Contains方法

这种方法测试该文件是否包含给定名称的元素。

ContainsValue方法

此方法测试该文件是否包含与给定的值的元素。

GetElement方法

通常情况下，你会使用GetValue，或更常见相应的索引。在极少数情况下，您可能需要得到BsonElements自己使用的两种重载GetElement（如果指数，如果按名称）。

GetValue方法和索引

GetValue方法主要有三种形式：第一个数字索引，第二个需要的元素的名称，和第三也需要 一个默认值被返回，如果不存在该名称的元素。在所有情况下返回值类型BsonValue，。还设有一个匹配索引器每个GetValue方法。例如:

BsonDocument book = books.FindOne（）;

string author = book.GetValue(“author”).AsString;

DateTime publicationDate =

book.GetValue(“publicationDate”).AsDateTime;

int pages = book.GetValue(“pages”).AsInt32;

int pages = book.GetValue(“pages”, -1).AsInt32; / /默认-1

或使用的索引，这是推荐的方法：

BsonDocument book = books.FindOne（）;

string author = book[“author”].AsString;

DateTime publicationDate = book[“publicationDate”].AsDateTime;

int pages = book[“pages”].AsInt32;

int pages = book[“pages”, -1].AsInt32; / /默认-1

由于BsonValue还支持显式转换到对应的。NET类型，这个例子也可以写成：

BsonDocument book = books.FindOne（）;

string author = (string) book[“author”];

DateTime publicationDate = (DateTime) book[“publicationDate”];

int pages = (int) book[“pages”];

int pages = (int) book[“pages”, -1]; // default -1

使用 这些方法， 你是一个个人选择的问题。我们建议第二种 方法（使用索引和[类型]属性），因为我们认为它是最可读的（不需要额外的括号有时需要的类型转换（可以是特别混乱时，他们被嵌套（它们经常是）））。比较下面的两个语句：

/ /每人是一个BsonDocument的了

BsonDocument firstBorn =

person[“children”].AsBsonArray [0]。AsDocument;

BsonDocument firstBorn =

(BsonDocument) ((BsonArray) person[“children”])[0];

第一 是有点更容易读取从左到右。相同的事件序列是在这两种情况下发生：

1.       被检索的个人文档的“孩子们”的元素（BsonValue）

2. 该BsonValue转换为一个BsonArray

3被检索的孩子数组的第一个元素（BsonValue）

4：BsonValue转换为一个BsonDocument的

有一个名字参数获取方法抛出一个异常，如果没有找到具有该名称的元素，并没有提供默认值 。请参阅TryGetValue方法，如果你不想要一个例外。

Merge方法

这种方法允许你合并元素从一个BsonDocument到另一个。从源文档的每个元件进行测试，以查看是否具有该名称的目标文档已经有一个元素。如果该名称已经存在，该元素将被跳过，如果不是，它被添加到目标文档。

删除方法

此方法用于删除一个元素从BsonDocument。如果允许重复的文件名，然后调用删除将删除与该名称的所有元素。

RemoveAt方法

此方法用于删除一个元素从一个BsonDocument使用它的索引位置。

设置方法（指数值）

虽然大多数的时候，你会访问元素的名称，偶尔会访问他们的指数。使用此方法时，该文件必须已经有一个元素在该指数或将抛出一个异常。有一个等价的索引。例如:

book.Set(0, “Ernest Hemingway”); // assume element 0 is author

book[0] = “Ernest Hemingway”; // shorter and better

SET（名称，值）的方法

如果这个名字的元素存在，它的值将被替换为新的值，否则这个名字和值的一个新的元素。例如:

BsonDocument book = new BsonDocument();

book.Set(“author”, “Ernest Hemway”); // adds element

/ /一些其他的工作

/ /注意，作者姓名拼写错误

书的声音Set(“author”, “Ernest Hemingway”); // replaces value

使用的索引器，前面的例子可以写成：

BsonDocument book = new BsonDocument();

book[“author”] = “Ernest Hemway”; // adds element

/ /一些其他的工作

/ /注意，作者姓名拼写错误

book[“author”] = “Ernest Hemingway”; // replaces value

ToBson方法

此方法将BSON格式的二进制序列化的BsonDocument作为一个字节数组，并返回序列化的文件。

toJSON方法

此方法将序列化的BsonDocument的的一个JSON格式的字符串。这是可能的，有一定的控制生成的JSON表示提供一些BsonJsonWriterSettings的。

ToString方法

这种方法是覆盖调用的ToJSON使用默认设置。它主要用于调试。如果您有意创建JSON调用的ToJSON。

TryGetElement和TryGetValue方法

如果你不知道该文件所包含的元素与给定的名称，你可以第一个测试使用Contains方法或使用的TryGetElement或TryGetValue方法。例如:

BsonValue age;

if (person.TryGetValue(“age”, out age)) {

/ /做一些事情随着年龄的增长

} else {

/ /处理丢失的年龄情况

}

BsonArray类

这个类是用来代表BSON阵列。需要注意的是，而BSON阵列外部表示作为一个的BSON文档中（用一个特殊的命名约定的元素），C＃ 驱动程序 的BsonArray类是没有关系的的BsonDocument类。这是因为一个BsonArray作为BsonDocument外部表示的事实是偶然的，实际行为一个BsonArray是非常从一个BsonDocument不同。

BsonArray构造函数

您可以使用不带参数的构造函数创建一个空的数组，并同时将项目添加到数组，你可以使用C＃的集合初始化器的语法：

BsonArray a1 = new BsonArray(); // empty

BsonArray a2 = new BsonArray { 1 }; // 1 element

BsonArray a3 = new BsonArray { 1, 2, 3 }; // 3 elements

还有一个构造函数的的IEnumerable的<BsonValue>参数（它调用 匹配 的 AddRange方法）。例如:

IEnumerable<BsonValue> values; // from somewhere

BsonArray a = new BsonArray(values); // adds values to array

许多额外超载（IEnumerable的<int>的像）提供支持常见的情况，如：

int[] values = new int[] { 1, 2, 3 };

BsonArray a = new BsonArray(values);

这个例子将不能正确编译的，因为IEnumerable <int>的不能自动转换到IEnumerable <BsonValue>的IEnumerable的<int>的过载。 IEnumerable的重载为布尔型，日期时间型，双，整型，长，对象和字符串。

索引器属性

这个类提供了一个索引属性来获取或设置数组中的元素。的索引器返回类型是 BsonValue，的，所以通常有做一些转换 。例如:

array[0] = “Tom”;

array[1] = 39;

string name = array[0].AsString;

int age = array[1].AsInt32;

Count属性

这个属性返回的值存储在BsonArray

添加方法

只有一个Add方法，它 一个BsonValue添加到数组（但也看到AddRange方法）。例如:

BsonValue value; // from somewhere

array.Add(value);

array.Add(1); // implicit conversion from int to BsonInt32

AddRange方法

一个重载，AddRange方法需要的IEnumerable <BsonValue>参数和添加 多个项目的数组。例如:

IEnumerable<BsonValue> values; // from somewhere

array.AddRange(values); // adds values to array

许多额外超载（IEnumerable的<int>的像）提供支持常见的情况，如：

int[] values = new int[] { 1, 2, 3 };

array.AddRange(values);

这个例子将无法编译，因为IEnumerable <int>的不能被自动转换IEnumerable的 <BsonValue>的 没有了IEnumerable <int>的过载 。IEnumerable的重载为布尔型，日期时间型，双，整型，长，对象和字符串。

清除方法

此方法清除所有值的数组。

的indexOf方法

可以使用下面的indexOf方法找到在数组中的值的索引：

int IndexOf(BsonValue value)

int IndexOf(BsonValue value, int index)

int IndexOf(BsonValue value, int index, int count)

他们所有的工作一样名单<T>匹配的indexOf方法，则返回-1，如果没有匹配的数组中的项目。

插入方法

此方法用于添加一个值，在阵列中的一个特定的位置。例如:

array.Insert(2, value);

这个例子假设数组包含至少2个元素。如果包含两个以上的元素，索引2处的元素开始被移到一个位置，以腾出空间给新的元素。

删除方法

Remove方法从数组中删除一个特定的值。如果该值出现不止一次 在数组中，只有第一个实例被 删除。所有剩余的元素被转移到右侧，以便不留间隙，在阵列中，得到的数组会更短（除非没有匹配的元素被发现在这种情况下，这个方法没有任何效果）。

RemoveAt方法

此方法将删除从一个特定的值在数组中的位置。跟随它的任何元素移动一个位置向左侧和阵列是现在缩短一个元件的。