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`	指定在没有文档与查询过滤匹配的情况下，更新操作是否执行更新或更新或插入（upsert）操作。有关更多信息，请参阅MongoDB Server手册。数据类型： `bool`
`Let`	获取或设置 let文档。有关更多信息，请参阅MongoDB Server手册。数据类型： BsonDocument

返回值

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

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