c# MongoDB Driver 官方教程翻译
先贴官方文档地址:http://mongodb.github.io/mongo-csharp-driver/
安装部分很简单,nuget搜索并安装 MongoDB.Driver
MongoDB Driver快速浏览
这是MongoDB驱动程序快速浏览的第一部分。在这一部分中,我们将看看如何执行基本的CRUD(创建,读取,更新,删除)操作。在接下来的部分,我们将看看执行一些管理功能。
建立连接
以下示例显示了连接到本地计算机上的一个或多个服务器的三种方法。
// To directly connect to a single MongoDB server // (this will not auto-discover the primary even if it's a member of a replica set) var client = new MongoClient(); // or use a connection string var client = new MongoClient("mongodb://localhost:27017"); // or, to connect to a replica set, with auto-discovery of the primary, supply a seed list of members var client = new MongoClient("mongodb://localhost:27017,localhost:27018,localhost:27019");
该client
实例现在拥有一个到连接字符串中指定的服务器或服务器的连接池。
MongoClient
该MongoClient
实例实际上代表了一个到数据库的连接池; 即使有多个线程,您也只需要MongoClient类的一个实例。
重要
通常,您只能MongoClient
为给定群集创建一个实例,并在整个应用程序中使用它。MongoClients
但是,只有在连接字符串相同的情况下,创建多个意志仍将共享相同的连接池。
获取数据库
要获取数据库,请在上面的GetDatabase
方法中指定数据库的名称client
。如果数据库尚不存在,那也没问题。它将在第一次使用时创建。
var database = client.GetDatabase("foo");
该database
变量现在拥有对“foo”数据库的引用。
获取收藏
要获取集合以进行操作,请将集合的名称指定给该GetCollection<TDocument>
方法database
。如果该集合尚不存在,那也没关系。它将在第一次使用时创建。
var collection = database.GetCollection<BsonDocument>("bar");
该collection
变量现在拥有对“foo”数据库中“bar”集合的引用。
注意
泛型参数TDocument
表示集合中存在的模式。上面,我们用a BsonDocument
来表示我们没有预定义的模式。也可以使用普通的C#对象(POCO)。有关更多信息,请参阅映射文档。
插入文件
一旦拥有collection
实例,就可以将文档插入到集合中。例如,请考虑以下JSON文档; 该文档包含一个嵌入式文档的字段信息:
{ "name": "MongoDB", "type": "database", "count": 1, "info": { x: 203, y: 102 } }
要使用.NET驱动程序创建文档,请使用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.InsertOneAsync(document);
插入多个文档
要插入多个文档,可以使用InsertMany
or InsertManyAsync
方法。
// generate 100 documents with a counter ranging from 0 - 99 var documents = Enumerable.Range(0, 100).Select(i => new BsonDocument("counter", i)); collection.InsertMany(documents); await collection.InsertManyAsync(documents);
计数文件
现在我们已经插入了101个文档(我们在循环中加入了100个,加上第一个文档),我们可以检查是否全部使用Count
or CountAsync
方法。以下代码应该将count的值设置为101。
var count = collection.Count(new BsonDocument()); var count = await collection.CountAsync(new BsonDocument());
注意
该方法的空BsonDocument
参数CountAsync
是一个过滤器。在这种情况下,它是一个空过滤器,指示对所有文档进行计数。
查询集合
使用该Find
方法查询集合。该Find
方法返回一个IFindFluent<TDocument, TProjection>
实例,为链接查找操作选项提供流畅的接口。
查找集合中的第一个文档
要获取集合中的第一个文档,请调用FirstOrDefault
or FirstOrDefaultAsync
方法。FirstOrDefault
返回第一个文档或null。这对仅适用于单个文档的查询或仅对第一个文档感兴趣的查询很有用。
以下示例打印集合中找到的第一个文档。
var document = collection.Find(new BsonDocument()).FirstOrDefault(); Console.WriteLine(document.ToString()); var document = await collection.Find(new BsonDocument()).FirstOrDefaultAsync(); Console.WriteLine(document.ToString());
该示例应打印以下文档:
{ "_id": ObjectId("551582c558c7b4fbacf16735") }, "name": "MongoDB", "type": "database", "count": 1, "info": { "x" : 203, "y" : 102 } }
注意
“ id”元素已被MongoDB自动添加到您的文档中,您的值将与所示值不同。MongoDB保留以“ ”和“$” 开头的字段名称供内部使用。
查找集合中的所有文档
要检索集合中的所有文档,请调用ToList
or ToListAsync
方法。这在预计要返回的文档数量很小时很有用。
var documents = collection.Find(new BsonDocument()).ToList(); var documents = await collection.Find(new BsonDocument()).ToListAsync();
如果文档数量预计很大或者可以迭代处理,那么ForEachAsync
将为每个返回的文档调用回调。
await collection.Find(new BsonDocument()).ForEachAsync(d => Console.WriteLine(d));
要使用同步API遍历返回的文档,请使用带ToEnumerable
适配器方法的C#foreach语句:
var cursor = collection.Find(new BsonDocument()).ToCursor(); foreach (var document in cursor.ToEnumerable()) { Console.WriteLine(document); }
上面的每个例子都会向控制台输出完全相同的东西。有关迭代的更多信息,请参阅参考文档。
使用过滤器获取单个文档
我们可以创建一个过滤器来传递给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 }
使用过滤器获取一组文档
我们还可以从我们的收藏中获得一组文档。例如,如果我们想要获取所有文档i > 50
,我们可以这样写:
var filter = Builders<BsonDocument>.Filter.Gt("i", 50); 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); var cursor = collection.Find(filter).ToCursor(); foreach (var document in cursor.ToEnumerable()) { Console.WriteLine(document); } await collection.Find(filter).ForEachAsync(document => Console.WriteLine(document));
排序文件
我们通过调用Sort
方法为查询查询添加一个排序。下面我们使用Exists
过滤器构建器方法和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();
投影领域
很多时候,我们不需要文档中包含的所有数据。“ 投影”构建器将帮助为查找操作构建投影参数。下面我们将排除“_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());
更新文件
MongoDB支持许多更新运算符。
要最多更新1个文档(如果没有匹配过滤器,则可能为0),请使用UpdateOne
or 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); var result = collection.UpdateOne(filter, update); if (result.IsModifiedCountAvailable) { Console.WriteLine(result.ModifiedCount); } var result = await collection.UpdateManyAsync(filter, update); if (result.IsModifiedCountAvailable) { Console.WriteLine(result.ModifiedCount); }
更新方法返回一个UpdateResult
提供有关操作的信息,包括更新修改的文档数量。
注意
根据服务器的版本,某些功能可能不可用。在这些情况下,我们试图表现出检查其可用性的能力。
删除文件
要删除最多1个文档(如果没有匹配过滤器,则可以为0)使用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); var result = collection.DeleteMany(filter); Console.WriteLine(result.DeletedCount); var result = await collection.DeleteManyAsync(filter); Console.WriteLine(result.DeletedCount);
删除方法返回一个DeleteResult
提供有关操作的信息,包括删除的文档数量。
批量写入
有两种类型的批量操作:
-
有序批量操作。
按顺序执行所有操作,并在第一个错误中执行错误。
-
无序批量操作。
执行所有操作并报告任何错误。无序批量操作不保证执行顺序。
让我们看看使用有序和无序操作的两个简单例子:
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. Ordered bulk operation - order of operation is guaranteed collection.BulkWrite(models); // 2. Unordered bulk operation - no guarantee of order of operation collection.BulkWrite(models, new BulkWriteOptions { IsOrdered = false }); // 1. Ordered bulk operation - order of operation is guaranteed await collection.BulkWriteAsync(models); // 2. Unordered bulk operation - no guarantee of order of operation await collection.BulkWriteAsync(models, new BulkWriteOptions { IsOrdered = false });