/ /

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`	Especifica a locale Componentes internacionais para Unicode (ICU). Para obter uma lista de localidades suportadas, consulte Localidades de Agrupamento e Parâmetros Padrão no Manual do MongoDB Server . Se você quiser usar a comparação binária simples, use a `Collation.Simple` propriedade estática para retornar um `Collation` objeto com o `locale` definido `"simple"` como. Tipo de dados: `string`	`Locale`
`caseLevel`	(Opcional) Especifica se incluir comparação de caso. Quando esse argumento `true` é, o comportamento do driver depende do valor do `strength` argumento: - Se `strength` `CollationStrength.Primary`for, o driver compara caracteres básicos e maiúsculas e minúsculas. - `strength` Se `CollationStrength.Secondary` for, o driver compara caracteres básicos, diacríticos, outras diferenças secundárias e maiúsculas e minúsculas. - Se `strength` for qualquer outro valor, esse argumento será ignorado. Quando esse argumento `false` é, o driver não inclui comparação de caso no nível de força `Primary` `Secondary`ou. Tipo de Dados: `boolean` Padrão: `false`	`CaseLevel`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante as comparações de nível terciário. Tipo de dados: CollationCaseFirst padrão: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Opcional) Especifica o nível de comparação a ser executado, conforme definido na documentação da ICU. Tipo de Dados: CollationStrength Padrão: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se esse argumento `true` for, o driver compara strings numéricas como números. Por exemplo, ao comparar as strings "10" e "2", o driver trata os valores como 10 e 2 e considera 10 maior. Se esse argumento for `false` ou excluído, o driver compara cadeias de caracteres numéricas como cadeias de caracteres. Por exemplo, ao comparar as strings "10" e "2", o driver compara um caractere de cada vez. Como "1" é menor que "2", o driver acha que "10" é menor que "2". Para obter mais informações, consulte Restrições de agrupamento no manual do MongoDB Server . Tipo de dados: `boolean` Padrão: `false`	`NumericOrdering`
`alternate`	(Opcional) Especifica se o driver considera o espaço em branco e a pontuação como caracteres básicos para fins de comparação. Tipo de dados: CollationAlterne padrão: `CollationAlternate.NonIgnorable` (espaços e pontuação são considerados caracteres básicos)	`Alternate`
`maxVariable`	(Opcional) Especifica quais caracteres o driver considera ignoráveis quando o `alternate` argumento `CollationAlternate.Shifted` é. Tipo de Dados: CollationMaxVariable Padrão: `CollationMaxVariable.Punctuation` (o driver ignora pontuação e espaços)	`MaxVariable`
`normalization`	(Opcional) Especifica se o driver normaliza o texto conforme necessário. A maioria dos textos não exige normalização. Para obter mais informações sobre normalização, consulte a documentação da ICU. Tipo de dados: `boolean` Padrão: `false`	`Normalization`
`backwards`	(Opcional) Especifica se as strings contendo diacríticos são classificadas da parte de trás da string para a frente. Tipo de dados: `boolean` Padrão: `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