DEV Community: EveIsSim

C# How to ambient transaction work under the hood

EveIsSim — Fri, 09 May 2025 08:00:00 +0000

In previous article, we looked at how TransactionScope (ambient transaction) simplifies transactional consistency. But how does it do this? How does such a simple and convenient mechanism solve this problem? How exactly is a transaction passed between threads is asynchronous communication? And how does the process of rollback and commit work?
In this article we will try to figure it out with you.

Structure:

TransactionScope and Transaction.Current
How exactly does ExecutionContext 'know' about ContextKey through AsyncLocal and what happens when await occurs
How Transaction is passed to Npgsql
How do Commit() and Rollback() work
Conclusion

1. TransactionScope and Transaction.Current

sources:

transaction scope class - source
System.Transaction class - source

The TransactionScope class in .NET is used to automatically manage transactions through the ambient transactions mechanism. You can read more about its application here

Now let's try to figure out what happens when we create a TransactionScope.
Exp:

using var scope = new TransactionScope();

// our repo methods.

scope.Complete();

For understanding, I suggest you open the TransactionScope.cs source code in parallel - source.
NOTE: For easy of reading, find the creation of the public TransactionScope(...) instance.
At the time of writing this is line 53.

Steps:

Validate and set AsyncFlow in ValidateAndSetAsyncFlowOption
Trying to see if there is a transaction already created or if we have to create a new one in NeedToCreateTransaction (the name might be a bit weird, that's ok (-: )
1. In the CommonInitialize method using Transaction.GetCurrentTransactionAndScope(...) we try to get the current transaction and scope:
  1. We look at the current transaction in current thread
    1. If there is one we return otherwise null.
2. Call ValidateAsyncFlowOptionAndESInteropOption
  1. In short, it is forbidden to use AsyncFlow in single-threaded mode.
Check scope option, if TransactionScope.Required
1. We return false if there is a transaction, or true if we need to create one.
Creation is done via CommitableTransaction
1. This is the actual managed transaction object that will be either Commit() or Rollback() in the end. (TransactionScope automatically completes the transaction only if Complete() has been called and there are no exceptions or other processed errors. Otherwise, the transaction is rolled back when leaving the using scope)
Make a Clone() transaction for subsequent transfer to Transaction.Current
1. Why? The Clone() method returns a transaction object without the ability to do Commit(). Isolation and single point control mechanism.
Set TransactionScope and specify the transaction as ambient available via Transaction.Current in PushScope()
1. Here we are interested in the CallContextCurrentData.CreateOrGetCurrentData method, it is operation is as follows:
  1. AsyncLocal<ContextKey> - responsible for 'where we are'.
  2. ConditionalWeakTable<ContextKey, ContextData - stores the actual state of the transaction.
  3. => we add our ContextKey transaction on these objects.
  4. Now ExecutionContext via AsyncLocal 'knows' which ContextKey is active and we can get the state from it.
    1. See p.2 for exactly how this works.
2. SetCurrent - set the current transaction.

2. How exactly does `ExecutionContext` 'know' about `ContextKey` through `AsyncLocal` and what happens when `await` occurs

ExecutionContext - This is the container of the logical execution context, which includes:

AsyncLocal<T> values
CallContext
HttpContext
SecurityContext
and other 'logical' thread data

Its main task:
Automatically copy and restore all values associated with the current execution context when you switch between threads, tasks, etc.

Where is `AsyncLocal` in this?

Example from Transaction.cs

private static readonly AsyncLocal<ContextKey?> s_currentTransaction = new AsyncLocal<ContextKey?>();

When we do:

s_currentTransaction.Value = someContextKey;

Its mean, that:

The current ExecutionContext is saved
Then, when continuing (on another thread/task), it will be restored
And s_currentTransaction.Value will be equal to someContextKey again.

What does `AsyncLocal` do under the hood?

AsyncLocal<T> is registered in the ExecutionContext via the .NET infrastructure
When any await, ThreadPool.QueueUserWorkItem, Task.Run():
- Copying of ExecutionContext occurs
- Along with it - all AsyncLocal are copied

3. How `Transaction` is passed to `Npgsql`

This is where we have to touch on ADO.NET
ADO.NET is a low-level data access platform in .NET that:

Allow working with databases (SQL Server, PostgreSQL, Oracle, etc.)
Supports connection, executing SQL queries, reading results, transaction read Microsoft documentation for more details - here

Npgsql is an ADO.NET provider for PostgreSQL. In this article we will consider it, but the principle of transaction retrieval itself should be almost the same for other providers.

When you work with TransactionScope or Transaction.Current and open SqlConnection, NpgsqlConnection and etc, the following happens:

Inside Npgsql when you call NpgsqlConnection.Open(), Transaction.Current is checked, and it it is not null, the driver itself call EnlistTransaction(...), thus attaching the connection to the transaction.

NOTE: What happens if there is no transaction? - Then your request will work in normal autocommit mode. So be careful when creating TransactionScope to avoid making this situation

Steps:

You call async method inside TransactionScope

using var scope = new TransactionScope(TransactionScopeAsyncFlowOption.Enabled))

await _repo.DoSmth();_

scope.Complete();

Inside the _repo.DoSmth() method you open a connection to the database
When the connection is opened, the binding to the transaction takes place:
1. NpgsqlConnection source
2. In the OpenAsync() method, we define var enlistToTransaction = Settings.Enlist ? Transaction.Current : null
3. Settings.Enlist - answers whether to try to connect to the current transaction or not.
  1. By default this value = true. Documentation - here
4. => we take Transaction.Current
  1. Where the next chain of calls will be:
    1. Transaction.Current => GetCurrentTransactionAndScope(...) => LookupContextData(...) => TryGetCurrentData(...) => s_currentTransaction.Value

FINISH: Congratulations, we have figured out how a transaction works within TransactionScope.

But that is not all. Let's try to understand what IDBTransaction has to do with it and how exactly Commit and Rollback will work.

4. How do Commit() and Rollback() work

We have worked out that:

Transaction.Current - is simply a global reference to the current active transaction in the thread or AsyncLocal
It does not commit or rollback
It provides you a transaction that you can:
- EnlistTransaction(tx) is a method that:
  - Remember Transaction.Current as the active transaction
  - Creates a real BEGIN at the PostgreSQL level
  - Waits for a Commit() or Rollback() command from .NET and does not do the COMMIT itself.

Actually Commit() is only called manually by the user via scope.Complete().
If scope.Complete() has not been called, then Rollback() will be executed when scope.Dispose() is called automatically or manually.

What does IDbTransaction have to do with this?

In brief, it has nothing to do with:

IDbTransaction is an ADO.NET interface for manual managing
It allows you to manually manage a transaction
has Commit() and Rollback() like TransactionScope()

Despite this TransactionScope and IDBTransaction do not overlap directly, only relatively.

How then does `TransactionScope` work without `IDBTransaction`?

When you use TransactionScope with NpgsqlConnection Npgsql registers a special VilatileResourceManager object in Transaction.Current via the

transaction.EnlistVolatile(volatileResourceManager, EnlistmentOptions.None);

This VilatileResourceManager implements:

ISinglePhaseNotification (for an one-phase commit)
IEnlistmentNotification (because ISinglePhaseNotification inherits it) (for a two-phase commit)

When we call scope.Complete() = just sets the flag _complete = true
scope.Dispose() => call Commit() from CommitableTransaction

Where resource.SinglePhaseCommit(enlistment) will subsequently be called.
On the Npgsql side, the SinglePhaseCommit implementation will call _connector.ExecuteInternal(“Commit”) where _connector = NpgsqlConnector;

The NpgsqConnector itself does the following:

Formats the SQL-query into binary or text PostgreSQL protocol
Sends the command via TCP (via Socket, Stream)
Processes the response (e.g., CommandComplete)
Updates the internal transaction state in connector.TrasactionStatus

NOTE: This article only considers the single-phase commit scenario, where only one resource in invilved in a transaction.

Conclusion

As a result, we have seen how exactly TransactionScope works under the hood and what makes it possible to write such simple and elegant code.

Since this article serves as a companion to C# Ambient Transactions: What They Are and Why They Matter
I’ve added transaction logging at each step in the demo project, which you can see via the console. The code is here

console log exp.

[Endpoint] Start: Thread: 7
[Endpoint] Start: Transaction.Current:
 => [TxFactory] Creating TransactionScope
 => [TxFactory] Thread: 7
 => [TxFactory] TransactionScope created. Transaction.Current ID: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] UpdateBalanca: UserId: 1. Before OpenAsync. Thread: 7
 => => [DB] UpdateBalanca: UserId: 1. Transaction.Current: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] UpdateBalanca: UserId: UserId: 1. After OpenAsync. Still in Transaction: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] UpdateBalanca: UserId: 2. Before OpenAsync. Thread: 7
 => => [DB] UpdateBalanca: UserId: 2. Transaction.Current: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] UpdateBalanca: UserId: UserId: 2. After OpenAsync. Still in Transaction: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] AddLog: UserFrom: 1 -> UserTo: 2. Before OpenAsync. Thread: 7
 => => [DB] AddLog: UserFrom: 1 -> UserTo: 2. Transaction.Current: c37ac104-0513-4445-b2cd-ae4687fb5598:1
 => => [DB] AddLog: UserFrom: 1 -> UserTo: 2. After OpenAsync. Still in Transaction: c37ac104-0513-4445-b2cd-ae4687fb5598:1
[Endpoint] Stop: After [TxFactory].Dispose: Thread: 7
[Endpoint] Stop: After [TxFactory].Dispose: Transaction.Current:

Thank you for your attention.

C# Ambient Transactions: What They Are and Why They Matter

EveIsSim — Mon, 31 Mar 2025 23:05:20 +0000

Introduction

Transactions are the main mechanism for ensuring data consistency in a system. A transaction ensures that all actions within it either succeed or fail, keeping the system in a consistent state.

In .NET, transactions can be managed manually using BeginTransaction() from System.Data.IDbConnection. Many developers, both experienced and novice, choose this approach.

However, manually managing transactions creates many problems:

Forgotten commits
Unhandled exceptions
Nesting conflicts
Rollback errors
Generating Leaky repository OR Separation of Concerns. When business logic goes beyond the Business layer and spreads to the Repository layer and vice versa.
async/await issues

It is especially painful when the code base starts to grow and grow dependencies and duplicated parts, violating the most important things in the project: readability, support, testing, in other words, violating the SRP principle.

In this article, I will talk about typical problems of using BeginTransaction() and how they can be solved via TransactionScopeFactory.

Problems

Forgotten commit or rollback

One of the most frequent errors is a forgotten Commit() or Rollback(). It can be happen if the code has conditional branching, early return. Or an exception is thrown.

As result, the transaction hangs, blocks resources, or results in data loss.

In addition, Rollback() can throw an exception too (e.g. for connection problems), and if it is not handled, the application may crash at the moment when it was supposed to be recovering.

Non-processing of exceptions

When working with transactions, you should always wrap a block of operations in try/catch. But this is often forgotten, especially in a hurry or when it seems “nothing can do wrong”.

This results in unclosed transactions, connection leaks and data loss.

Conflicts with nesting

Manual transactions do not support nesting. If an internal methods starts BeginTransaction without knowing that a transaction has already been started above, an error may occur: either an exception or the logic will start working in a new isolated transaction, breaking atomicity.

This is especially critical when reusing libraries.

The principle of trust in previously written code by your teammates is violated.

Leaky Repository / Violation of Separation of Concerns

When you use BeginTransaction in business logic and commit in repository, or vice versa, you are blurring the responsibility between the layers.

// Service  
_repo.DoSomething();  

// Repository  
using var tx = connection.BeginTransaction();  
... // Additional logic related to business or rollback logic.  
tx.Commit();

This violates Separation of Concerns: now the service must know that repository itself commits something, and the repository cannot be reused in other contexts.

This kind of code is hard to test, scale, and maintain.

This is leaky abstraction, and one of the main anti-patterns when working with transactions.

Problems with `async/await` and explicit transaction passing

When you use BeginTransaction in asynchronous code, it becomes necessary to explicitly pass the transaction object IDbTransaction and the connection IDbConnection to all methods that participate in the transition.

This make the code less readable, more brittle, and breaks encapsulation.

Each method must accept both the connection and the transaction, even if it does not directly deal with them itself. This leads to strong coupling, makes testing harder, and makes the code more vulnerable to bugs. One forgotten tx in the parameters and the logic goes beyond the transaction.

Solution: How to solve these problems and what does TransactionScopeFactory have to do with it?

TransactionScopeFactory is a wrapper that helps to create a TransactionScope with the desired settings, while taking into account the current ambient context and working correctly with async/await.

As examples we will consider a simplified system of recording money transfers from customer A => B and logging the fact the transfer was made.

// Service
public async Task<...> Transfer(....)
{
  .....
  source.Balance -= r.Amount;
  destination.Balance += r.Amount;

  .....
  using var ts = _transactionScopeFactory.Create();

  var err = await _db.UpdateBalance([source, destination], token);
  if (err != null) return err;

  var err = await _db.AddLog(r.ToLog(), token);
  if (err != null) return err;

  ts.Complete();
}
.....

// Repository


public async Task<string> UpdateBalance(AccountEntity[] entities, CancellationToken token)
{
    try
    {
        foreach (var entity in entities)
        {
            var result = await UpdateBalance(entity, token);
            if (!result.IsSucces)
                return result;
        }
        return (true, "");
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
}

private async Task<string> UpdateBalance(AccountEntity entity, CancellationToken token)
{
    var sql = "UPDATE accounts SET ....";

    try
    {
        ... ExecuteAsync ...
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
}

public async Task<string> AddLog(TransactionLogEntity entity, CancellationToken token)
{
    var sql = @"
            INSERT INTO ....
            VALUES ....";

    try
    {
        ... ExecuteAsync ...
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
}

This approach allows you to get:

Clean and readable code
try/catch processing is at the repository level. All business logic is in one place: clear and easy to understand.
Repository methods are concise and simple and ready to reused
Support for async/await
Secure transaction completion
Respect for external ambient — context if it already exists.

How to implement TransactionScopeFactory

If you want to apply this approach to you project, below is a basic example of a TransactionScopeFactory implementation.

A more detailed implementation with integration into business logic, repositories and unit-of-work can be viewed in my repository on GitHub: EveIsSim/AmbientTransaction

Create interface:

public interface ITransactionScopeFactory  
{  
    TransactionScope Create();  
}

Add implementation: where:

TransactionScopeOption.Required — If there is already an active transaction in the current context — join it. If not — create a new one.
IsolationLevel.ReadCommitted — It provides protection against “dirty reads” and is a reasonable compromise between security and perfomance.
TransactionScopeAsyncFlowOption.Enabled — If you specify this flag when creating a TransactionScope, Transaction.Current will be saved via await.

public class TransactionScopeFactory : ITransactionScopeFactory
{
    public TransactionScope Create()
    {
        return new TransactionScope(
            TransactionScopeOption.Required,
            new TransactionOptions
            {
                IsolationLevel = IsolationLevel.ReadCommitted
            },
            TransactionScopeAsyncFlowOption.Enabled);
    }
}

Conclusion

If you are still manually managing transactions via BeginTransaction, you have probably already experienced the pain of supporting such code. An abstraction like TransactionScopeFactory helps you write cleaner, more stable and reusable code. This is especially important when a project grows and dozens of methods and services start touching transactions.

Take advantage of the convenience of the C# language. (=

Thank you for your attention.

EveIsSim (everything is simple)

Frequently asked question: Is await using for TransactionScope necessary?

The short answer is no, you do not need it.

Although TransationScope supports async/await via TransactionScopeAsyncFlowOption.Enabled, it does not itself implement the IAsyncDisposable interface, and thus does not require await using.

Why does the confusion arise?

Many people assume that supporting async = the need for DisposeAsync(), but TransactionScope uses regular Dispose() even in an asynchronous context.

await using is only required when the object implements IAsyncDisposable. This is not the case.

When then is await using appropriate?

If you wrap TransactionScope in its own wrapper that implements IAsyncDisposable— then await using makes sense.

So, if you use TransactionScope directly — you can and should get by with just using.

DEV Community: EveIsSim

C# How to ambient transaction work under the hood

Structure:

1. TransactionScope and Transaction.Current

2. How exactly does ExecutionContext 'know' about ContextKey through AsyncLocal and what happens when await occurs

Where is AsyncLocal in this?

What does AsyncLocal do under the hood?

3. How Transaction is passed to Npgsql

FINISH: Congratulations, we have figured out how a transaction works within TransactionScope.

4. How do Commit() and Rollback() work

What does IDbTransaction have to do with this?

How then does TransactionScope work without IDBTransaction?

Conclusion

C# Ambient Transactions: What They Are and Why They Matter

Introduction

Problems

Forgotten commit or rollback

Non-processing of exceptions

Conflicts with nesting

Leaky Repository / Violation of Separation of Concerns

Problems with async/await and explicit transaction passing

Solution: How to solve these problems and what does TransactionScopeFactory have to do with it?

How to implement TransactionScopeFactory

Conclusion

Frequently asked question: Is await using for TransactionScope necessary?

2. How exactly does `ExecutionContext` 'know' about `ContextKey` through `AsyncLocal` and what happens when `await` occurs

Where is `AsyncLocal` in this?

What does `AsyncLocal` do under the hood?

3. How `Transaction` is passed to `Npgsql`

How then does `TransactionScope` work without `IDBTransaction`?

Problems with `async/await` and explicit transaction passing