/ /

updateOne

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提供的示例数据集。请参阅.NET/C#驱动程序入门，了解如何创建免费的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);

更新管道

您可以将一系列更新操作连接到单个聚合管道中。

要创建更新管道，请调用 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<ArrayFilterDefinition>

BypassDocumentValidation

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

数据类型： bool?

Collation

指定对结果进行排序时要使用的语言排序规则类型。有关详细信息，请参阅本页的排序规则部分。

数据类型： 排序规则

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

排序规则

要为操作配置排序规则，请创建 Collation 类的实例。

下表描述了 Collation 构造函数接受的参数。它还列出了相应的类属性，您可以使用这些属性读取每个设置的值。

Parameter	说明	类属性
`locale`	指定 Unicode 国际组件 (ICU)区域设置设置。有关支持的区域设置列表，请参阅MongoDB Server手册中的排序规则区域设置和默认参数。如果要使用简单的二进制比较，请使用 `Collation.Simple`静态属性返回`Collation` 对象，并将`locale` 设立为`"simple"` 。数据类型：`string`	`Locale`
`caseLevel`	（可选）指定是否包括大小写比较。当此参数为 `true`时，驱动程序的行为取决于`strength` 参数的值： `strengthCollationStrength.Primary` - 如果`strength` 为`CollationStrength.Secondary` ，驾驶员会比较基本字符和大小写。 — 如果为，则驾驶员会比较基本字符、变音符号、其他从节点(secondary node from replica set)差异和大小写。 — 如果为任何其他值，则忽略此参数。当此参数为`strength` `false`时，驾驶员不包括强度级别`Primary` 或`Secondary` 的大小写比较。数据类型：`boolean` 默认值：`false`	`CaseLevel`
`caseFirst`	（可选）指定三级比较期间大小写差异的排序顺序。数据类型：CollationCaseFirst 默认值：`CollationCaseFirst.Off`	`CaseFirst`
`strength`	（可选）指定要执行的比较级别，如 ICU 文档中所定义。数据类型：CollationStrength 默认值：`CollationStrength.Tertiary`	`Strength`
`numericOrdering`	（可选）指定驾驶员是否将数字字符串作为数字进行比较。如果此参数为 `true`，则驾驶员将数字字符串作为数字进行比较。示例，在比较字符串10 210210 `false`"10 " 和 "2 " 时，驾驶员会将这些值视为和，并发现更大。如果此参数为或已排除，则驾驶员会将数字字符串作为字符串进行比较。示例，在比较字符串1 "2 " 和10 "2 " 时，驾驶员一次比较一个字符。由于“”小于“”，因此驾驶员会发现“”小于“”。有关更多信息，请参阅MongoDB Server手册中的排序规则限制。数据类型： `boolean` 默认值：`false`	`NumericOrdering`
`alternate`	（可选）指定驾驶员是否将空格和标点符号视为基本字符以进行比较。数据类型：CollationAlternate 默认值：`CollationAlternate.NonIgnorable` （空格和标点符号被视为基本字符）	`Alternate`
`maxVariable`	（可选）指定当 `alternate`参数为`CollationAlternate.Shifted` 时驾驶员认为哪些字符可忽略。数据类型：CollationMaxVariable 默认值：`CollationMaxVariable.Punctuation` （驾驶员忽略标点符号和空格）	`MaxVariable`
`normalization`	（可选）指定驾驶员是否根据需要对文本进行规范化。大多数文本不需要规范化。有关规范化的更多信息，请参阅 ICU 文档。数据类型： `boolean` 默认值：`false`	`Normalization`
`backwards`	（可选）指定包含变音符号的字符串是否从后往前排序。数据类型： `boolean` 默认值：`false`	`Backwards`

有关排序规则的更多信息，请参阅MongoDB Server手册中的排序规则页面。

返回值

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

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