/ /

Driver C#/ .NET

Fundamentals

Página inicial do Docs

Bibliotecas do cliente

Driver C#/ .NET

Fundamentals

Usar transações em C#

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.

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 gravação 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. 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.

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.

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.

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. Gera uma exceção se já houver uma transação em andamento para a sessão. Para aprender 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 nenhuma 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. Gera uma exceção se não houver uma transação ativa para a sessão ou se a transação tiver sido encerrada. Para aprender 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. Parâmetros: `Func <IClientSessionHandle, CancellationToken, Task<TResult>>`, `TransactionOptions`, `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. Gera uma exceção se já houver uma transação em andamento para a sessão. Para aprender 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 nenhuma 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. Gera uma exceção se não houver uma transação ativa para a sessão ou se a transação tiver sido encerrada. Para aprender 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. Parâmetros: `Func <IClientSessionHandle, CancellationToken, Task<TResult>>`, `TransactionOptions`, `CancellationToken` Tipo de retorno: `Task <TResult>`

opções de transação

Para configurar uma transação individual, passe uma instância TransactionOptions para o método StartTransaction() ou WithTransaction(). O exemplo nesta seção define a preocupação de leitura como ReadConcern.Majority e a preocupação de gravação como WriteConcern.WMajority.

Você pode configurar um objeto TransactionOptions com as seguintes propriedades:

Propriedade	Descrição
`MaxCommitTime`	Quantidade máxima de tempo que um único comando `commitTransaction` pode executar. Se o commit exceder esse limite, o MongoDB Server retornará um erro `MaxTimeMSExpired` e não confirmará a transação. Se você omitir essa propriedade, o MongoDB Server aplicará o limite de tempo de execução de transação padrão. Tipo de dados: `TimeSpan?`
`ReadConcern`	Read concern para a transação. Para aprender mais, consulte Read Concern no manual do MongoDB Server. Tipo de Dados: ReadConcern
`ReadPreference`	Preferência de leitura para a transação. Para saber mais, consulte Preferência de leitura no manual do MongoDB Server. Tipo de dados: ReadPreference
`WriteConcern`	Write concern para a transação. Para saber mais, consulte Write Concern no manual do MongoDB Server. Tipo de Dados: WriteConcern

Exemplo

Este exemplo mostra como criar uma sessão, configurar as opções de transaçã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.

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

GUIDs

Indexes