/ /

Operações em lote em transações

Visão geral

Neste guia, você aprenderá a usar o driver .NET/C# do MongoDB para realizar transações. As transações permitem executar uma série de operações que não alteram nenhum dado até que a transação seja confirmada. Se alguma operação na transação retornar um erro, o driver cancelará a transação e descartará todas as alterações de dados antes que elas se tornem visíveis.

O MongoDB garante que os dados envolvidos em suas operações de transação permaneçam consistentes, mesmo que as operações encontrem erros inesperados.

Sessões

No MongoDB, as transações são executadas dentro de sessões lógicas. Uma sessão é um agrupamento de operações de leitura ou escrita relacionadas que você pretende executar sequencialmente. As sessões permitem consistência causal para um grupo de operações ou permitem que você execute operações em uma transação ACID.

Ao usar o driver .NET/C#, você pode criar uma nova sessão a partir de uma instância MongoClient como um tipo IClientSession. Recomendamos reutilizar seu cliente para várias sessões e transações, em vez de fazer a instância de um novo cliente a cada vez.

O exemplo seguinte mostra como criar uma sessão chamando o método StartSession():

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

Aviso

Utilize um IClientSession apenas com o MongoClient (ou MongoDatabase ou MongoCollection associada) que o criou. Utilizar uma IClientSession com um MongoClient diferente resulta em erros de operação.

ClientSessionOptions

Você pode personalizar o comportamento da sua sessão passando uma instância da classe ClientSessionOptions para o método StartSession(). A tabela a seguir descreve as propriedades que você pode definir em um objeto ClientSessionOptions :

Propriedade	Descrição
`CausalConsistency`	Especifica se a sessão é causalmente consistente. Em uma sessão causalmente consistente, o driver executa operações na ordem em que foram emitidas. Para saber mais, consulte Consistência causal. Tipo de`boolean` dados: Padrão: `true`
`DefaultTransactionOptions`	Especifica as opções de transação padrão para a sessão. Isso incluio tempo máximo de confirmação, preocupação de leitura, preferência de leitura e preocupação de gravação. Tipo de Dados: TransactionOptions Padrão: `null`
`Snapshot`	Especifica se o driver realiza leituras de snapshots. Para saber mais sobre leituras de snapshots, consulte Read Concern "snapshot" no manual do MongoDB Server . Tipo de dados: `boolean` Padrão: `false`
`SnapshotTime`	Especifica o tempo de agrupamento no qual o driver lê todos os dados na sessão. Você deve `Snapshot` definir `true` como ao definir esta propriedade. Para saber mais, consulte Read Concern "snapshot" no manual do MongoDB Server . Tipo de Dados: BsonTimestamp Padrão: `null`

A propriedade DefaultTransactionOptions aceita uma instância da classe TransactionOptions. A tabela a seguir descreve as propriedades que você pode definir em um objeto TransactionOptions :

Propriedade	Descrição
`MaxCommitTime`	Quantidade máxima de tempo que um único `commitTransaction` comando pode executar. Se a confirmação exceder esse limite, o MongoDB Server retornará um `MaxTimeMSExpired` erro e não confirmará as alterações na transação. O driver não tenta novamente a confirmação após esse erro. Se você omitir esta propriedade, o MongoDB Server aplicará o limite de tempo de execução da transação padrão. Tipo `TimeSpan?` de dados: Padrão: `null`
`ReadConcern`	Preocupação de leitura para cada transação na sessão. Para saber mais, consulte Read Concern no manual do MongoDB Server . Se você omitir essa propriedade, as transações usarão a preocupação de leitura no nível da sessão, se você definir uma. Se você também omitir a preocupação de leitura em nível de sessão, as transações usarão a preocupação de leitura em nível de cliente. Tipo de Dados: Padrão ReadConcern: `null`
`ReadPreference`	Preferência de leitura para cada transação na sessão. Para saber mais, consulte Preferência de leitura no manual do MongoDB Server . Se você omitir essa propriedade, as transações usarão a preferência de leitura de nível de sessão, se você definir uma. Se você também omitir a preferência de leitura no nível da sessão , as transações usarão a preferência de leitura no nível do cliente . Tipo de dados: Padrão ReadPreference: `null`
`WriteConcern`	Write concern para cada transação na sessão. Para saber mais, consulte Write Concern no manual do MongoDB Server . Se você omitir essa propriedade, as transações usarão a preocupação de gravação no nível da sessão, se você definir uma. Se você também omitir a preocupação de gravação em nível de sessão , as transações usarão a preocupação de gravação em nível de cliente . Tipo de Dados: Padrão WriteConcern: `null`

O seguinte exemplo de código mostra como criar uma sessão com opções 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);

Consistência causal

O MongoDB permite consistência causal em determinadas sessões de cliente. O modelo de consistência causal garante que, em um sistema distribuído, as operações dentro de uma sessão sejam executadas em uma ordem causal. Os clientes observam resultados consistentes com as relações causais ou as dependências entre as operações. Por exemplo, se você executar uma série de operações em que uma operação depende logicamente do resultado de outra, todas as leituras subsequentes refletirão o relacionamento de dependência .

Para garantir a consistência causal, as sessões de cliente devem atender aos seguintes requisitos:

Ao iniciar uma sessão, o driver deve habilitar a opção de consistência causal. Esta opção está habilitada por padrão.
As operações devem ser executadas em uma única sessão em um único thread. Caso contrário, as sessões ou threads devem comunicar os valores de optime e tempo de cluster uns aos outros. Para exibir um exemplo de duas sessões que comunicam esses valores, consulte os exemplos de Consistência causal no manual do MongoDB Server.
Você deve usar uma preocupação de leitura ReadConcern.Majority .
Você deve usar uma preocupação de gravação WriteConcern.WMajority . Este é o valor padrão de preocupação de gravação .

A tabela a seguir descreve as garantias que as sessões causalmente consistentes oferecem:

Garantia	Descrição
Ler suas gravações	As operações de leitura refletem os resultados das operações de gravação anteriores.
Leituras monotônicas	As operações de leitura não retornam resultados que reflitam um estado de dados anterior a uma operação de leitura anterior.
Escritas monotônicas	Se uma operação de gravação precisar preceder outras operações de gravação, o servidor executará essa operação de gravação primeiro. Por exemplo, se você chamar `InsertOne()` para inserir um documento e, em seguida, chamar `UpdateOne()` para modificar o documento inserido, o servidor executará a operação de inserção primeiro.
Escritas que seguem as leituras	Se uma operação de gravação precisar seguir outras operações de leitura, o servidor executará primeiro as operações de leitura. Por exemplo, se você chamar `Find()` para recuperar um documento e, em seguida, chamar `DeleteOne()` para excluir o documento recuperado, o servidor executará primeiro a operação de localização.

Dica

Para saber mais sobre os conceitos mencionados nesta seção, consulte as seguintes entradas de manual do MongoDB Server :

Métodos

Crie um IClientSession usando o método StartSession() síncrono ou o método StartSessionAsync() assíncrono em sua instância MongoClient. Depois, você pode modificar o estado da sessão usando o conjunto de métodos fornecido pela interface IClientSession. Selecione uma das seguintes abas Synchronous Methods e Asynchronous Methods para saber mais sobre os métodos para gerenciar sua transação:

Método	Descrição
`StartTransaction()`	Inicia uma nova transação, configurada com as opções fornecidas, nesta sessão. Lança uma exceção se já houver uma transação em andamento para a sessão. Para saber mais sobre esse método, consulte a página startTransaction() no manual do servidor. Parâmetro: `TransactionOptions` (opcional)
`AbortTransaction()`	Termina a transação ativa para esta sessão. Lança uma exceção se não houver uma transação ativa para a sessão ou se a transação tiver sido confirmada ou encerrada. Para saber mais sobre esse método, consulte a página abortTransaction() no manual do servidor. Parâmetro: `CancellationToken`
`CommitTransaction()`	Confirma a transação ativa para esta sessão. Lança uma exceção se não houver nenhuma transação ativa para a sessão ou se a transação tiver sido encerrada. Para saber mais sobre esse método, consulte a página commitTransaction() no manual do servidor. Parâmetro: `CancellationToken`
`WithTransaction()`	Inicia uma transação nesta sessão e executa a chamada de resposta fornecida. Para saber mais sobre esse método, consulte a página withTransaction() no manual do MongoDB Server. IMPORTANTE: ao capturar exceções dentro da função de chamada de resposta `WithTransaction()` usada por, você deve lançar novamente a exceção antes de sair do bloco try-catch. Não fazer isso pode resultar em um loop infinito. Para obter mais detalhes sobre como lidar com exceções nesse caso, consulte Transações no manual do servidor e selecione C# no menu suspenso de idioma para ver o exemplo. `Func <IClientSessionHandle, CancellationToken, Task<TResult>>TransactionOptions`Parâmetros:,, `CancellationToken` Tipo de Retorno: `Task <TResult>`

Método	Descrição
`StartTransaction()`	Inicia uma nova transação, configurada com as opções fornecidas, nesta sessão. Lança uma exceção se já houver uma transação em andamento para a sessão. Para saber mais sobre esse método, consulte a página startTransaction() no manual do servidor. Parâmetro: `TransactionOptions` (opcional)
`AbortTransactionAsync()`	Termina a transação ativa para esta sessão. Lança uma exceção se não houver uma transação ativa para a sessão ou se a transação tiver sido confirmada ou encerrada. Para saber mais sobre esse método, consulte a página abortTransaction() no manual do servidor. Parâmetro: `CancellationToken` Tipo de retorno: `Task`
`CommitTransactionAsync()`	Confirma a transação ativa para esta sessão. Lança uma exceção se não houver nenhuma transação ativa para a sessão ou se a transação tiver sido encerrada. Para saber mais sobre esse método, consulte a página commitTransaction() no manual do servidor. Parâmetro: `CancellationToken` Tipo de retorno: `Task`
`WithTransactionAsync()`	Inicia uma transação nesta sessão e executa a chamada de resposta fornecida. Para saber mais sobre esse método, consulte a página withTransaction() no manual do MongoDB Server. IMPORTANTE: ao capturar exceções dentro da função de chamada de resposta `WithTransactionAsync()` usada por, você deve lançar novamente a exceção antes de sair do bloco try-catch. Não fazer isso pode resultar em um loop infinito. Para obter mais detalhes sobre como lidar com exceções nesse caso, consulte Transações no manual do servidor e selecione C# no menu suspenso de idioma para ver o exemplo. `Func <IClientSessionHandle, CancellationToken, Task<TResult>>TransactionOptions`Parâmetros:,, `CancellationToken` Tipo de Retorno: `Task <TResult>`

Dica

Configurar transações

Você pode personalizar o comportamento de transações individuais passando uma instância da classe TransactionOptions para o método StartTransaction() ou WithTransaction(). As opções definidas aqui substituem as opções de transação padrão definidas no objeto ClientSessionOptions.

Exemplo

Este exemplo mostra como criar uma sessão, criar uma transação e inserir documentos em várias coleções dentro da transação por meio das seguintes etapas:

Crie uma sessão a partir do cliente usando o método StartSession().
Crie um objeto TransactionOptions para configurar a transação.
Use o método StartTransaction() para iniciar uma transação.
Insira documentos nas coleções books e films .
Confirme a transação usando o 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!

Observação

Operações paralelas não suportadas

O driver .NET/C# não suporta a execução de operações paralelas em uma única transação.

Se você estiver usando o MongoDB Server v8.0 ou posterior, poderá executar operações de gravação em vários namespaces em uma única transação usando o método BulkWrite() ou BulkWriteAsync(). Para mais informações, consulte Operações de Gravação em Massa.

Informações adicionais

Para saber mais sobre os conceitos mencionados neste guia, consulte as seguintes páginas no manual do servidor:

Documentação da API

Para saber mais sobre qualquer um dos tipos ou métodos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Operações de gravação em massa

Armazenar arquivos grandes