/ /

Driver C#/.NET

Docs Home

Librerías de clientes

Driver C#/.NET

Docs Home

Librerías de clientes

Driver C#/.NET

Reemplazar Documentos

Overview

En esta guía, puede aprender a utilizar el controlador .NET/C# para reemplazar documentos en una colección MongoDB.

El controlador .NET/C# proporciona la ReplaceOne() y ReplaceOneAsync(). Estos métodos eliminan todos los campos (excepto el campo _id) del primer documento que coincide con los criterios de búsqueda y, a continuación, insertan en el documento los campos y valores especificados.

Nota

Sobrecargas de métodos

Muchos de los métodos de esta página tienen múltiples sobrecargas. Los ejemplos de esta guía muestran solo una definición de cada método. Para obtener más información sobre las sobrecargas disponibles, consulte Documentación de la API.

Datos de muestra

Los ejemplos de esta guía utilizan la colección restaurants de la base de datos sample_restaurants. Los documentos de esta colección utilizan las siguientes clases Restaurant, Address y 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; }
}

Nota

Los documentos de la colección restaurants utilizan la convención de nomenclatura snake-case. Los ejemplos de esta guía utilizan un ConventionPack para deserializar los campos de la colección en notación Pascal y asignarlos a las propiedades de la clase Restaurant.

Para obtener más información sobre la serialización personalizada, consulte Serialización personalizada.

Esta colección es de los conjuntos de datos de muestra proporcionados por Atlas. Consulte Primeros pasos con el controlador .NET/C# para aprender a crear un clúster gratuito de MongoDB y cargar estos datos de muestra.

Reemplazar un documento

Para reemplazar un documento en una colección, llame al método ReplaceOne() o ReplaceOneAsync(). Estos métodos aceptan los siguientes parámetros:

Parameter	Descripción
`filter`	Un filtro de consulta que especifica el documento que se va a reemplazar. Puede usar la `Builders` clase para crear un filtro de consulta. Para obtener más información sobre los filtros de consulta, consulte el manual de MongoDB Server. Tipo de dato: FilterDefinition<TDocument>
`replacement`	Un documento de reemplazo, que especifica los campos y valores que se insertarán en el nuevo documento. Si los documentos de su colección están asignados a una clase de C#, el documento de reemplazo puede ser una instancia de esta clase. Tipo de dato: `TDocument`
`options`	Opcional. Una instancia de la `ReplaceOptions` clase que especifica la configuración para la operación de reemplazo. El valor predeterminado `null` es. Tipo de dato: Reemplazar opciones
`cancellationToken`	Opcional. Un token que puedes usar para cancelar la operación. Tipo de dato: CancellationToken

El siguiente ejemplo de código muestra cómo realizar una operación de reemplazo. El código realiza los siguientes pasos:

Crea un filtro de consulta mediante la clase Builders. El filtro busca todos los documentos donde el campo cuisine tenga el valor "Pizza".
Crea un nuevo objeto Restaurant.
Llama al método ReplaceOne() en la colección restaurants. Esta operación busca el primer documento coincidente de la colección y lo reemplaza por el documento recién creado.

Seleccione el Synchronous o la pestaña Asynchronous para ver el código correspondiente.

// 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

Los valores de los campos _id son inmutables. Si el documento de reemplazo especifica un valor para el campo _id, este debe coincidir con el valor _id del documento existente.

Si su documento de reemplazo no especifica un valor para el campo _id, puede agregar el atributo [BsonIgnoreIfDefault] al campo _id en su objeto CLR/Clase simple (POCO). Use [BsonIgnoreIfDefault] si el campo _id de su POCO es del tipo ObjectId.

El siguiente ejemplo muestra cómo agregar este atributo:

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

Personalizar la operación de reemplazo

Los métodos ReplaceOne() y ReplaceOneAsync() aceptan opcionalmente un objeto ReplaceOptions como parámetro, que representa opciones que puede utilizar para configurar la operación de reemplazo.

La clase ReplaceOptions contiene las siguientes propiedades:

Propiedad

Descripción

BypassDocumentValidation

Especifica si la operación de reemplazo omite la validación de documentos. Esto permite reemplazar documentos que no cumplen los requisitos de validación del esquema, si los hay. Consulte el manual de MongoDB Server para obtener más información sobre la validación del esquema.

Tipo de dato: bool?

Collation

Especifica el tipo de intercalación de idioma que se usará al ordenar los resultados. Consulte la sección Intercalación de esta página para obtener más información.

Tipo de dato: Intercalación

Comment

Obtiene o establece el comentario proporcionado por el usuario para la operación. Consulte el manual del servidor MongoDB para obtener más información.

Tipo de dato: Valor de Bson

Hint

Obtiene o establece el índice que se usará para buscar documentos. Consulte el manual del servidor MongoDB para obtener más información.

Tipo de dato: Valor de Bson

IsUpsert

Especifica si la operación de reemplazo realiza una operación de upsert si ningún documento coincide con el filtro de consulta. Consulte el manual de MongoDB Server para obtener más información.

Tipo de dato: bool

Sort

Determina qué documento reemplaza la operación si la consulta selecciona varios documentos, ya que la operación de reemplazo reemplaza el primer documento en el orden de clasificación especificado. Para configurar esta opción, debe crear una instancia ReplaceOptions<T> que utilice un tipo genérico que modele sus datos, como se muestra en el siguiente código:

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

Tipo de dato: SortDefinition<T>

Let

Obtiene o establece el documento let. Consulte el manual del servidor MongoDB para obtener más información.

Tipo de dato: Documento Bson

El siguiente ejemplo realiza los mismos pasos que el anterior, pero además utiliza la opción BypassDocumentValidation para omitir cualquier requisito de validación del esquema. Seleccione la pestaña Synchronous o Asynchronous para ver el código correspondiente.

// 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);

Intercalación

Para configurar la intercalación para tu operación, crea una instancia de la clase intercalación.

La siguiente tabla describe los parámetros que acepta el constructor Collation. También enumera la propiedad de clase correspondiente que se puede usar para leer el valor de cada configuración.

Parameter	Descripción	Propiedad de clase
`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`

Más información sobre la intercalación en la página Intercalación en el manual de MongoDB Server.

Valor de retorno

El método ReplaceOne() devuelve un objeto ReplaceOneResult y el método ReplaceOneAsync() devuelve un objeto Task<ReplaceOneResult>. La clase ReplaceOneResult contiene las siguientes propiedades:

Propiedad	Descripción
`IsAcknowledged`	Indica si MongoDB reconoció o no la operación de reemplazo. Tipo de dato: `bool`
`IsModifiedCountAvailable`	Indica si puede leer el recuento de registros reemplazados en `ReplaceOneResult`. Tipo de dato: `bool`
`MatchedCount`	La cantidad de documentos que coincidieron con el filtro de consulta, independientemente de si se reemplazó alguno. Tipo de dato: `long`
`ModifiedCount`	El número de documentos reemplazados por la operación de reemplazo. Tipo de dato: `long`
`UpsertedId`	El ID del documento que se insertó en la base de datos, si el controlador realizó una inserción. Tipo de dato: Valor de Bson

Información Adicional

Para obtener ejemplos ejecutables de la operación de reemplazo, consulte los siguientes ejemplos de uso:

Documentación de la API

Para obtener más información sobre cualquiera de los métodos y clases utilizados en esta página, consulte la siguiente documentación de API:

Volver

Arreglos

Delete Documents