Title: Transactions with Delegates in C#

The Delegate type is a powerful feature of C#. This article introduces delegates, and shows how they can be used to solve a common problem: ensuring that a series of database updates occur as a single operation by use of a transaction. The solution presented is flexible and minimises duplication of code.

Transactions are essential for maintaining data integrity within computer systems; they seek to guarantee that logically dependent data are amended together in (effectively) a single operation. If an error occurs during that operation, the entire operation fails, and no changes are persisted. Indeed, the ACID () properties of a database rely heavily on correctly implemented transactions^[1].

However, the application developer should not be forced to memorise the details of transaction-handling code in order to perform 'ACID-ic' data updates: transaction code should be transparent, and not interfere with core application logic.

The 'boiler-plate' transaction code (i.e. that which is generic) would best be hidden behind a programming interface that feels 'natural'; ideally, we would have just a single point in the code for handling transactions. With the complex details of transactions hidden, programmers are free to concentrate on application logic.

We need a solution which:

The programmatic nature of transactions can be summarised as:

The BEGIN and COMMIT/ROLLBACK actions represent the 'boiler-plate' code, whereas EXECUTE is dependent on specific data update requirements. Figure 1 shows this relationship.

Here are some possible schemes for using transactions:

The ECMA specification [Specification] for C# introduces the delegate type thus:

A delegate is declared as follows:

public delegate void SomeDelegate(int i);

The delegate SomeDelegate expects a single int parameter and returns no value. Note the keyword delegate. The delegate is invoked as follows:

public class SomeClass
{
  // ...
  // Signature matches that of delegate
  public void SomeMethod(int i) { 
     /* do     something here */ }
  // ...
}
public class AnotherClass
{
  public void CallDelegate(int i)
  {
    SomeClass c = new SomeClass();
    // Wrap the method as a delegate
    SomeDelegate d = new
        SomeDelegate(c.SomeMethod);

       #// Invoke the delegate
    d(i);
  }
}

The delegate acts a typed 'wrapper' around another method. Following instantiation, the delegate object is 'free' of the class in which its wrapped method is defined; the delegate can be treated as (and in fact is) a first-class object in its own right. For example, the delegate can be stored in a container or list of some sort for later processing, if required. So, delegates can be considered as akin to type-safe function pointers (or somewhat analogous to function objects in C++ and Python).

By placing all data update code inside delegate methods, it is possible to trigger all data updates in the same generic way: namely, by invoking the appropriate delegates. The parameters expected by one update method are identical to (or compatible with) those expected by all other update methods. We can thus guarantee that every delegate-based update method has access to the required IDbTransaction reference to use during data updates. Referring back to Figure 1 and the three stages of a transactional data update, we now have a way to link any EXECUTE step (contained within a delegate) to the transaction associated with our BEGIN and COMMIT/ROLLBACK logic. See Figure 4.

However, C# delegates sport another feature which is particularly useful in the context of this articleiii: they have 'multi-cast' abilities. Delegates of the same type can be 'combined' or concatenated (using the overloaded operator +=), producing a new delegate object which will - when invoked - call each of the original delegates in turn. This multi-cast feature can be used to chain together a sequence of data update calls, without the need explicitly to manage the group of delegates in the chain. For example, data updates might be queued on a background thread, and then submitted together as a batch. The code invoking the multi-cast delegate need not know how many individual delegates will be invoked; the invoked delegate handles this automatically.

Delegates will allow us to place our database update code in any class we choose, providing we arrange for the method signature of the update methods to match that of a particular delegate. We can pass into the delegate method the IDbTransaction reference for use during data update.

The following code demonstrates the ideas presented so far in working code.

First we declare our delegate which expects two parameters: sender and args (details follow later).

public delegate void TransactionedOperationDelegate
    (TransactionWrapper sender, 
     TransactionArgs args);

Next we declare a lightweight class to represent a database update operation:

public abstract class TransactionedOperation
{
  public TransactionedOperationDelegate Execute; 
}

We must derive sub-classes from this class, as it is marked abstract, and therefore not instantiable. It holds a delegate reference in its Execute field. We will return to this shortly.

Referring to the basic transaction model (see Potential Solutions, above; Figure 1), we can map out the method required to implement the BEGIN and COMMIT/ROLLBACK logic.^[3]

The various data update operations passed to this method should be treated as a single, atomic operation:

// Make all operations into one atomic operation
public void MakeAtomic
    (TransactionedOperation[] operations)
{
  // Connection is set elsewhere
  this.Connection.Open();
  try
  {
    // BEGIN
    using (IDbTransaction transaction =
        this.Connection.BeginTransaction())
    {
      try
      {
      /// Prepare, then call each operation
       /// Any exceptions will abort the transaction
 
        foreach (TransactionedOperation 
            operation in operations)
          {
            // EXECUTE
            // Invoke the delegate here!
            // i.e. operation.Execute(...)
            // ...
          }
          // COMMIT...
          transaction.Commit();
      }
      catch (Exception exception)
      {
        // ... or ROLLBACK
        transaction.Rollback();

        // TODO: Log the exception here

        // Re-throw exception
        throw;
      }
    }
  }
  finally
  {
    this.Connection.Close();
  }
}

The code as shown implements the BEGIN and COMMIT/ROLLBACK stages of the transaction logic. What is missing is the EXECUTE stage; that is, the invocation of the data update delegate contained in each TransactionedOperation in the operations array. What sort of parameters should we pass to the delegate? We clearly cannot make any sensible generalised assertions about the kind of parameters that might be needed by any given data update method. After all, one of the goals of using delegates is to allow data update code to reside in any arbitrary class; locking down the parameters would negate that flexibility.

The solution is to allow calling code to 'hook on' parameters to the TransactionedOperation parameter, by deriving a sub-class (as mentioned above), and defining new fields^[4] to store the required parameters. For example:

public class CustomTransactionedOperation : TransactionedOperation
{
  // hook arbitrary data...
  public CustomTransactionedOperation
     (CustomDataSet dataSet)
  {
    this.Example = dataSet.ExampleData;
  }
  public readonly string Example;
}

A sub-class CustomTransactionedOperation is derived from the base class TransactionedOperation. A delegate method can now access the Example field of the operation parameter.

Remember that the delegate method takes two parameters: a reference to the TransactionWrapper calling the delegate (the ubiquitous 'sender'), and a parameter of type TransactionArgs. We use this second parameter to pass essential information to the delegate method:

public class TransactionArgs : EventArgs 
    // for convenience
{
  public TransactionArgs(
      IDbConnection connection,
      IDbTransaction transaction,
      TransactionedOperation operation)
  {
    this.Connection = connection;
    this.Transaction = transaction;
    this.Operation = operation;
  }
  public readonly IDbConnection Connection;
  public readonly IDbTransaction Transaction;
  public readonly TransactionedOperation
      Operation;
} 

The CustomTransactionedOperation (with its custom data fields) can be attached to the TransactionArgs parameter, thereby allowing arbitrary information to be passed to the delegate method.

Our code for invoking an operation delegate therefore looks like this:

// Connection is an IDbConnection reference
// transaction is an IDbTransaction reference
// operation is a TransactionedOperation
// reference
TransactionArgs args = new TransactionArgs(
    Connection, transaction, operation);
operation.Execute(this, args);

It might seem slightly strange that we use the operation parameter twice (once to allow us to call the delegate, and a second time to pass custom parameters to the delegate inside args): this is largely for convenience, although also allows for flexibility in the management of update operations.

All that is left now is to prepare the TransactionedOperation and use the TransactionWrapper class to make the data update operation(s) atomic:

// Some arbitrary update code, somewhere...
public void UpdateCustomDetails(CustomDataSet dataSet)
{
  // Connect here to a SQL Server database -
  // could change
  IDbConnection connection = new
      System.Data.SqlClient.SqlConnection
      ( /* connection string */ );
  TransactionWrapper transactionWrapper = new
      TransactionWrapper(connection);

  // Hook the data onto the operation 
  // parameters
  CustomDataUpdate customDataUpdate = new
      CustomDataUpdate();
  CustomTransactionedOperation operation = new
      CustomTransactionedOperation(dataSet);
  operation.Execute += new
      TransactionedOperationDelegate(
      customDataUpdate.UpdateData);
/* chain another delegate here if required:
operation.Execute += new
    TransactionedOperationDelegate(
    SomeOtherDelegateMethod);
*/
  // wrap in transaction
  transactionWrapper.MakeAtomic(operation);
}

The delegate used here is the UpdateData() method of a CustomDataUpdate instance. This is the method that will make use of the IDbTransaction transaction to perform atomic updates. Other update methods that expect the same dataset^[5] can be chained on to the first delegate (shown in comments). Each delegate in the multi-cast chain will receive the same arguments. The UpdateData() method could look like this:

public class CustomDataUpdate
{
// The delegate method
public void UpdateData(TransactionWrapper sender, TransactionArgs args)
{
// Expect special operation type
CustomTransactionedOperation operation = args.Operation as CustomTransactionedOperation;

SqlCommand sqlCommand = new SqlCommand();
sqlCommand.Transaction = args.Transaction as System.Data.SqlClient.SqlTransaction;
sqlCommand.Connection = args.Connection as System.Data.SqlClient.SqlConnection;

// Use custom params from operation object
sqlCommand.CommandText = operation.Example; // etc.

sqlCommand.ExecuteNonQuery();
}
}

Clearly, a production system would employ somewhat more sophisticated logic, but the principle remains!

The code presented above achieves the three goals set out at the beginning of this article: there is no proliferation of transaction code (only a single method, TransactionWrapper.MakeAtomic() holds such code^[6]); data update methods need only use the IDbTransaction reference when calling into the database (no other details are needed); and data update methods can be defined in arbitrary locations, and can require arbitrary data, and all participate in transactions in the same way. See Figure 4.

The scheme provides additional benefits, such as the ability to log all details of a transaction at a single point (in the TransactionWrapper).

Finally, the scheme implements a modified version of the Command Pattern [GoF] with the operation.Execute() method [Command] functionality, and the TransactionWrapper is arguably an implementation of the Façade Pattern [Facade].

In this scheme all database updates take place synchronously within the same IDbConnection context. Use of a single connection is normally essential for transactions (although MS SQL Server allows sharing of transaction space between connections via a special Stored Procedure sp_bindsession - see [Sharing]). Delegates are processed (and data updated) in order of submission to the TransactionWrapper.MakeAtomic() method.

C# delegates also support asynchronous execution, but this scenario has not been tested with the scheme presented here. If the ordering of data updates is not important, then it is possible that asynchronous delegate execution could be made to work with this code, but mixing asynchronous calls with transactions could lead to problems: transactions typically lock (part of) a database during execution, and long-running transactional asynchronous method calls could therefore cause performance bottlenecks.

Any method that performs data update using the technique presented here must use the provided IDbTransaction interface. A deadlock condition is likely to ensue if an application mixes transactional database requests with non-transactional requests. Enforcing this requirement is probably largely down to good practice.

The scheme is not designed to support Distributed Transactions, although could in principle be modified for such a purpose, if a suitable implementation of the IDbTransaction interface were available.

It might be useful to consider providing event notifications at certain stages of the transaction, such as TransactionStarted, TransactionCommitted, TransactionAborted, etc. This would allow listeners to register for notification of these events, probably in the context of the submission to the TransactionWrapper of a group of transactional operations.

The code demonstrated here has been tested only with the Microsoft version of C#, running under the .NET Platform (versions 1.0 and 1.1) [dotNET], but should work with little or no modification under alternative C# implementations, such as Mono [Mono].

This article introduced the C# Delegate type, and showed how it can be used to coordinate and simplify the management of transactional database updates. We have seen a coding scheme using Delegates which keeps tight control of the transaction logic, while also allowing a good deal of flexibility in the definition and location of database update code.

using System;
using System.Collections;
using System.Data;
using System.Data.SqlClient;
namespace Library
{
  #region Delegates
  /// <summary>
  /// A delegate for data updates which
  /// require a transaction i.e. need to be atomic
  /// </summary>
  public delegate void
      TransactionedOperationDelegate(
      TransactionWrapper sender,
      TransactionArgs args);
  #endregion
  #region Operation Parameters Class
  /// <summary>
  /// Base class for all classes implementing
  functionality of parameters for transactioned
  operations
  /// Derive sub-classes from this, and customise
  with fields etc.
  /// In the transactioned operation, check the type
  of the object.
  /// </summary>
  public abstract class TransactionedOperation
  {
    public TransactionedOperationDelegate Execute;
    // cannot use 'event' designation as we are
    calling this multicast from outside the defining
    class
  }
  #endregion
#region Transaction Args
/// <summary>
/// Lightweight class representing arguments for a transactionable operation
/// </summary>
public class TransactionArgs : EventArgs
{
  public TransactionArgs(
      IDbConnection connection,
      IDbTransaction transaction,
      TransactionedOperation operation)
    {
      this.Connection = connection;
      this.Transaction = transaction;
      this.Operation = operation;
    }
    public readonly IDbConnection Connection;
    public readonly IDbTransaction Transaction;
    public readonly TransactionedOperation
          Operation;
  }
  #endregion
  #region TransactionWrapper Class
  /// <summary>
  /// Provides a fairly generic way to wrap any
  operation within a transaction.
  /// The functionality is implemented using
  delegates.
  /// </summary>
  public class TransactionWrapper
  {
    #region .ctor public TransactionWrapper(
          IDbConnection connection)
      {
        if (null == connection)
        {
          throw new ArgumentNullException(
                "connection");
        }
      this.Connection = connection;
    }
    #endregion

    #region Fields
    internal readonly IDbConnection Connection;
    #endregion

    /// <summary>
    /// Makes an operation atomic by allowing
    all data updates it contains easily to share the
    same transaction
    /// </summary>
    /// <param name="operations">An operation
    which should use a single transaction</param>
    public void MakeAtomic(
                TransactionedOperation operation)
    {
      #region Parameter checks
      if (null == operation)
      {
        throw new ArgumentNullException(
              "operation");
      }
      #endregion

      MakeAtomic(new TransactionedOperation[]
            {operation});
    }

    /// <summary>
    /// Makes one or more potentially disparate 
    operations atomic by allowing them easily to 
    share the same transaction
    /// </summary>
    /// <param name="operations">An array of 
    operations which should share the same 
    transaction</param>
    public void MakeAtomic(
          TransactionedOperation[] operations)
    {
      #region Parameter checks
      if (null == operations)
      {
        throw new ArgumentNullException(
              "operations");
      }

      for (int i=0; i < operations.Length;++i)
      {
        TransactionedOperation operation 
              = operations[i];

        if (null == operation)
        {
          throw new ArgumentNullException(
                "operation"
        }
        if (null == operation.Execute)
        {
          throw new ArgumentNullException(
             String.Format(
             "operation.Execute at index {0}",i));
        }
      }
      #endregion

      #region Main functionality
      this.Connection.Open();
      try
      {
        using (IDbTransaction transaction = 
           this.Connection.BeginTransaction())
        {
        try
          {
           /// Prepare, then call the operation
           /// Any exceptions will cause the 
           transaction to be aborted
           /// All relevent objects have been
           checked for nullness prior to this
           /// 
          foreach (TransactionedOperation
                operation in operations)
            { 
              TransactionArgs args = new
                   TransactionArgs(Connection,
                   transaction, operation);
              operation.Execute(this, args);
  // TODO: Log the operation here if required.
            }
            transaction.Commit();
          }
          catch (Exception exception)
          {
            transaction.Rollback();
  // TODO: Log the error here
            throw;
          }
        }
      }
      finally
      {
// Strictly speaking, there is no need for this close here because IDbConnection 
// implements IDisposable - the connection will be closed when the object is Garbage-Collected
        this.Connection.Close();
      }
        #endregion
      }
    }
    #endregion
  }
  namespace Application
  {
    /// <summary>
    /// Example logging interface
    /// </summary>
    public interface ILog
    {
      void Write(DateTime dateTime, 
                IDbConnection connection,
                Library.TransactionArgs args);
    }
    /// <summary>
    /// Some kind of custom data set
    /// </summary>
    public class CustomDataSet : DataSet
    {
      public string ExampleData;
    }
    /// <summary>
    /// 
    /// </summary>
    public class CustomTransactionedOperation
          : Library.TransactionedOperation
    {
      public CustomTransactionedOperation
            (CustomDataSet dataSet)
      {
        this.Example = dataSet.ExampleData;
      }
      public readonly string Example;
    }
    /// <summary>
    /// A base class for data update 
    operations. Provides logging capabilities.
    /// </summary>
    public abstract class BaseDataUpdate
    {
      public BaseDataUpdate (ILog log)
        {
          this.log = log;
        }

      private ILog log;

      private bool loggingEnabled;
      public bool LoggingEnabled
      {
        get { return loggingEnabled; }
        set { loggingEnabled = value; }
      }

      public virtual void UpdateData(
            Library.TransactionWrapper sender,
            Library.TransactionArgs args)
      {
        log.Write(DateTime.Now,
                  sender.Connection, args);
      }
    }

    /// <summary>
    /// An example class which performs data
    updates.
    /// </summary>

    public class 
          CustomDataUpdate : BaseDataUpdate
    {
      public CustomDataUpdate 
            (ILog log) : base (log) { }

      public override void UpdateData
           (Library.TransactionWrapper sender,
            Library.TransactionArgs args)
      {
        CustomTransactionedOperation
              operation = args.Operation as
              CustomTransactionedOperation;
        SqlCommand sqlCommand = 
              new SqlCommand();
        sqlCommand.Transaction =
              args.Transaction as
              System.Data.SqlClient
              .SqlTransaction;
        sqlCommand.Connection 
              = args.Connection as
              System.Data.SqlClient
              .SqlConnection;

        sqlCommand.CommandText 
              = operation.Example;
              /* Some suitable text here */

        sqlCommand.ExecuteNonQuery(); // TODO:
               note the number of rows affected and
               publish via an event 

        base.UpdateData(sender, args);
      }
    }

    /// <summary>
    /// Example class demonstrating a stand
    alone method used in data updates.
    /// </summary>
    public class StandaloneDataUpdate
    {
      /// <summary>
      /// This method does not need custom
      TransactionArgs parameter. 
      /// </summary>
      /// <param name="sender"></param>
      /// <param name="args"></param>
        public void SomeMethod(
              Library.TransactionWrapper sender,
              Library.TransactionArgs args)
        {
          SqlCommand sqlCommand = new SqlCommand();
          sqlCommand.Transaction = args.Transaction
            as System.Data.SqlClient.SqlTransaction;
          sqlCommand.Connection = args.Connection as
            System.Data.SqlClient.SqlConnection;

          sqlCommand.CommandText = ""; 
          /* Some suitable text here */

          sqlCommand.ExecuteNonQuery(); 
        }
      }

      /// <summary>
      /// Some other kid of data set
      /// </summary>
      public class SpecialDataSet : DataSet
      {
        public int MoreExampleData;
      }

      /// <summary>
      /// Example class where the data update method
      is actually part of the class. 
      /// This avoid the need to redefine separate 
      classes for the update method and the 
      parameters but might reduce flexibility.
      /// </summary>
      public class AggregateTransactionedOperation :
            Library.TransactionedOperation
      {
        public AggregateTransactionedOperation 
              (SpecialDataSet dataSet)
        {
          this.Example = dataSet.MoreExampleData;
        }

        public readonly int Example;

        public static void SelfContainedUpdateData
              (Library.TransactionWrapper sender,
               Library.TransactionArgs args)
        { 
            // TODO: Paramter checks

          AggregateTransactionedOperation operation 
                = args.Operation as 
                AggregateTransactionedOperation;

          SqlCommand sqlCommand = new SqlCommand();
          sqlCommand.Transaction = args.Transaction
                 as System.Data.SqlClient.SqlTransaction;
          sqlCommand.Connection = args.Connection as
                 System.Data.SqlClient.SqlConnection;

          sqlCommand.CommandText = "";
          /* Some suitable text here */

          sqlCommand.ExecuteNonQuery();
        }
      }

      /// <summary>
      /// Manager class which co-ordinates access to
     data update operations
    /// </summary>
    public class DataUpdateManager
    {
      private ILog log = null; // Initialise this
            somewhere...

    /// <summary>
    /// 
    /// </summary>
    /// <param name="dataSet"></param>
    public void UpdateCustomDetails
          (CustomDataSet dataSet)
    {
      IDbConnection connection 
            = new System.Data.SqlClient.SqlConnection
            ( /* Connection string goes here*/ );
      Library.TransactionWrapper transactionWrapper =
            new Library.TransactionWrapper(connection);
      // Hook the data onto the operation parameters
      CustomDataUpdate customDataUpdate = 
            new CustomDataUpdate(this.log);
      CustomTransactionedOperation operation =
            new CustomTransactionedOperation(dataSet);
      operation.Execute += 
            new Library.TransactionedOperationDelegate
            (customDataUpdate.UpdateData);

      transactionWrapper.MakeAtomic(operation);
    }

    /// <summary>
    /// Performs multiple updates in a single 
    transaction, with disparate (but presumably 
    related) data.
    /// </summary>
    /// <param name="dataSet1">first data set</param>
    /// <param name="dataSet2">second data set</param>
    public void UpdateMultipleDetails
          (CustomDataSet dataSet1,
           SpecialDataSet dataSet2)
    {
      // Prepare the connection
      IDbConnection connection = 
            new System.Data.SqlClient.SqlConnection
            ( /* Connection string goes here*/ );
      Library.TransactionWrapper transactionWrapper =
            new Library.TransactionWrapper(connection);
      // Hook data for first operation
      CustomDataUpdate customDataUpdate = 
            new CustomDataUpdate(this.log); 
      CustomTransactionedOperation operation1 = 
            new CustomTransactionedOperation(dataSet1);
      operation1.Execute +=
            new Library.TransactionedOperationDelegate
            (customDataUpdate.UpdateData);

      // Hook data for second operation
      AggregateTransactionedOperation operation2 = 
            new AggregateTransactionedOperation
            (dataSet2);
      operation2.Execute += 
            new Library.TransactionedOperationDelegate
            (AggregateTransactionedOperation
            .SelfContainedUpdateData);
      // Collect together the operations and make them
      atomic
      Library.TransactionedOperation[] operations = 
            new Library.TransactionedOperation[] 
            {operation1, operation2};
      transactionWrapper.MakeAtomic(operations);
    }
  }
}