Docs 菜单
Docs 主页
/ / /
C#/.NET
/ / /

修改文档

在此页面上

  • Overview
  • 样本数据
  • 更新操作
  • 所需参数
  • 更新一个文档
  • 更新多个文档
  • 自定义更新操作
  • 返回值
  • 例子
  • 替换操作
  • 所需参数
  • 自定义替换操作
  • 返回值
  • 例子
  • 更多信息
  • API 文档

在本指南中,您可以了解如何使用 MongoDB .NET/C# 驱动程序,以通过执行以下操作来修改 MongoDB 集合中的文档:

  • 更新操作

  • 替换操作

.NET/C# 驱动程序提供了以下方法修改文档,每种方法都有异步和同步版本:

  • UpdateOneAsync() or UpdateOne()

  • UpdateManyAsync() or UpdateMany()

  • ReplaceOneAsync() or ReplaceOne()

提示

互动实验室

本页包括一个简短的交互式实验室,演示了如何使用 UpdateManyAsync() 方法修改数据。无需安装 MongoDB 或代码编辑器,即可直接在浏览器窗口中完成此实验。

若要启动实验室,请单击页面顶部的“Open Interactive Tutorial”按钮。要将实验室扩展为全屏格式,请单击实验室窗格右上角的全屏按钮 ()。

本指南中的示例使用 sample_restaurants 数据库中的 restaurants 集合。此集合中的文档使用以下 RestaurantAddressGradeEntry 类作为模型:

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

注意

restaurants集合中的文档使用蛇形命名规则。本指南中的示例使用 ConventionPack 将集合中的字段反序列化为 Pascal 语句,并将它们映射到 Restaurant 类中的属性。

如需了解有关自定义序列化的更多信息,请参阅自定义序列化

此数据集来自 Atlas 提供的示例数据集。请参阅快速入门,以了解如何创建一个免费的 MongoDB 集群并加载这些示例数据。

您可以通过以下方法在 MongoDB 中执行更新操作:

  • UpdateOne(),更新匹配搜索条件的第一个文档

  • UpdateMany(),更新与搜索条件匹配的所有文档

每种更新方法都需要以下参数:

  • 查询筛选器文档,用于确定要更新的记录。 有关查询筛选器的更多信息,请参阅MongoDB 服务器手册

  • 更新文档,其中指定更新操作符(要执行的更新类型)以及应更改的字段和值。 有关更新操作符及其用法的完整列表,请参阅字段更新操作符手册页面

.NET/C# 驱动程序提供了一个 Builders 类,可简化查询筛选器和更新文档的创建。以下代码示例使用 Builders 创建两个文档以用作更新操作中的参数:

  • 查询过滤器,用于搜索 cuisine 字段值为“Pizza”的餐厅

  • 更新文档,用于将这些餐厅的 cuisine 字段的值设置为 "Pasta and breadsticks"

const string oldValue = "Pizza";
const string newValue = "Pasta and breadsticks";
// Creates a filter for all documents with a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
.Eq(restaurant => restaurant.Cuisine, oldValue);
// Creates instructions to update the "cuisine" field of documents that
// match the filter
var update = Builders<Restaurant>.Update
.Set(restaurant => restaurant.Cuisine, newValue);
// Updates all documents that have a "cuisine" value of "Pizza"
return _restaurantsCollection.UpdateMany(filter, update);

提示

更新操作中的聚合管道

如果您使用的是 MongoDB 4.2或更高版本,则可以在更新操作中使用由聚合阶段子集组成的聚合管道。 有关 MongoDB 在更新操作中使用的聚合管道中支持的聚合阶段的更多信息,请参阅有关使用聚合管道构建更新的教程。

以下代码将演示如何使用异步 UpdateOneAsync() 方法或同步 UpdateOne() 方法更新一个文档。

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

以下代码将演示如何使用异步 UpdateManyAsync() 方法或同步 UpdateMany() 方法更新所有匹配文档。

var result = await _restaurantsCollection.UpdateManyAsync(filter, update);
var result = _restaurantsCollection.UpdateMany(filter, update);

提示

附加信息下方查找使用这些方法的可运行示例。

这两种方法都可以选择接受 UpdateOptions 对象作为附加参数,该参数表示可用于配置更新操作的选项。如果您不指定任何 UpdateOptions 属性,则驱动程序不会自定义更新操作。

UpdateOptions 类型允许您使用以下属性配置选项:

属性
说明

ArrayFilters

Specifies which array elements to modify for an update operation on an array field. See the MongoDB server manual for more information.

BypassDocumentValidation

Specifies whether the update operation bypasses document validation. This lets you update documents that don't meet the schema validation requirements, if any exist. See the MongoDB server manual for more information on schema validation.

Collation

Specifies the kind of language collation to use when sorting results. See the MongoDB server manual for more information on collation.

Comment

Gets or sets the user-provided comment for the operation. See the MongoDB server manual for more information.

Hint

Gets or sets the index to use to scan for documents. See the MongoDB server manual for more information.

IsUpsert

Specifies whether the update operation performs an upsert operation if no documents match the query filter. See the MongoDB server manual for more information.

Let

Gets or sets the let document. See the MongoDB server manual for more information.

UpdateOne()UpdateMany() 方法会各自返回一个 UpdateResult 对象。UpdateResult 类型包含以下属性:

属性
说明

IsAcknowledged

Indicates whether the update operation was acknowledged by MongoDB.

IsModifiedCountAvailable

Indicates whether you can read the count of updated records on the UpdateResult.

MatchedCount

The number of documents that matched the query filter, regardless of how many were updated.

ModifiedCount

The number of documents updated by the update operation. If an updated document is identical to the original, it won't be included in this count.

UpsertedId

The ID of the document that was upserted in the database, if the driver performed an upsert.

以下代码使用 UpdateMany() 方法查找 borough 字段值为“曼哈顿”的所有文档,然后将这些文档中的 borough 值更新为“曼哈顿(北部)”。由于 IsUpsert 选项设置为 true,因此如果查询筛选器与任何现有文档都不匹配,驱动程序将插入新文档。

var filter = Builders<Restaurant>.Filter
.Eq(restaurant => restaurant.Borough, "Manhattan");
var update = Builders<Restaurant>.Update
.Set(restaurant => restaurant.Borough, "Manhattan (north)");
UpdateOptions opts = new UpdateOptions()
{
Comment = new BsonString("Borough updated for C# Driver Fundamentals"),
IsUpsert = true
};
Console.WriteLine("Updating documents...");
var result = _restaurantsCollection.UpdateMany(filter, update, opts);
Console.WriteLine($"Updated documents: {result.ModifiedCount}");
Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");
Updating documents...
Updated documents: 10259
Result acknowledged? True

注意

如果上述示例使用 UpdateOne() 方法而不是 UpdateMany(),则驱动程序将更新匹配文档中的第一个。

您可以使用 ReplaceOne() 方法在 MongoDB 中执行替换操作。此方法会删除第一个符合搜索条件的文档中的所有字段(_id 字段除外),然后将指定的字段和值插入文档。

ReplaceOne() 方法需要使用以下参数:

  • 查询筛选器文档,用于确定要替换的记录。

  • 替换文档,用于指定要插入新文档的字段和值。如果集合中的文档映射到 C# 类,则替换文档可以是此类的实例。

与更新操作一样,您可以使用 .NET/C# 驱动程序中的 Builders 类来创建查询筛选器。以下代码示例使用 Builders 创建查询筛选器,用于搜索 name 字段值为“Pizza Town”的餐厅。该代码还创建一个新的 Restaurant 对象,以替换第一个匹配的文档。

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
.Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
Id = oldId,
Name = "Mongo's Pizza",
Cuisine = "Pizza",
Address = new()
{
Street = "Pizza St",
ZipCode = "10003"
},
Borough = "Manhattan",
};
// Replaces the existing restaurant document with the new document
return _restaurantsCollection.ReplaceOne(filter, newPizzaRestaurant);

重要

_id 字段的值不可变。如果您的替换文档指定 _id 字段的值,则它必须与现有文档的 _id 值匹配。

以下代码将演示如何使用异步 ReplaceOneAsync() 方法或同步 ReplaceOne() 方法替换一个文档。

var result = await _restaurantsCollection.ReplaceOneAsync(filter, newRestaurant);
var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant);

提示

附加信息下方查找使用这些方法的可运行示例。

ReplaceOne() 方法可以选择性地采用 ReplaceOptions 对象作为附加参数,此参数表示可用来配置替换操作的选项。如果您不指定任何 ReplaceOptions 属性,则驱动程序不会自定义替换操作。

ReplaceOptions 类型允许您使用以下属性配置选项:

属性
说明

BypassDocumentValidation

Specifies whether the replace operation bypasses document validation. This lets you replace documents that don't meet the schema validation requirements, if any exist. See the MongoDB server manual for more information on schema validation.

Collation

Specifies the kind of language collation to use when sorting results. See the MongoDB server manual for more information on collation.

Comment

Gets or sets the user-provided comment for the operation. See the MongoDB server manual for more information.

Hint

Gets or sets the index to use to scan for documents. See the MongoDB server manual for more information.

IsUpsert

Specifies whether the replace operation performs an upsert operation if no documents match the query filter. See the MongoDB server manual for more information.

Let

Gets or sets the let document. See the MongoDB server manual for more information.

ReplaceOne() 方法返回 ReplaceOneResult 对象。ReplaceOneResult 类型包含以下属性:

属性
说明

IsAcknowledged

Indicates whether the replace operation was acknowledged by MongoDB.

IsModifiedCountAvailable

Indicates whether you can read the count of replaced records on the ReplaceOneResult.

MatchedCount

The number of documents that matched the query filter, regardless of whether one was replaced.

ModifiedCount

The number of documents replaced by the replace operation.

UpsertedId

The ID of the document that was upserted in the database, if the driver performed an upsert.

以下代码使用 ReplaceOne() 方法查找 name 字段值为“Pizza Town”的第一个文档,然后用名为“Food World”的新的 Restaurant 文档替换该文档。由于 IsUpsert 选项设置为 true,因此如果查询筛选器与任何现有文档都不匹配,驱动程序将插入新文档。

var filter = Builders<Restaurant>.Filter.Eq(restaurant => restaurant.Name, "Pizza Town");
Restaurant newRestaurant = new()
{
Name = "Food World",
Cuisine = "American",
Address = new BsonDocument
{
{"street", "Food St"},
{"zipcode", "10003"},
},
Borough = "Manhattan",
};
ReplaceOptions opts = new ReplaceOptions()
{
Comment = new BsonString("Restaurant replaced for .NET/C# Driver Fundamentals"),
IsUpsert = true
};
Console.WriteLine("Replacing document...");
var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant, opts);
Console.WriteLine($"Replaced documents: {result.ModifiedCount}");
Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");
Replacing document...
Replaced documents: 1
Result acknowledged? True

有关更新和替换操作的可运行示例,请参阅以下用法示例:

要了解创建查询筛选器的更多信息,请参阅指定查询指南。

要进一步了解本指南所讨论的任何方法或类型,请参阅以下 API 文档:

后退

Insert