插入文档

Overview

在本指南中，您可以了解如何使用 MongoDB .NET/C# 驱动程序通过执行插入操作将文档添加到 MongoDB 集合。

插入操作将一个或多个文档插入MongoDB集合。.NET/ C#驱动程序提供了以下方法来执行插入操作，每种方法都有同步和异步版本：

• InsertOne() or ``InsertOneAsync()

• InsertMany() or InsertManyAsync()

public class Restaurant
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    [BsonElement("restaurant_id")]
    public string RestaurantId { get; set; }
    public string Cuisine { get; set; }
    public Address Address { get; set; }
    public string Borough { get; set; }
    public List<GradeEntry> Grades { get; set; }
}

public class Address
{
    public string Building { get; set; }
    [BsonElement("coord")]
    public double[] Coordinates { get; set; }
    public string Street { get; set; }
    [BsonElement("zipcode")]
    public string ZipCode { get; set; }
}

public class GradeEntry
{
    public DateTime Date { get; set; }
    public string Grade { get; set; }
    public float? Score { get; set; }
}

_id 字段

在 MongoDB 集合中，每个文档必须包含具有唯一字段值的 _id 字段。

MongoDB 允许您通过两种方式管理该字段：

• 您可以自行为每个文档设置此字段，确保每个 _id 字段的值都是唯一的。

• 您可以让驱动程序为每个文档 _id 自动生成唯一的 ObjectId 值。如果您没有为文档手动设置 _id 字段值，则驱动程序将用 ObjectId 填充该字段。

除非您可以保证唯一性，否则 MongoDB 建议让驱动程序自动生成 _id 值。

如要了解有关 _id 字段的更多信息，请参阅有关唯一索引的 Server 手册条目。

要了解有关文档结构和规则的更多信息，请参阅服务器手册中有关文档的条目。

插入一个文档

以下代码演示如何使用同步 InsertOne() 方法或异步 InsertOneAsync() 方法插入一个文档。

_restaurantsCollection.InsertOne(document);

await _restaurantsCollection.InsertOneAsync(document);

插入多个文档

以下代码演示如何使用同步 InsertMany() 方法或异步 InsertManyAsync() 方法插入多个文档。

_restaurantsCollection.InsertMany(docs);

await _restaurantsCollection.InsertManyAsync(docs);

修改插入行为

InsertOne() 方法将您要插入的文档作为参数。InsertMany()方法采用 IEnumerable 文档集合（例如列表或数组）作为参数。

InsertOne() 方法可以选择性地采用 InsertOneOptions 类型作为附加参数，此参数表示可用来配置插入操作的选项。如果您不指定任何 InsertOneOptions 属性，驱动程序将不会自定义插入操作。

InsertOneOptions 类型允许您使用以下属性配置选项：

InsertMany() 方法可以选择采用 InsertManyOptions 类型作为附加参数，该参数具有前面的 BypassDocumentValidation 和 Comment 属性，以及附加的 IsOrdered 属性：

// Generates 5 new restaurants by using a helper method
var restaurants = GenerateDocuments();
// Creates an option object to bypass documentation validation on the documents
var options = new InsertManyOptions() { BypassDocumentValidation = true };
// Inserts the new documents into the restaurants collection with the specified options
_restaurantsCollection.InsertMany(restaurants, options);

指定有序行为

假设要插入以下文档：

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 1, "name" : "Restaurant C" }
{ "_id" : 3, "name" : "Restaurant D" }

如果尝试使用默认InsertManyOptions 插入这些文档，则驱动程序会在插入第三个文档时抛出 MongoBulkWriteException，因为 _id 值重复。该操作仅将前两个文档添加到集合：

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }

如果您在插入操作中将 IsOrdered设立为 false，则即使某些文档产生错误，驱动程序也会继续插入文档。通过此修改后的插入行为，驱动程序会引发异常，但会插入所有不会产生错误的文档：

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 3, "name" : "Restaurant D" }

更多信息

有关插入操作的可运行示例，请参阅以下使用示例：

• InsertOne()

• InsertOneAsync()

• InsertMany()

• InsertManyAsync()