Substituir documentos

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 collection é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte a Introdução ao driver .NET/C# para saber como criar um cluster MongoDB gratuito e carregar esses dados de exemplo.

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 classe `Builders` 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 instância da classe `ReplaceOptions` 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");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    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");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{   
    Id = oldId,
    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.

Se o seu documento de substituição não especificar um valor para o campo _id, você poderá adicionar o atributo [BsonIgnoreIfDefault] ao campo _id no seu Objeto de classe/CLR antigo (POCO). Use [BsonIgnoreIfDefault] se o campo _id em seu POCO for do tipo ObjectId.

O exemplo a seguir mostra como adicionar este atributo:

public class Restaurant
{
    [BsonIgnoreIfDefault]
    public ObjectId Id { get; set; }
    // Other properties
}

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 servidor do MongoDB 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 a seção Agrupamento desta página para obter mais informações.

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 substituiçã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

Sort

Determina qual documento a operação substitui se a query selecionar vários documentos, pois a operação de substituição substitui o primeiro documento na ordem de classificação especificada. Para definir essa opção, você deve instanciar uma instância ReplaceOptions<T> que usa um tipo genérico que modela seus dados, conforme mostrado no código a seguir:

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

Tipo de Dados: SortDefinition<T>

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

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");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    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");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    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);

Agrupamentos

Para configurar o agrupamento para sua operação, crie uma instância da classe Agrupamento.

A tabela seguinte descreve os parâmetros que o construtor do Collation aceita. Ela também lista a propriedade de classe correspondente que você pode usar para ler o valor de cada configuração.

Parâmetro	Descrição	Propriedade de classe
`locale`	Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server Manual. If you want to use simple binary comparison, use the `Collation.Simple` static property to return a `Collation` object with the `locale` set to `"simple"`. Data Type: `string`	`Locale`
`caseLevel`	(Optional) Specifies whether to include case comparison. When this argument is `true`, the driver's behavior depends on the value of the `strength` argument: - If `strength` is `CollationStrength.Primary`, the driver compares base characters and case. - If `strength` is `CollationStrength.Secondary`, the driver compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this argument is ignored. When this argument is `false`, the driver doesn't include case comparison at strength level `Primary` or `Secondary`. Data Type: `boolean` Default: `false`	`CaseLevel`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: CollationCaseFirst Default: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: CollationStrength Default: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Optional) Specifies whether the driver compares numeric strings as numbers. If this argument is `true`, the driver compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the driver treats the values as 10 and 2, and finds 10 to be greater. If this argument is `false` or excluded, the driver compares numeric strings as strings. For example, when comparing the strings "10" and "2", the driver compares one character at a time. Because "1" is less than "2", the driver finds "10" to be less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `boolean` Default: `false`	`NumericOrdering`
`alternate`	(Optional) Specifies whether the driver considers whitespace and punctuation as base characters for purposes of comparison. Data Type: CollationAlternate Default: `CollationAlternate.NonIgnorable` (spaces and punctuation are considered base characters)	`Alternate`
`maxVariable`	(Optional) Specifies which characters the driver considers ignorable when the `alternate` argument is `CollationAlternate.Shifted`. Data Type: CollationMaxVariable Default: `CollationMaxVariable.Punctuation` (the driver ignores punctuation and spaces)	`MaxVariable`
`normalization`	(Optional) Specifies whether the driver normalizes text as needed. Most text doesn't require normalization. For more information about normalization, see the ICU documentation. Data Type: `boolean` Default: `false`	`Normalization`
`backwards`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `boolean` Default: `false`	`Backwards`

Para obter mais informações sobre agrupamento, consulte a página Agrupamento no manual do MongoDB Server .

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

Informações adicionais

Para obter exemplos executáveis da operação de substituição, consulte os seguintes exemplos de uso:

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

Exclua documentos