updateOne

在此页面上

Overview

样本数据
方法和参数
更新多个值
组合更新定义
更新管道
配置选项
返回值
更多信息
API 文档

Overview

在本指南中，您可以学习；了解如何使用MongoDB .NET/ C#驱动程序更新单个文档中的值。

.NET/ C#驱动程序提供以下方法来更新值：

UpdateOne()：更新单个文档中的一个或多个字段。
UpdateOneAsync()：UpdateOne() 的异步版本。

以下部分更详细地描述了这些方法。

注意

方法重载

此页面上的许多方法都有多个重载。本指南中的示例仅显示每种方法的一个定义。有关可用重载的更多信息，请参阅 API文档。

样本数据

本指南中的示例使用 sample_restaurants 数据库中的 restaurants 集合。此集合中的文档使用以下 Restaurant、Address 和 GradeEntry 类作为模型：

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 集群并加载这些示例数据。

方法和参数

UpdateOne() 和 UpdateOneAsync() 方法接受以下参数：

Parameter	说明
`filter`	`FilterDefinition` 类的实例，用于指定要更新的文档。要学习；了解如何创建查询过滤，请参阅指定查询。数据类型： FilterDefinition
`update`	`UpdateDefinition` 类的一个实例。该对象指定更新操作的类型、要更新的字段以及每个字段的新值。要学习；了解如何创建 `UpdateDefinition`对象，请参阅更新一个文档中的字段和更新一个文档中的数组。数据类型： UpdateDefinition<TDocument>
`options`	可选。指定更新操作配置的 `UpdateOptions` 类的实例。默认值为 `null`。有关可用选项的列表，请参阅配置选项。数据类型： UpdateOptions
`cancellationToken`	可选。可用于取消操作的令牌。数据类型：`CancellationToken`

更新多个值

UpdateOne() 和 UpdateOneAsync() 方法只接受一个 UpdateDefinition对象。以下部分介绍如何在单个方法调用中更新多个值。

组合更新定义

Builders.Update.Combine() 方法允许您组合多个 UpdateDefinition 对象。此方法接受以下参数：

Parameter	说明
`updates`	要组合的更新定义的大量。数据类型： `UpdateDefinition<TDocument>[]`

Combine() 方法返回定义多个更新操作的单个 UpdateDefinition对象。

以下代码示例使用Combine() 方法来组合 $ 设立操作和 $unset 操作：

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
_restaurantsCollection.UpdateOne(filter, combinedUpdate);

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var combinedUpdate = Builders<Restaurant>.Update.Combine(
    Builders<Restaurant>.Update.Set("cuisine", "French"),
    Builders<Restaurant>.Update.Unset("borough")
);
await _restaurantsCollection.UpdateOneAsync(filter, combinedUpdate);

更新管道

如果您的应用程序连接到MongoDB Server4.2 或更高版本，则可以将一系列更新操作联接到单个聚合管道中。

要创建更新管道，请调用 Builders.Update.Pipeline() 方法。此方法接受以下参数：

Parameter	说明
`pipeline`	代表更新管道的 `PipelineDefinition`实例。要创建 `PipelineDefinition`对象，请为要执行的每个更新操作创建一个BSON文档，然后将这些文档传递给 `PipelineDefinition.Create()` 方法。数据类型： `PipelineDefinition<TDocument, TDocument>`

Pipeline() 方法返回定义多个聚合阶段的单个 UpdateDefinition对象。

以下代码示例使用Pipeline() 方法来组合 $ 设立操作和 $unset 操作：

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
_restaurantsCollection.UpdateOne(filter, updatePipeline);

var filter = Builders<Restaurant>.Filter
    .Eq("name", "Downtown Deli");
var updatePipeline = Builders<Restaurant>.Update.Pipeline(
    PipelineDefinition<Restaurant, Restaurant>.Create(
        new BsonDocument("$set", new BsonDocument("cuisine", "French")),
        new BsonDocument("$unset", "borough")
    )
);
await _restaurantsCollection.UpdateOneAsync(filter, updatePipeline);

注意

不支持的操作

更新管道不支持所有更新操作，但它们支持其他更新定义中未找到的某些聚合阶段。有关管道支持的更新操作列表，请参阅MongoDB Server手册中的使用聚合管道进行更新。

配置选项

UpdateOne() 和 UpdateOneAsync() 方法可以选择接受 UpdateOptions对象作为参数。您可以使用此参数来配置更新操作。

UpdateOptions 类包含以下属性：

属性

说明

ArrayFilters

指定针对数组字段的更新操作时要修改的数组元素。有关更多信息，请参阅 MongoDB Server 手册。

数据类型：IEnumerable

BypassDocumentValidation

指定更新操作是否绕过文档验证。这使您可以更新不满足模式验证要求的文档（如存在）。有关模式验证的更多信息，请参阅 MongoDB Server 手册。

数据类型： bool?

Collation

指定排序结果时使用的语言集合类型。有关集合的更多信息，请参阅 MongoDB Server 手册。

数据类型： 排序规则

Comment

获取或设置用户提供的操作注释。有关更多信息，请参阅 MongoDB Server 手册。

数据类型： BsonValue

Hint

获取或设置用于扫描文档的索引。有关更多信息，请参阅 MongoDB Server 手册。

数据类型： BsonValue

IsUpsert

指定如果没有文档与查询筛选条件匹配，更新操作是否执行更新或插入操作。有关更多信息，请参阅 MongoDB Server 手册。

数据类型： bool

Sort

如果查询选择了多个文档，则确定操作更新哪个文档，因为更新操作会按指定的排序顺序更新第一个文档。要设立此选项，您必须实例化一个 UpdateOptions<T>实例，该实例使用对数据进行建模的泛型类型，如以下代码所示：

var options = new UpdateOptions<Restaurant>
{
  Sort = Builders<Restaurant>.Sort.Ascending(r => r.Name)
};

数据类型： SortDefinition<T>

Let

获取或设置 let 文档。有关更多信息，请参阅 MongoDB Server 手册。

数据类型： BsonDocument

返回值

UpdateOne() 方法返回 UpdateResult，UpdateOneAsync() 方法返回 Task<UpdateResult>对象。 UpdateResult 类包含以下属性：

属性	说明
`IsAcknowledged`	指示更新操作是否由 MongoDB 确认。数据类型： `bool`
`IsModifiedCountAvailable`	指示您是否可以读取 `UpdateResult` 上的更新记录计数。数据类型： `bool`
`MatchedCount`	与查询过滤匹配的文档数量，无论文档是否已更新。数据类型： `long`
`ModifiedCount`	通过更新操作更新的文档数量。数据类型： `long`
`UpsertedId`	如果驱动程序执行了更新或插入，则在数据库中更新或插入的文档的 ID。数据类型： BsonValue