systemsSystem.Transactions was introduced in .Net 2.0.  According to Jim Johnson, who was the architect on the team that created this model, one of the design goals of System.Transactions was to extend the reach of transactions beyond DBMS (Database Management Systems) by allowing creation of transactional resources. Another goal was to simplify the programming model and the interface to use transactions.

System.Transactions.TransactionScope provides an implicit programming model in which the transactions are automatically managed by the infrastructure. It provides a simple mechanism for you to specify a code block to participate in a transaction. TransactionScope reduces the complexity of code that need to use transactions and it allows existing transaction providers to be retrofitted to participate in this programming model. Nested transaction work transparently. Disparate transaction providers can participate in a transaction without increasing the complexity of your code. No wonder TransactionScope is so popular!

I have used TransactionScope countless times in the past, but it never occurred to me that there is such an elegant mechanism implemented under the hood. It proves that the team that worked on System.Transactions met its goals. Recently, while working on a project using TransactionScope, I realized that I don’t fully understand how TransactionScope really works. Look at it a little bit closely and you too will realize that it seems almost magical.

Without TransactionScope, you have to manage the transaction yourself. Your code is intimately aware of the transaction.

  1. private static void ExecuteSqlTransaction(string connectionString)
  2. {
  3.     using (SqlConnection connection = new SqlConnection(connectionString))
  4.     {
  5.         connection.Open();
  7.         SqlCommand command = connection.CreateCommand();
  9.         SqlTransaction transaction;
  11.         // Start a ransaction.
  12.         transaction = connection.BeginTransaction(“MyTransaction”);
  13.         command.Connection = connection;
  14.         command.Transaction = transaction;
  16.         try
  17.         {
  18.             command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (1234, ‘ValueB’)”;
  19.             command.ExecuteNonQuery();
  21.             command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (5678, ‘Another Value’)”;
  22.             command.ExecuteNonQuery();
  24.             // Attempt to commit the transaction.
  25.             transaction.Commit();
  27.             Console.WriteLine(“Both records are written to database.”);
  28.         }
  29.         catch (Exception ex)
  30.         {
  31.             // Log exception
  33.             // Attempt to roll back the transaction.
  34.             try
  35.             {
  36.                 transaction.Rollback();
  37.             }
  38.             catch (Exception exception)
  39.             {
  40.                 // This catch block will handle any errors that may have occurred
  41.                 // on the server that would cause the rollback to fail.
  42.             }
  43.         }
  44.     }
  45. }

Now take a look at the code below that uses TransactionScope. Compare this to the code above.

  1. private static void ExecuteSqlTransactionUsingTransactionScope(string connectionString)
  2. {
  3.     using (TransactionScope scope = new TransactionScope())
  4.     {
  5.         using (SqlConnection connection = new SqlConnection(connectionString))
  6.         {
  7.             connection.Open();
  9.             SqlCommand command = connection.CreateCommand();
  11.             command.Connection = connection;
  13.             command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (1234, ‘ValueB’)”;
  14.             command.ExecuteNonQuery();
  16.             command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (5678, ‘Another Value’)”;
  17.             command.ExecuteNonQuery();
  19.             Console.WriteLine(“Both records are written to database.”);
  20.         }
  22.         scope.Complete();
  23.     }
  24. }

This will work even if the two sql commands are executed in two different methods!

  1. private static void ExecuteTwoMethodsOpeningTwoConnections(string connectionString)
  2. {
  3.     using (TransactionScope scope = new TransactionScope())
  4.     {
  5.         ExecuteCommandA(connectionString);
  6.         ExecuteCommandB(connectionString);
  8.         Console.WriteLine(“Both records are written to database transactionally.”);
  9.         scope.Complete();
  10.     }
  11. }
  14. private static void ExecuteCommandA(string connectionString)
  15. {
  16.     using (SqlConnection connection = new SqlConnection(connectionString))
  17.     {
  18.         connection.Open();
  20.         SqlCommand command = connection.CreateCommand();
  22.         command.Connection = connection;
  24.         command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (1234, ‘ValueB’)”;
  25.         command.ExecuteNonQuery();
  26.     }
  27. }
  29. private static void ExecuteCommandB(string connectionString)
  30. {
  31.     using (SqlConnection connection = new SqlConnection(connectionString))
  32.     {
  33.         connection.Open();
  35.         SqlCommand command = connection.CreateCommand();
  37.         command.Connection = connection;
  39.         command.CommandText = “Insert into MyTable(ColumnA, ColumnB) VALUES (5678, ‘Another Value’)”;
  40.         command.ExecuteNonQuery();
  41.     }
  42. }

Note that the two methods have no transaction related code at all. A new connection is opened in each one of the two methods : ExecuteCommandA and ExecuteCommandB and sql commands are executed on those two connections. The changes are made by both commands will be rolled back if the second command fails. Note that none of the connections are explicitly associated with any transaction. How does this work? How does SqlConnection know about the implicit transaction? How does TransactionScope provides an instance of System.Transaction to the code encompassed by the TransactionScope block?

TransactionScope does its magic by providing and managing an “ambient” transaction, and System.Data.SqlClient is a System.Transaction resource manager. Which means that it is aware of the ambient transaction. Anyone can write an ambient transaction aware resource provider. The magic happens with the cooperation of the two, the ambient transaction provided by the TransactionScope and the implementation in System.Data.SqlClient that detects and honors the ambient transaction.

The ambient transaction provided by the TransactionScope is a thread-static (TLS) variable. It can be accessed with static Transaction.Current property. Here is the TransactionScope code at referencesource.microsoft.com. ThreadStatic ContextData, contains the CurrentTransaction.

When a SqlConnection is opened, it detects this ambient transaction and enlists itself in this transaction. If another connection is opened in another method while the transaction scope has not been disposed yet, it will also enlist itself. I am simplifying this to make a point, but whether a new transaction is created or the current ambient one is used, depends on the TransactionScopeOption.

So remember, the connection must be opened inside the TransactionScope block for it to enlist in the ambient transaction automatically. If the connection was opened before that, it will not participate in the transaction. Read this last sentence again. This is your only warning! TransactionScope or SqlConnection does not know or care and it will not warn you. This is especially important if have a pattern for sharing a connection instance among your methods (which is not a good idea anyway).

If you are wondering whether MSDTC (Microsoft Distributed Transaction Coordinator) will be used if the two connections are pointing to two different databases, then the answer is yes, absolutely. The transactions are promoted automatically to distributed transactions when needed and the MSDTC becomes involved. TransactionScope does not obviate the need for MSDTC. Make sure MSDTC is enabled on the servers where your code is executing, if your transactions will be spanning more than one database.

Remember that Transaction.Current is a thread static variable. If your code is executing in a multi-threaded environments, you may need to take some precautions. The connections that need to participate in ambient transactions must be opened on the same thread that creates the TransactionScope that is managing that ambient transaction.

Lastly, if you are using async/await inside the TransactionScope block, you should know that it does not work well with TransactionScope and you might want to look into new TransactionScope constructor in .NET Framework 4.5.1 that accepts a TransactionScopeAsyncFlowOption. TransactionScopeAsyncFlowOption.Enabled option, which is not the default, allows TransactionScope to play well with asynchronous continuations.

Hope this demystifies the magic of TransactionScope for you.