Substituir documentos

Nesta página

Visão geral

Dados de amostra
Substituir um documento
Personalizar a operação de substituição
Valor de retorno
Documentação da API

Visão geral

Neste guia, você pode aprender como usar o Driver .NET/C# para substituir documentos em uma coleção MongoDB .

O driver .NET/C# fornece os métodos ReplaceOne() e ReplaceOneAsync(). Esses métodos removem todos os campos (exceto o campo _id ) do primeiro documento que corresponde aos critérios de pesquisa e, em seguida, inserem os campos e valores especificados no documento.

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.

Substituir um documento

Para substituir um documento em uma coleção, chame o método ReplaceOne() ou ReplaceOneAsync(). Esses métodos aceitam os seguintes parâmetros:

Parâmetro	Descrição
`filter`	Um filtro de query que especifica o documento a ser substituído. Você pode utilizar a `Builders` classe para criar um filtro de query. Para obter mais informações sobre filtros de query, consulte o manual do MongoDB Server . Tipo de dados: FilterDefinition<TDocument>
`replacement`	Um documento de substituição, que especifica os campos e valores a serem inseridos no novo documento. Se os documentos em sua coleção forem mapeados para uma classe C#, o documento de substituição poderá ser uma instância dessa classe. Tipo de dados: `TDocument`
`options`	Opcional. Uma `ReplaceOptions` instância da classe que especifica a configuração para a operação de substituição. O valor padrão `null` é. Tipo de dados: ReplaceOptions
`cancellationToken`	Opcional. Um token que você pode usar para cancelar a operação. Tipo de dados : CancellationToken

O seguinte exemplo de código demonstra como executar uma operação de substituição. O código executa as seguintes etapas:

Cria um filtro de query usando a classe Builders . O filtro corresponde a todos os documentos onde o campo cuisine tem o valor "Pizza".
Cria um novo objeto Restaurant .
Chama o método ReplaceOne() na coleção restaurants. Esta operação localiza o primeiro documento correspondente na coleção e o substitui pelo documento recém-criado.

Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

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

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
// Asynchronously replaces the existing restaurant document with the new document
return await _restaurantsCollection.ReplaceOneAsync(filter, newPizzaRestaurant);

Importante

Os valores dos campos _id são imutáveis. Se o documento de substituição especificar um valor para o campo _id, ele deverá corresponder ao valor _id do documento existente.

Personalizar a operação de substituição

Os métodos ReplaceOne() e ReplaceOneAsync() aceitam opcionalmente um objeto ReplaceOptions como parâmetro, que representa as opções que você pode usar para configurar a operação de substituição.

A classe ReplaceOptions contém as seguintes propriedades:

Propriedade	Descrição
`BypassDocumentValidation`	Especifica se a operação de substituição ignora a validação do documento . Isso permite substituir documentos que não atendem aos requisitos de validação de esquema , se houver. Consulte o manual do MongoDB Server para obter mais informações sobre validação de esquema. Tipo de dados: `bool?`
`Collation`	Especifica o tipo de agrupamento de idiomas a ser usado ao classificar os resultados. Consulte o manual do MongoDB Server 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 MongoDB Server para obter mais informações. Tipo de dados: BsonValor
`Hint`	Obtém ou define o índice a ser usado para digitalizar documentos. Consulte o manual do MongoDB Server para obter mais informações. Tipo de dados: BsonValor
`IsUpsert`	Especifica se a operação de substituição executará uma operação de upsert se nenhum documento corresponder ao filtro de consulta. Consulte o manual do MongoDB Server para obter mais informações. Tipo de dados: `bool`
`Let`	Obtém ou define o documento let . Consulte o manual do MongoDB Server para obter mais informações. Tipo de dados: Documento BSON

O exemplo a seguir executa as mesmas etapas do exemplo anterior, mas também usa a opção BypassDocumentValidation para ignorar quaisquer requisitos de validação de esquema . Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

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

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
var options = new ReplaceOptions
{
    BypassDocumentValidation = true
};
// Asynchronously replaces the existing restaurant document with the new document
return await _restaurantsCollection.ReplaceOneAsync(filter, newPizzaRestaurant, options);

Valor de retorno

O método ReplaceOne() retorna um objeto ReplaceOneResult e o método ReplaceOneAsync() retorna um objeto Task<ReplaceOneResult>. A classe ReplaceOneResult contém as seguintes propriedades:

Propriedade	Descrição
`IsAcknowledged`	Indica se a operação de substituição foi reconhecida pelo MongoDB. Tipo de dados: `bool`
`IsModifiedCountAvailable`	Indica se você pode ler a contagem de registros substituídos no `ReplaceOneResult`. Tipo de dados: `bool`
`MatchedCount`	O número de documentos que corresponderam ao filtro de queries, independente de algum ter sido substituído. Tipo de dados: `long`
`ModifiedCount`	O número de documentos substituídos pela operação de substituiçã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

Documentação da API

Para saber mais sobre qualquer um dos métodos e classes usados nesta página, consulte a seguinte documentação da API:

Voltar

arrays

Excluir