/ /

Reemplazar Documentos

Overview

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

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

Nota

Sobrecargas de métodos

Muchos de los métodos en esta página tienen varias 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, se puede consultar la 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 aprender más sobre la serialización personalizada, consultar 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, llama al método ReplaceOne() o ReplaceOneAsync(). Estos métodos aceptan los siguientes parámetros:

Parameter	Descripción
`filter`	Un filtro de query que especifica el documento a reemplazar. Puede usar la clase `Builders` para crear un filtro de query. Para obtener más información sobre los filtros de query, consulta el manual del servidor de MongoDB. Tipo de dato: FilterDefinition<TDocument>
`replacement`	Un documento de reemplazo que especifica los campos y valores que se deben insertar en el nuevo documento. Si los documentos de tu colección se asignan 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 clase `ReplaceOptions` que especifica la configuración para la operación de reemplazo. El valor por defecto es `null`. Tipo de dato: ReplaceOptions
`cancellationToken`	opcional. Un token que puedes usar para cancelar la operación. Tipo de dato: CancellationToken

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

Crea un filtro de query utilizando la clase Builders. El filtro coincide con todos los documentos donde el campo cuisine tiene el valor "Pizza".
Crea un nuevo objeto Restaurant.
Llama al método ReplaceOne() en la colección restaurants. Esta operación encuentra el primer documento que coincide en la colección y lo reemplaza con el nuevo documento creado.

Selecciona 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",
};
// 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 tu documento de reemplazo especifica un valor para el campo _id, este debe coincidir con el valor _id del documento existente.

Si el documento de reemplazo no especifica un valor para el campo _id, puedes agregar el atributo [BsonIgnoreIfDefault] al campo _id en tu objeto común de CLR/clase (POCO). Utiliza [BsonIgnoreIfDefault] si el campo _id de tu 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 como parámetro un objeto ReplaceOptions, que representa opciones que puede usar para configurar la operación de sustitución.

La clase ReplaceOptions contiene las siguientes propiedades:

Propiedad

Descripción

BypassDocumentValidation

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

Tipo de dato: bool?

Collation

Especifica el tipo de intercalación de lenguaje que se debe usar al clasificar 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. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonValue

Hint

Obtiene o establece el índice que se utilizará para buscar documentos. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonValue

IsUpsert

Especifica si la operación de reemplazo realiza una operación inserción si ningún documentos coincide con el filtro de query. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: bool

Sort

Determina qué documento reemplaza la operación si la query 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, debes instanciar una instancia de ReplaceOptions<T> que use un tipo genérico que modele tus 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. Para obtener más información, consulta el manual de MongoDB Server.

Tipo de dato: BsonDocument

El siguiente ejemplo realiza los mismos pasos que el ejemplo anterior, pero también utiliza la opción BypassDocumentValidation para omitir cualquier requisito de validación del esquema. Selecciona 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`	Especifica la configuración regional de Componentes Internacionales para Unicode (ICU). Para obtener una lista de las configuraciones regionales compatibles, consulte Configuraciones regionales de intercalación y parámetros predeterminados en el Manual del servidor MongoDB. Si desea utilizar una comparación binaria simple, utilice la `Collation.Simple` propiedad estática para devolver un `Collation` objeto con establecido `locale` `"simple"`en. Tipo de datos: `string`	`Locale`
`caseLevel`	(Opcional) Especifica si se debe incluir la comparación de mayúsculas y minúsculas. Cuando este argumento `true` es, el comportamiento del controlador depende del valor del `strength` argumento: - Si `strength` `CollationStrength.Primary`es, el controlador compara caracteres base y mayúsculas y minúsculas. - Si `strength` `CollationStrength.Secondary`es, el controlador compara caracteres base, diacríticos, otras diferencias secundarias y mayúsculas y minúsculas. - Si `strength` es cualquier otro valor, este argumento se ignora. Cuando este argumento `false` es, el controlador no incluye la comparación de mayúsculas y minúsculas en el nivel `Primary` de fuerza `Secondary` o. Tipo `boolean` de datos: Predeterminado: `false`	`CaseLevel`
`caseFirst`	(Opcional) Especifica el orden de clasificación de las diferencias de mayúsculas y minúsculas durante las comparaciones de nivel terciario. Tipo de datos: CollationCaseFirst Valor predeterminado: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Opcional) Especifica el nivel de comparación a realizar, tal como se define en la documentación de la UCI. Tipo de datos: CollationStrength Valor predeterminado: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica si el controlador compara las cadenas numéricas como números. Si este argumento `true` es, el controlador compara las cadenas numéricas como números. Por ejemplo, al comparar las cadenas "10" y "2", el controlador trata los valores como 10 2y, y encuentra 10 que es mayor. Si este argumento es `false` o se excluye, el controlador compara las cadenas numéricas como cadenas. Por ejemplo, al comparar las cadenas "10" y "2", el controlador compara un carácter a la vez. Como "1" es menor que "2", el controlador encuentra10que " " es menor que "2". Para obtener más información, consulte Restricciones de intercalación en el manual del servidor MongoDB. Tipo de datos: `boolean` Predeterminado: `false`	`NumericOrdering`
`alternate`	(Opcional) Especifica si el controlador considera los espacios en blanco y la puntuación como caracteres base para fines de comparación. Tipo de datos: CollationAlternate Valor predeterminado: `CollationAlternate.NonIgnorable` (los espacios y la puntuación se consideran caracteres base)	`Alternate`
`maxVariable`	(Opcional) Especifica qué caracteres considera el controlador como ignorables cuando el `alternate` argumento `CollationAlternate.Shifted` es. Tipo de datos: CollationMaxVariable Valor predeterminado: `CollationMaxVariable.Punctuation` (el controlador ignora la puntuación y los espacios)	`MaxVariable`
`normalization`	(Opcional) Especifica si el controlador normaliza el texto según sea necesario. La mayoría del texto no requiere normalización. Para obtener más información sobre la normalización, consulte la documentación de ICU. Tipo de datos: `boolean` Predeterminado: `false`	`Normalization`
`backwards`	(Opcional) Especifica si las cadenas que contienen diacríticos se ordenan desde el final de la cadena hacia el principio. Tipo de datos: `boolean` Valor predeterminado: `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() retorna un objeto ReplaceOneResult, y el método ReplaceOneAsync() retorna 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 puedes leer la cuenta de los registros reemplazados en el `ReplaceOneResult`. Tipo de dato: `bool`
`MatchedCount`	La cantidad de documentos que coincidieron con el filtro de query, independientemente de si uno fue reemplazado. Tipo de dato: `long`
`ModifiedCount`	La cantidad de documentos reemplazados por la operación de reemplazo. Tipo de dato: `long`
`UpsertedId`	El ID del documento que fue insertado o actualizado en la base de datos, si el driver realizó una actualización o inserción. Tipo de dato: BsonValue

Información Adicional

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

Documentación de la API

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

Volver

Arreglos

Delete Documents