/ /

Operaciones por lotes en transacciones

Overview

En esta guía, puedes aprender a utilizar el controlador MongoDB .NET/C# para ejecutar transacciones. Las transacciones permiten ejecutar una serie de operaciones que no modifican ningún dato hasta que se confirme la transacción. Si alguna operación en la transacción devuelve un error, el controlador cancela la transacción y descarta todos los cambios de datos antes de que lleguen a ser visibles.

MongoDB garantiza que los datos involucrados en sus operaciones de transacción se mantendrán coherentes, incluso si las operaciones encuentran errores inesperados.

Sesiones

En MongoDB, las transacciones se ejecutan dentro de sesiones lógicas. Una sesión es un agrupamiento de operaciones relacionadas de lectura o escritura que se pretende ejecutar en secuencia. Las sesiones permiten la coherencia causal para un grupo de operaciones o te permiten ejecutar operaciones en una transacción ACID.

Cuando uses el controlador .NET/C#, puedes crear una nueva sesión a partir de una instancia MongoClient como un tipo IClientSession. Recomendamos reutilizar tu cliente para múltiples sesiones y transacciones en lugar de instanciar un nuevo cliente cada vez.

El siguiente ejemplo muestra cómo crear una sesión llamando al método StartSession():

var client = new MongoClient("mongodb://localhost:27017");
var session = client.StartSession();

Advertencia

Utiliza un IClientSession únicamente con el MongoClient (o el MongoDatabase o MongoCollection asociado) que lo haya creado. El uso de un IClientSession con un MongoClient diferente provoca errores de operación.

Opciones de sesión de cliente

Puedes personalizar el comportamiento de tu sesión pasando una instancia de la clase ClientSessionOptions al método StartSession(). La siguiente tabla describe las propiedades que puede definir en un objeto ClientSessionOptions:

Propiedad	Descripción
`CausalConsistency`	Especifica si la sesión es causalmente coherente. En una sesión causalmente coherente, el driver ejecuta las operaciones en el orden en que se emitieron. Para obtener más información, consulte la coherencia causal. Tipo de dato: `boolean` Por defecto: `true`
`DefaultTransactionOptions`	Especifica las opciones de transacción predeterminadas para la sesión. Esto incluye eltiempo máximo de confirmación, la prioridad de lectura, la preferencia de lectura y la prioridad de escritura. Tipo de datos: TransactionOptions. Valor predeterminado: `null`
`Snapshot`	Especifica si el controlador realiza lecturas de instantáneas. Para obtener más información sobre las lecturas de instantáneas, consulte la sección "Instantánea" del manual del servidor MongoDB. Tipo de datos: `boolean` Predeterminado: `false`
`SnapshotTime`	Especifica la hora del clúster en la que el controlador lee todos los datos de la sesión. Debe establecer `Snapshot` a `true` al configurar esta propiedad. Para obtener más información, consulte la sección "Instantánea" de Read Concern en el manual del servidor MongoDB. Tipo de datos: BsonTimestamp. Valor predeterminado:. `null`

La propiedad DefaultTransactionOptions acepta una instancia de la clase TransactionOptions. La siguiente tabla describe las propiedades que se pueden establecer en un objeto TransactionOptions:

Propiedad	Descripción
`MaxCommitTime`	Tiempo máximo que `commitTransaction` puede ejecutarse un único comando. Si la confirmación supera este límite, MongoDB Server devuelve un `MaxTimeMSExpired` error y no confirma los cambios en la transacción. El controlador no vuelve a intentar la confirmación después de este error. Si omite esta propiedad, MongoDB Server aplica el límite de tiempo de ejecución de transacción predeterminado. Tipo `TimeSpan?` de datos: Predeterminado: `null`
`ReadConcern`	Preocupación de lectura para cada transacción en la sesión. Para obtener más información, consulte Preocupación de lectura en el manual del servidor MongoDB. Si omite esta propiedad, las transacciones usarán la preocupación de lectura a nivel de sesión, si la ha configurado. Si también omite la preocupación de lectura a nivel de sesión, las transacciones usarán la preocupación de lectura a nivel de cliente. Tipo de datos:ReadConcern Valor predeterminado:`null`
`ReadPreference`	Preferencia de lectura para cada transacción en la sesión. Para obtener más información, consulte Preferencia de lectura en el manual del servidor MongoDB. Si omite esta propiedad, las transacciones usarán la preferencia de lectura a nivel de sesión, si la ha configurado. Si también omite la preferencia de lectura a nivel de sesión, las transacciones usarán la preferencia de lectura a nivel de cliente. Tipo de datos:ReadPreference Valor predeterminado:`null`
`WriteConcern`	Consentimiento de escritura para cada transacción en la sesión. Para obtener más información, consulte Consentimiento de escritura en el manual del servidor MongoDB. Si omite esta propiedad, las transacciones usarán el consentimiento de escritura a nivel de sesión, si lo ha configurado. Si también omite el consentimiento de escritura a nivel de sesión, las transacciones usarán el consentimiento de escritura a nivel de cliente. Tipo de datos:WriteConcern Valor predeterminado:`null`

El siguiente ejemplo de código muestra cómo crear una sesión con opciones personalizadas:

var client = new MongoClient("mongodb://localhost:27017");
var sessionOptions = new ClientSessionOptions
{
    CausalConsistency = true,
    DefaultTransactionOptions = new TransactionOptions(
         readConcern:  ReadConcern.Available,
         writeConcern:   WriteConcern.Acknowledged)
};
var session = client.StartSession(sessionOptions);

Coherencia causal

MongoDB habilita la coherencia causal en ciertas sesiones de clientes. El modelo de coherencia causal garantiza que en un sistema distribuido, las operaciones dentro de una sesión se ejecuten en un orden causal. Los clientes observan resultados que son coherentes con las relaciones causales, o las dependencias entre las operaciones. Por ejemplo, si realizas una serie de operaciones donde una depende lógicamente del resultado de otra, las lecturas subsecuentes reflejarán esa relación de dependencia.

Para garantizar la coherencia causal, las sesiones de los clientes deben cumplir los siguientes requisitos:

Al iniciar una sesión, el driver debe habilitar la opción de coherencia causal. Esta opción está habilitada por defecto.
Las operaciones deben ejecutarse en una sola sesión en un solo hilo. De lo contrario, las sesiones o hilos deben comunicarse entre sí los valores de operation time y tiempo de clúster. Para ver un ejemplo de dos sesiones que comunican estos valores, consulte los Ejemplos de coherencia causal en el manual del servidor de MongoDB.
Debes usar un ReadConcern.Majority nivel de consistencia de lectura.
Debe usar un WriteConcern.WMajority nivel de confirmación de escritura (write concern). Este es el valor predeterminado de nivel de confirmación de escritura (write concern).

La siguiente tabla describe las garantías que ofrecen las sesiones coherentes causales:

garantías	Descripción
Leer las escrituras	Las operaciones de lectura reflejan los resultados de las operaciones de escritura anteriores.
Lecturas monotónicas	Las operaciones de lectura no devuelven resultados que reflejen un estado de datos anterior al de una operación de lectura previa.
Escrituras monotónicas	Si una operación de escritura debe preceder a otras operaciones de escritura, el servidor ejecutará primero esta operación de escritura. Por ejemplo, si llamas a `InsertOne()` para insertar un documento y luego llamas a `UpdateOne()` para modificar el documento insertado, el servidor ejecutará primero la operación de inserción.
Las escrituras siguen a las lecturas	Si una operación de escritura debe seguir a otras operaciones de lectura, el servidor primero ejecuta las operaciones de lectura. Por ejemplo, si llamas a `Find()` para recuperar un documento y luego llamas a `DeleteOne()` para borrar el documento recuperado, el servidor ejecutará primero la operación find.

Tip

Para aprender más sobre los conceptos mencionados en esta sección, consulta las siguientes entradas del manual del servidor MongoDB:

Métodos

Cree un IClientSession usando el método StartSession() síncrono o StartSessionAsync() asíncrono en su instancia de MongoClient. Luego puedes modificar el estado de la sesión utilizando el método set proporcionado por la interfaz IClientSession. Selecciona una de las siguientes opciones en las pestañas Synchronous Methods y Asynchronous Methods para conocer los métodos de gestión de tu transacción:

Método	Descripción
`StartTransaction()`	Inicia una nueva transacción, configurada con las opciones especificadas, en esta sesión. Genera una excepción si ya hay una transacción en curso para la sesión. Para obtener más información sobre este método, consulte la página startTransaction() en el manual del servidor. Parámetro: `TransactionOptions` (opcional)
`AbortTransaction()`	Finaliza la transacción activa de esta sesión. Genera una excepción si no hay ninguna transacción activa en la sesión o si la transacción ya se ha confirmado o finalizado. Para obtener más información sobre este método, consulte la página abortTransaction() del manual del servidor. Parámetro: `CancellationToken`
`CommitTransaction()`	Confirma la transacción activa de esta sesión. Genera una excepción si no hay ninguna transacción activa o si la transacción ha finalizado. Para obtener más información sobre este método, consulte la página commitTransaction() del manual del servidor. Parámetro: `CancellationToken`
`WithTransaction()`	Inicia una transacción en esta sesión y ejecuta la función de retorno proporcionada. Para obtener más información sobre este método, consulta la página withTransaction() en el manual del Servidor. IMPORTANTE: Al capturar excepciones dentro de la función de retorno utilizada por `WithTransaction()`, debes relanzar la excepción antes de salir del bloque try-catch. No hacerlo puede resultar en un ciclo infinito. Para obtener más detalles sobre cómo gestionar excepciones en este caso, consulta Transacciones en el manual del servidor y selecciona C# en el menú desplegable de lenguaje para ver el ejemplo. `Func <IClientSessionHandle, CancellationToken, Task<TResult>>TransactionOptions`Parámetros:,, `CancellationToken` Tipo de retorno: `Task <TResult>`

Método	Descripción
`StartTransaction()`	Inicia una nueva transacción, configurada con las opciones especificadas, en esta sesión. Genera una excepción si ya hay una transacción en curso para la sesión. Para obtener más información sobre este método, consulte la página startTransaction() en el manual del servidor. Parámetro: `TransactionOptions` (opcional)
`AbortTransactionAsync()`	Finaliza la transacción activa de esta sesión. Genera una excepción si no hay ninguna transacción activa en la sesión o si la transacción se ha confirmado o finalizado. Para obtener más información sobre este método, consulte la página abortTransaction() en el manual del servidor. Parámetro: `CancellationToken` Tipo de retorno: `Task`
`CommitTransactionAsync()`	Confirma la transacción activa de esta sesión. Genera una excepción si no hay ninguna transacción activa o si la transacción ha finalizado. Para obtener más información sobre este método, consulte la página commitTransaction() del manual del servidor. Parámetro: `CancellationToken` Tipo de retorno: `Task`
`WithTransactionAsync()`	Inicia una transacción en esta sesión y ejecuta la función de retorno proporcionada. Para obtener más información sobre este método, consulta la página withTransaction() en el manual del Servidor. IMPORTANTE: Al capturar excepciones dentro de la función de retorno utilizada por `WithTransactionAsync()`, debes relanzar la excepción antes de salir del bloque try-catch. No hacerlo puede resultar en un ciclo infinito. Para obtener más detalles sobre cómo gestionar excepciones en este caso, consulta Transacciones en el manual del servidor y selecciona C# en el menú desplegable de lenguaje para ver el ejemplo. `Func <IClientSessionHandle, CancellationToken, Task<TResult>>TransactionOptions`Parámetros:,, `CancellationToken` Tipo de retorno: `Task <TResult>`

Tip

Configurar Transacciones

Puedes personalizar el comportamiento de transacciones individuales pasando una instancia de la clase TransactionOptions al método StartTransaction() o WithTransaction(). Las opciones establecidas aquí sustituyen las opciones de transacción predeterminadas que estableces en el objeto ClientSessionOptions.

Ejemplo

Este ejemplo muestra cómo puedes crear una sesión, crear una transacción e insertar documentos en varias colecciones dentro de la transacción a través de los siguientes pasos:

Cree una sesión desde el cliente usando el método StartSession().
Cree un objeto TransactionOptions para configurar la transacción.
Utiliza el método StartTransaction() para iniciar una transacción.
Inserte documentos en las colecciones books y films.
Confirme la transacción usando el método CommitTransaction().

var books = database.GetCollection<Book>("books");
var films = database.GetCollection<Film>("films");
// Begins transaction
using (var session = mongoClient.StartSession())
{
    // Configures transaction options
    var transactionOptions = new TransactionOptions(
        readConcern: ReadConcern.Majority,
        writeConcern: WriteConcern.WMajority
    );
    session.StartTransaction(transactionOptions);
    try
    {
        // Creates sample data
        var book = new Book
        {
            Title = "Beloved",
            Author = "Toni Morrison",
            InStock = true
        };
        var film = new Film
        {
            Title = "Star Wars",
            Director = "George Lucas",
            InStock = true
        };
        // Inserts sample data
        books.InsertOne(session, book);
        films.InsertOne(session, film);
        // Commits our transaction
        session.CommitTransaction();
    } 
    catch (Exception e)
    {
        Console.WriteLine("Error writing to MongoDB: " + e.Message);
        return;
    }
    // Prints a success message if no error thrown
    Console.WriteLine("Successfully committed transaction!");
}

Successfully committed transaction!

Nota

Operaciones paralelas no admitidas

El driver .NET/C# no admite la ejecución de operaciones paralelas dentro de una sola transacción.

Si utiliza MongoDB Server v8.0 o posterior, puede realizar operaciones de escritura en varios espacios de nombres dentro de una sola transacción utilizando el método BulkWrite() o BulkWriteAsync(). Para más información, consulta Operaciones de guardado masivo.

Información Adicional

Para **aprender** más sobre los conceptos mencionados en esta **guía**, consulta las siguientes páginas en el manual del **servidor**:

Documentación de la API

Para aprender más sobre cualquiera de los tipos o métodos discutidos en esta guía, consulta la siguiente documentación de la API:

Volver

Operaciones de escritura masiva

Almacene archivos grandes