Alterações em lote com transações

Visão geral

Neste guia, você aprenderá a usar transações em seus aplicativos do provedor EF Core. Uma transação envolve uma série de operações de gravação. Se alguma operação na transação falhar, o provedor reverterá todas as alterações na transação. Esse comportamento ajuda a garantir a consistência dos dados.

O provedor do EF Core suporta os seguintes modos de transação:

• Transações implícitas: O provedor automaticamente envolve chamadas para os métodos SaveChanges() e SaveChangesAsync() em uma transação. Consulte Configurar transações implícitas para saber como configurar ou desabilitar esse comportamento.

• Transações explícitas: Você chama o método Database.BeginTransaction() para iniciar manualmente uma transação e, em seguida, confirma ou reverte a transação chamando Commit() ou Rollback().

public class Planet
{
    public ObjectId _id { get; set; }
    public string name { get; set; } = null!;
    public int orderFromSun { get; set; }
    public bool hasRings { get; set; }
}

Requisitos e limitações

Antes de usar transações, observe os seguintes requisitos e limitações:

• As transações exigem uma implantação do MongoDB Server que suporte transações multidocumento, como um conjunto de réplicas ou cluster sharded. Se seu aplicativo tentar iniciar uma transação em uma implantação autônoma, o provedor lançará um NotSupportedException. Para evitar isso, defina AutoTransactionBehavior.Never conforme descrito em Configurar transações implícitas.

• O provedor EF Core não oferece suporte a transações ambiente .NET, como as criadas por System.Transactions.TransactionScope. Se você tentar usar uma transação ambiente, o provedor lançará uma exceção. Em vez disso, use transações implícitas ou explícitas.

Transações implícitas

Por padrão, o provedor EF Core automaticamente encapsula as chamadas SaveChanges() e SaveChangesAsync() em uma transação quando várias entidades raiz são afetadas. Uma entidade raiz é um documento de nível superior em uma coleção, em oposição a um tipo de propriedade ou incorporado que é armazenado dentro de outro documento.

O exemplo a seguir insere dois planetas em uma única chamada SaveChanges(). Como esta operação afeta mais de uma entidade raiz, o provedor a envolve automaticamente em uma transação. Se qualquer inserção falhar, o provedor reverterá ambas as alterações.

Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

dbContext.Planets.AddRange(
    new Planet { Name = "Mercury" },
    new Planet { Name = "Venus" }
);
// Both inserts succeed or both are rolled back
dbContext.SaveChanges();

dbContext.Planets.AddRange(
    new Planet { Name = "Mercury" },
    new Planet { Name = "Venus" }
);
// Both inserts succeed or both are rolled back
await dbContext.SaveChangesAsync();

dbContext.Database.AutoTransactionBehavior = AutoTransactionBehavior.Never;
// This SaveChanges() call will not use a transaction
dbContext.Planets.Add(new Planet { Name = "Mars" });
dbContext.SaveChanges();

dbContext.Database.AutoTransactionBehavior = AutoTransactionBehavior.Never;
// This SaveChangesAsync() call will not use a transaction
dbContext.Planets.Add(new Planet { Name = "Mars" });
await dbContext.SaveChangesAsync();

Transações explícitas

Você pode usar transações explícitas para agrupar várias chamadas SaveChanges() e outras operações em uma única unidade atômica de trabalho. Para iniciar uma transação explícita, chame o método Database.BeginTransaction() ou Database.BeginTransactionAsync(). Depois de realizar suas operações, chame Commit() ou CommitAsync() para concluir a transação.

O exemplo a seguir mostra esse padrão agrupando várias operações em uma única transação. Se alguma operação gerar uma exceção, o provedor reverterá automaticamente todas as alterações na transação. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente.

using var transaction = dbContext.Database.BeginTransaction();
var planet = dbContext.Planets.First(p => p.Name == "Mercury");
planet.Name = "Mercury (Updated)";
dbContext.SaveChanges();
dbContext.Planets.Add(new Planet { Name = "Venus" });
dbContext.SaveChanges();
transaction.Commit();

await using var transaction = await dbContext.Database.BeginTransactionAsync();
var planet = await dbContext.Planets.FirstAsync(p => p.Name == "Mercury");
planet.Name = "Mercury (Updated)";
await dbContext.SaveChangesAsync();
dbContext.Planets.Add(new Planet { Name = "Venus" });
await dbContext.SaveChangesAsync();
await transaction.CommitAsync();

var options = new TransactionOptions(
    readConcern: new Optional<ReadConcern>(ReadConcern.Majority)
);
using var transaction = dbContext.Database.BeginTransaction(options);
var planet = dbContext.Planets.First(p => p.Name == "Mercury");
planet.Name = "Mercury (Updated)";
dbContext.SaveChanges();
transaction.Commit();

var options = new TransactionOptions(
    readConcern: new Optional<ReadConcern>(ReadConcern.Majority)
);
await using var transaction = await dbContext.Database.BeginTransactionAsync(options);
var planet = await dbContext.Planets.FirstAsync(p => p.Name == "Mercury");
planet.Name = "Mercury (Updated)";
await dbContext.SaveChangesAsync();
await transaction.CommitAsync();

Limitações de transação

As seguintes limitações e precauções se aplicam ao usar transações:

• Desative as transações automáticas somente se sua implantação não as suportar. A desativação de transações automáticas pode causar inconsistências de dados e impede que você use a concorrência otimista.

• O MongoDB Server não suporta transações aninhadas. Se você chamar BeginTransaction() ou BeginTransactionAsync() enquanto uma transação já estiver ativa, o provedor lançará um InvalidOperationException.

• O MongoDB Server não oferece suporte a pontos de salvamento de transações. Você deve fazer commit ou rollback de uma transação inteira.

• Por padrão, o MongoDB Server anula qualquer transação que seja executada por mais de 60 segundos, conforme controlado pelo parâmetro do servidor transactionLifetimeLimitSeconds. Este limite se aplica a transações implícitas e explícitas. Se sua transação exceder esse limite de tempo, o MongoDB Server a anulará e o provedor gerará um erro. Evite realizar operações de longa duração, como chamadas de API externas, dentro de uma transação.

• Se o MongoDB Server sofrer uma interrupção de rede ou precisar realizar uma eleição de conjunto de réplicas, ele poderá retornar um erro TransientTransactionError. Nesses casos, o provedor EF Core não tenta novamente a transação automaticamente. Para saber mais sobre erros de transação transitórios e estratégias de repetição, consulte Tratamento de erros de transações.

Informações adicionais

Para saber mais sobre os conceitos deste guia, consulte os seguintes recursos:

• Gravar dados no MongoDB
• Garanta a consistência dos dados com simultaneidade otimista
• Transações

Para saber mais sobre os métodos usados nesta guia, consulte a seguinte documentação da API .NET:

• BeginTransaction() e BeginTransactionAsync()

• CommitTransaction() e CommitTransactionAsync()

• RollbackTransaction() e RollbackTransactionAsync()

• SaveChanges() e SaveChangesAsync()