Transaction Control
Building Distributed Applications with .NET
Priya Dhawan
Microsoft Developer Network

November 2001

Summary: This article describes how to run local and distributed transactions in your Microsoft .NET applications. (14 printed pages)

Contents
Introduction
Local and Distributed Transactions
Database Transactions
Manual Transactions
Automatic Transactions
Conclusion

Introduction
A transaction is a series of operations performed as a single unit of work. By binding a set of related operations together in a transaction, you ensure the consistency and reliability of the system despite any errors that occur. All operations in a transaction must complete successfully in order to make the transaction successful.

A transaction has a beginning and an end that specify its boundary within which it can span processes and machines. All resources within a transaction boundary participate in the same transaction. To maintain consistency across resources within a transaction boundary, a transaction must exhibit ACID properties, which are Atomicity, Consistency, Isolation, and Durability. See Processing Transactions in them Microsoft .NET Framework SDK and Transaction Processing in the Microsoft Platform SDK for details on transaction processing fundamentals.

In this article, we will show how you can run local and distributed transactions in your Microsoft .NET applications.

Local and Distributed Transactions
A local transaction is one whose scope is a single transaction-aware data resource, such as a Microsoft® SQL Server™ database or MSMQ message queue. For example, a single database system can enforce the ACID rules when it holds all the data involved in a transaction. In the case of SQL Server, there is an internal transaction manager that provides commit and rollback behavior.

Distributed transactions can span heterogeneous transaction-aware data resources and may include a wide range of activities such as retrieving data from a SQL Server database, reading messages from a Message Queue Server, and writing to other databases. Programming of distributed transactions is simplified by software that coordinates commit and abort behavior and recovery across several data resources. Microsoft Distributed Transaction Coordinator (DTC) is one such technology. It implements a two-phase commit protocol that ensures the transaction outcome is consistent across all data resources involved in a transaction. DTC only supports applications that have implemented compatible interfaces for management of transactions. These applications are referred to as Resource Managers (see Distributed Transactions in the .NET Framework Developer's Guide for more information on this topic) and many are currently available, including MSMQ, Microsoft SQL Server, Oracle, Sybase, and others.

Database Transactions
Invoking a stored procedure that wraps required operations within the BEGIN TRANSACTION and COMMIT/ROLLBACK TRANSACTION statements yields the best performance by allowing you to run the transaction in a single round-trip to the database server. Database transactions also support nested transactions, which means you can start a new transaction from within an active transaction.

In the following code snippet, the BEGIN TRANSACTION statement begins a new transaction. You can end a transaction either by committing changes to the database using the COMMIT TRANSACTION statement or by undoing all the changes if any error occurs using the ROLLBACK TRANSACTION statement:

CREATE PROCEDURE Proc1
…
AS
-- Begin the transaction
BEGIN TRANSACTION
-- Do transaction operations
…
-- Check for any Error
If @@Error <> 0
-- Rollback the Transaction
ROLLBACK TRANSACTION
…
-- Commit the Transaction
COMMIT TRANSACTION

The next stored procedure accepts an XML representation of an Order as an input parameter. To make appropriate insertions into the Orders and OrderDetails tables, the stored procedure loads and parses the XML using the sp_xmlpreparedocument system stored procedure. As you see in the code, the stored procedure wraps all the operations in an explicit transaction so that if any of the operations fail to execute all the changes made are rolled back.

Note that the procedure sets XACT_ABORT to ON, which specifies that the SQL server will automatically roll back the transaction in case any of the statements fail to complete.

CREATE PROCEDURE InsertOrder
@Order NVARCHAR(4000) = NULL
, @OrderId int Output
AS
SET NOCOUNT ON
DECLARE @hDoc INT
DECLARE @PKId INT
-- Specify that the SQL Server automatically rolls back the current
-- transaction if a Transact-SQL statement raises a run-time error.
SET XACT_ABORT ON
-- Begin the transaction
BEGIN TRANSACTION
-- Load and Parse the incoming XML represeting an Order into an
-- XMLDocument
EXEC sp_xml_preparedocument @hDoc OUTPUT, @Order
-- Select order header from the Order node in the XMLDocument and
-- insert it into the Orders table
INSERT Orders(CustomerId,
OrderDate,
ShipToName,
ShipToAddressId,
OrderStatus)
SELECT CustomerId, CONVERT(DateTime,OrderDate), ShipToName,
ShipToAddressId, OrderStatus
FROM OPENXML(@hDoc, '/NewDataSet/Orders')
WITH ( CustomerId int 'CustomerId',
OrderDate nvarchar(23) 'OrderDate',
ShipToName nvarchar(40) 'ShipToName',
ShipToAddressId int 'ShipToAddressId',
OrderStatus int 'OrderStatus')
-- Select the OrderId of the Order just inserted into the Orders table
-- to use it while inserting order details
SELECT @PKId = @@IDENTITY
-- Select order details from the Details node in the XMLDocument and
-- insert them into the OrderDetails table
INSERT OrderDetails (OrderId,
ItemId,
UnitPrice,
Quantity)
SELECT @PKId as OrderId, ItemId, UnitPrice, Quantity
FROM OPENXML(@hDoc, '/NewDataSet/Details')
WITH (ItemId int 'ItemId',
UnitPrice money 'UnitPrice',
Quantity int 'Quantity')
-- Set the Output parameter
Select @OrderId = @PKId
-- Commit the transaction
COMMIT TRANSACTION
EXEC sp_xml_removedocument @hDoc
RETURN 0
GO

Although it provides good performance, you need to code in Transact SQL, which is not as easy to code in as a .NET-compatible language.

Manual Transactions
A manual transaction allows you to explicitly control the transaction boundary with explicit instructions to begin and end the transaction. This model also supports nested transactions that allow you to start a new transaction from within an active transaction. The trade off for this control is that there is an extra burden on you to enlist data resources with the transaction boundary and coordinating these data resources. There is no built-in support for distributed transactions and so it will be a lot of responsibility if you choose to control a distributed transaction manually; you will need to control every connection and resource enlistment, and provide implementation to maintain ACID properties of the transaction.

ADO.NET manual transactions
Both Microsoft ADO.NET data providers enable manual transactions by providing a set of objects that create a connection to the data store, begin a transaction, commit or abort the transaction, and finally close the connection. We will be using ADO.NET SQL managed provider for our examples.

To perform operations within a single transaction, you need to create an SQLTransaction object, begin the transaction using an SQLConnection object, ensure our database interaction occurs within a transaction, and commit or abort the transaction. The SQLTransaction object provides a variety of methods and properties to control a transaction. You can commit changes made to the database using the Commit method if every operation in the transaction completed successfully. To rollback changes use the Rollback method of the SQLTransaction object.

Note The Transaction property of the Command object must be set to an already started transaction for it to execute within the transaction.
Visual Basic .NET

Dim conn as SQLConnection
Dim cmd as SQLCommand
Dim txn As SQLTransaction
conn = New SQLConnection("ConnString")
cmd = New SQLCommand
' Open a conection
conn.Open()
' Begin a transaction
txn = conn.BeginTransaction()
' Set the Transaction in which the command executes
cmd.Transaction = Txn
…

Visual C# .NET

SQLConnection Conn = New SQLConnection("ConnString");
SQLCommand Cmd = New SQLCommand;
// Open a connection
Conn.Open();
// Begin a transaction
SQLTransaction Txn = Conn.BeginTransaction();
// Set the Transaction in which the command executes
Cmd.Transaction = Txn;
…

In the following example, we execute two SQL commands within the boundary of a transaction. The first command inserts the order header of an order into the Orders table and returns the OrderId of the newly inserted order, which is used by the second command to insert the detail of the same order into the OrderDetails table. The transaction is aborted if either of the two commands fails to execute thereby preventing the rows from being added to the database.

Visual Basic .NET

Dim conn As SqlConnection
Dim cmd As SqlCommand
Dim tran As SqlTransaction
' Create a New Connection
conn = New SqlConnection("ConnString")
' Open the Connection
conn.Open()
' Create a new Command object
cmd = New SqlCommand()
' Create a new Transaction
tran = conn.BeginTransaction
' Set the Transaction within which the Commands execute
cmd.Transaction = tran
Try
' Insert the Order header
' Set the Command properties
With cmd
.CommandType = CommandType.StoredProcedure
.CommandText = "InsertOrderHeader"
.Connection = conn
' Add input and output parameters
.Parameters.Add("@CustomerId", SqlDbType.Int)
.Parameters("@CustomerId").Direction = ParameterDirection.Input
…
' Set the parameter values
.Parameters("@CustomerId").Value = 1
…
' Execute the command
.ExecuteNonQuery()
' Get the OrderId of the newly selected order header
OrderId = .Parameters("@OrderId").Value
' Clear the parameters for the next command
.Parameters.clear()
End With

' Insert the Order Details
' Set Command properties
With cmd
.CommandType = CommandType.StoredProcedure
.CommandText = "InsertOrderDetail"
.Connection = conn
' Add parameters
.Parameters.Add("@OrderId", SqlDbType.Int)
.Parameters("@OrderId").SourceColumn = "OrderId"
.Parameters("@OrderId").Direction = ParameterDirection.Input
…
' Set the parameter values
.Parameters("@OrderId").Value = OrderId
.Parameters("@ItemId").Value = 100
…
' Execute the command
.ExecuteNonQuery()
' Repeat the above few lines for each order detail
End With

' Commit the Transaction
tran.Commit()
Catch
' Rollback the Transaction
tran.Rollback()
Finally
' Cleanup Code
' Close the Connection
conn.Close()
End Try

As you see in the above code fragment, the two commands are being executed as part of a single transaction. If either of them fails, the transaction aborts and any changes made to the database are rolled back. Wrapping the code in a try/catch/finally block ensures that your transaction executes correctly; the transaction is committed at the very end of the try block when both the commands have been executed successfully. Any exception thrown is caught in the catch block where the transaction is aborted to undo changes made within the transaction.

Controlling a transaction through ADO.NET objects results in less efficient locking as compared to using explicit transactions in stored procedures. The reason is that an ADO.NET manual transaction takes at least as many round trips to the DBMS as there are operations to execute within the transaction in addition to trips that begin and end the transaction. You keep hold of locks while calls are sent back and forth between your ADO.NET code and the database server.