/ /

UpdateOne

Nesta página

Visão geral
Dados de amostra
Métodos e parâmetros
Atualizar vários valores
Definições de atualização combinadas
Atualizar pipelines
Opções de configuração
Valor de retorno
Informações adicionais
Documentação da API

Visão geral

Neste guia, você pode aprender como usar o Driver MongoDB .NET/C# para atualizar valores em um único documento.

O driver .NET/C# fornece os seguintes métodos para atualizar valores:

UpdateOne(): Atualiza um ou mais campos em um único documento.
UpdateOneAsync(): A versão assíncrona do UpdateOne().

As seções a seguir descrevem esses métodos em mais detalhes.

Observação

Sobrecargas de método

Muitos dos métodos nesta página têm múltiplas sobrecargas. Os exemplos deste guia mostram apenas uma definição de cada método. Para obter mais informações sobre as sobrecargas disponíveis,consulte a documentação da API.

Dados de amostra

Os exemplos neste guia utilizam a coleção do restaurants a partir do banco de dados do sample_restaurants. Os documentos nesta coleção usam as seguintes classes Restaurant, Address e GradeEntry como modelos:

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

Observação

Os documentos na collection restaurants usam a convenção de nomenclatura snake-case. Os exemplos neste guia usam um ConventionPack para desserializar os campos na coleção em maiúsculas e minúsculas Pascal e mapeá-los para as propriedades na classe Restaurant .

Para saber mais sobre serialização personalizada, consulte Serialização personalizada.

Essa coleção é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte o Quick Start para saber como criar um cluster MongoDB gratuito e carregar esses dados de amostra.

Métodos e parâmetros

Os métodos UpdateOne() e UpdateOneAsync() aceitam os seguintes parâmetros:

Parâmetro	Descrição
`filter`	Uma instância da classe `FilterDefinition` que especifica o documento a ser atualizado. Para saber como criar um filtro de query, consulte Especificar uma query. Tipo de Dados: FilterDefinition
`update`	Uma instância da `UpdateDefinition` classe. Este objeto especifica o tipo de operação de atualização, os campos a serem atualizados e o novo valor para cada campo. Para saber como criar um `UpdateDefinition` objeto, consulte Atualizar campos em um documento e Atualizar arrays em um documento. Tipo de Dados: UpdateDefinition<TDocument>
`options`	Opcional. Uma instância da classe `UpdateOptions` que especifica a configuração para a operação de atualização. O valor padrão é `null`. Para obter uma lista de opções disponíveis, consulte Opções de configuração. Tipo de Dados: UpdateOptions
`cancellationToken`	Opcional. Um token que você pode usar para cancelar a operação. Tipo de Dados: `CancellationToken`

Atualizar vários valores

Os métodos UpdateOne() e UpdateOneAsync() aceitam somente um objeto UpdateDefinition. As seções a seguir descrevem como atualizar vários valores em uma única chamada de método.

Definições de atualização combinadas

O método Builders.Update.Combine() permite combinar vários objetos UpdateDefinition. Este método aceita o seguinte parâmetro:

Parâmetro	Descrição
`updates`	Uma array de definições de atualizações para combinar. Tipo de Dados: `UpdateDefinition<TDocument>[]`

O método Combine() retorna um único objeto UpdateDefinition que define múltiplas operações de atualização.

O seguinte exemplo de código utiliza o Combine() método para combinar uma operação $set e uma operação $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);

Atualizar pipelines

Se seu aplicação se conectar ao MongoDB Server 4.2 ou posterior, você poderá participar de uma sequência de operações de atualização em um único pipeline de agregação .

Para criar um pipeline de atualização, chame o método Builders.Update.Pipeline(). Este método aceita o seguinte parâmetro:

Parâmetro	Descrição
`pipeline`	Uma instância `PipelineDefinition` que representa o pipeline de atualização. Para criar um objeto `PipelineDefinition`, crie um documento BSON para cada operação de atualização que você deseja executar e, em seguida, passe esses documentos para o método `PipelineDefinition.Create()`. Tipo de Dados: `PipelineDefinition<TDocument, TDocument>`

O método Pipeline() retorna um único objeto UpdateDefinition que define vários estágios de agregação .

O seguinte exemplo de código utiliza o Pipeline() método para combinar uma operação $set e uma operação $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);

Observação

Operações não suportadas

Os pipelines de atualização não suportam todas as operações de atualização, mas suportam determinados estágios de agregação não encontrados em outras definições de atualização. Para obter uma lista de operações de atualização suportadas por pipelines,consulte Atualizações com aggregation pipeline no manual do MongoDB Server .

Opções de configuração

Os métodos UpdateOne() e UpdateOneAsync() aceitam opcionalmente um objeto UpdateOptions como parâmetro. Você pode utilizar este argumento para configurar a operação de atualização.

A classe UpdateOptions contém as seguintes propriedades:

Propriedade	Descrição
`ArrayFilters`	Especifica quais elementos de array modificar para uma operação de atualização em um campo de array. Consulte o manual do servidor do MongoDB para obter mais informações. Tipo de dados: IEnumerable
`BypassDocumentValidation`	Especifica se a operação de atualização ignora a validação do documento. Isso permite atualizar documentos que não atendam aos requisitos de validação do esquema, se houver algum. Consulte o manual do servidor do MongoDB para obter mais informações sobre validação de esquema. Tipo de Dados: `bool?`
`Collation`	Especifica o tipo de agrupamento de linguagem a ser usado ao classificar os resultados. Consulte o manual do servidor do MongoDB para obter mais informações sobre agrupamento. Tipo de Dados: Agrupamentos
`Comment`	Obtém ou define o comentário fornecido pelo usuário para a operação. Consulte o manual do servidor do MongoDB para obter mais informações. Tipo de Dados: BsonValor
`Hint`	Obtém ou define o índice a ser usado para procurar documentos. Consulte o manual do servidor do MongoDB para obter mais informações. Tipo de Dados: BsonValor
`IsUpsert`	Especifica se a operação de atualização executa uma operação upsert se nenhum documento corresponder ao filtro de queries. Consulte o manual do servidor do MongoDB para obter mais informações. Tipo de Dados: `bool`
`Let`	Obtém ou define o documento de permissão. Consulte o manual do servidor do MongoDB para obter mais informações. Tipo de Dados: Documento BSON

Valor de retorno

O método UpdateOne() retorna um UpdateResult e o método UpdateOneAsync() retorna um objeto Task<UpdateResult>. A classe UpdateResult contém as seguintes propriedades:

Propriedade	Descrição
`IsAcknowledged`	Indica se a operação de atualização foi reconhecida pelo MongoDB. Tipo de Dados: `bool`
`IsModifiedCountAvailable`	Indica se você pode ler a contagem de registros de atualização no `UpdateResult`. Tipo de Dados: `bool`
`MatchedCount`	O número de documentos que corresponderam ao filtro de query, independentemente de um ter sido atualizado. Tipo de Dados: `long`
`ModifiedCount`	O número de documentos atualizados pela operação de atualização. Tipo de Dados: `long`
`UpsertedId`	O ID do documento que foi atualizado no banco de dados, se o driver executou um upsert. Tipo de Dados: BsonValor

Informações adicionais

Para obter exemplos executáveis das operações de atualização, consulte a página Atualizar um documento.

Para saber mais sobre como criar filtros de queries, consulte o guia Especifique uma consulta.

Documentação da API

Para obter mais informações sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Insert

Campos