Share via

WS Transaction Flow

  • Article

Download sample

This sample demonstrates the use of a client-coordinated transaction and the client and server options for transaction flow using either the WS-Atomic Transaction or OleTransactions protocol. This sample is based on the Getting Started Sample that implements a calculator service but the operations are attributed to demonstrate the use of the TransactionFlowAttribute with the TransactionFlowOption enumeration to determine to what degree transaction flow is enabled. Within the scope of the flowed transaction, a log of the requested operations is written to a database and persists until the client coordinated transaction has completed - if the client transaction does not complete, the Web service transaction ensures that the appropriate updates to the database are not committed.

NoteNote:

The setup procedure and build instructions for this sample are located at the end of this topic.

After initiating a connection to the service and a transaction, the client accesses several service operations. The contract for the service is defined as follows with each of the operations demonstrating a different setting for the TransactionFlowOption:

[ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]
public interface ICalculator
{
    [OperationContract]
    [TransactionFlow(TransactionFlowOption.Mandatory)]
    double Add(double n1, double n2);
    [OperationContract]
    [TransactionFlow(TransactionFlowOption.Allowed)]
    double Subtract(double n1, double n2);
    [OperationContract]
    [TransactionFlow(TransactionFlowOption.NotAllowed)]
    double Multiply(double n1, double n2);
    [OperationContract]
    double Divide(double n1, double n2); 
}

This defines the operations in the order they are to be processed:

  • An Add operation request must include a flowed transaction.

  • A Subtract operation request may include a flowed transaction.

  • A Multiply operation request must not include a flowed transaction through the explicit NotAllowed setting.

  • A Divide operation request must not include a flowed transaction through the omission of a TransactionFlow attribute.

To enable transaction flow, bindings with the transactionFlow property enabled must be used in addition to the appropriate operation attributes. In this sample, the service's configuration exposes a TCP endpoint and an HTTP endpoint in addition to a Metadata Exchange endpoint. The TCP endpoint and the HTTP endpoint use the following bindings, both of which have the transactionFlow property enabled:

<bindings>
  <netTcpBinding>
    <binding name="transactionalOleTransactionsTcpBinding"
             transactionFlow="true"
             transactionProtocol="OleTransactions"/>
  </netTcpBinding>
  <wsHttpBinding>
    <binding name="transactionalWsatHttpBinding"
             transactionFlow="true" />
  </wsHttpBinding>
</bindings>
NoteNote:

The system-provided netTcpBinding allows specification of the transactionProtocol whereas the system-provided wsHttpBinding uses only the more interoperable WSAtomicTransactionOctober2004 protocol. The OleTransactions protocol is only available for use by Windows Communication Foundation (WCF) clients.

For the class that implements the ICalculator interface, all of the methods are attributed with TransactionScopeRequired property set to true. This setting declares that all actions taken within the method occur within the scope of a transaction. In this case, the actions taken include recording to the log database. If the operation request includes a flowed transaction then the actions occur within the scope of the incoming transaction or a new transaction scope is automatically generated.

NoteNote:

The TransactionScopeRequired property defines behavior local to the service method implementations and does not define the client's ability to or requirement for flowing a transaction.

 
// Service class which implements the service contract.
[ServiceBehavior(TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable)]
public class CalculatorService : ICalculator
{
    [OperationBehavior(TransactionScopeRequired = true)]
    public double Add(double n1, double n2)
    {
        RecordToLog(String.Format(CultureInfo.CurrentCulture, "Adding {0} to {1}", n1, n2));
        return n1 + n2;
    }

    [OperationBehavior(TransactionScopeRequired = true)]
    public double Subtract(double n1, double n2)
    {
        RecordToLog(String.Format(CultureInfo.CurrentCulture, "Subtracting {0} from {1}", n2, n1));
        return n1 - n2;
    }

    [OperationBehavior(TransactionScopeRequired = true)]
    public double Multiply(double n1, double n2)
    {
        RecordToLog(String.Format(CultureInfo.CurrentCulture, "Multiplying {0} by {1}", n1, n2));
        return n1 * n2;
    }

    [OperationBehavior(TransactionScopeRequired = true)]
    public double Divide(double n1, double n2)
    {
        RecordToLog(String.Format(CultureInfo.CurrentCulture, "Dividing {0} by {1}", n1, n2));
        return n1 / n2;
    }

    // Logging method omitted for brevity
}

On the client, the service's TransactionFlowOption settings on the operations are reflected in the client's generated definition of the ICalculator interface. Also, the service's transactionFlow property settings are reflected in the client's application configuration. The client can select the transport and protocol by selecting the appropriate endpointConfigurationName:

// Create a client using either wsat or oletx endpoint configurations
CalculatorClient client = new CalculatorClient("WSAtomicTransaction_endpoint");
// CalculatorClient client = new CalculatorClient("OleTransactions_endpoint");
NoteNote:

The observed behavior of this sample is the same no matter which protocol or transport is chosen.

Having initiated the connection to the service, the client creates a new TransactionScope around the calls to the service operations:

// Start a transaction scope
using (TransactionScope tx =
            new TransactionScope(TransactionScopeOption.RequiresNew))
{
    Console.WriteLine("Starting transaction");

    // Call the Add service operation
    //  - generatedClient will flow the required active transaction
    double value1 = 100.00D;
    double value2 = 15.99D;
    double result = client.Add(value1, value2);
    Console.WriteLine("  Add({0},{1}) = {2}", value1, value2, result);

    // Call the Subtract service operation
    //  - generatedClient will flow the allowed active transaction
    value1 = 145.00D;
    value2 = 76.54D;
    result = client.Subtract(value1, value2);
    Console.WriteLine("  Subtract({0},{1}) = {2}", value1, value2, result);

    // Start a transaction scope that suppresses the current transaction
    using (TransactionScope txSuppress =
                new TransactionScope(TransactionScopeOption.Suppress))
    {
        // Call the Subtract service operation
        //  - the active transaction is suppressed from the generatedClient
        //    and no transaction will flow
        value1 = 21.05D;
        value2 = 42.16D;
        result = client.Subtract(value1, value2);
        Console.WriteLine("  Subtract({0},{1}) = {2}", value1, value2, result);

        // Complete the suppressed scope
        txSuppress.Complete();
    }

    // Call the Multiply service operation
    // - generatedClient will not flow the active transaction
    value1 = 9.00D;
    value2 = 81.25D;
    result = client.Multiply(value1, value2);
    Console.WriteLine("  Multiply({0},{1}) = {2}", value1, value2, result);

    // Call the Divide service operation.
    // - generatedClient will not flow the active transaction
    value1 = 22.00D;
    value2 = 7.00D;
    result = client.Divide(value1, value2);
    Console.WriteLine("  Divide({0},{1}) = {2}", value1, value2, result);

    // Complete the transaction scope
    Console.WriteLine("  Completing transaction");
    tx.Complete();
}

Console.WriteLine("Transaction committed");

The calls to the operations are as follows:

  • The Add request flows the required transaction to the service and the service's actions occur within the scope of the client's transaction.

  • The first Subtract request also flows the allowed transaction to the service and again the service's actions occur within the scope of the client's transaction.

  • The second Subtract request is performed within a new transaction scope declared with the TransactionScopeOption.Suppress option. This suppresses the client's initial outer transaction and the request does not flow a transaction to the service. This approach allows a client to explicitly opt-out of and protect against flowing a transaction to a service when that is not required. The service's actions occur within the scope of a new and unconnected transaction.

  • The Multiply request does not flow a transaction to the service because the client's generated definition of the ICalculator interface does not include a TransactionFlowAttribute. The service's actions again occur within the scope of another new and unconnected transaction.

  • The Divide request does not flow a transaction to the service because again the client's generated definition of the ICalculator interface does not include a TransactionFlowAttribute. The service's actions again occur within the scope of another new and unconnected transaction.

When you run the sample, the operation requests and responses are displayed in the client console window. Press ENTER in the client window to shut down the client.

Starting transaction
  Add(100,15.99) = 115.99
  Subtract(145,76.54) = 68.46
  Subtract(21.05,42.16) = -21.11
  Multiply(9,81.25) = 731.25
  Divide(22,7) = 3.14285714285714
  Completing transaction
Transaction committed
Press <ENTER> to terminate client.

The logging of the service operation requests are displayed in the service's console window. Press ENTER in the client window to shut down the client.

Press <ENTER> to terminate the service.
  Writing row to database: Adding 100 to 15.99
  Writing row to database: Subtracting 76.54 from 145
  Writing row to database: Subtracting 42.16 from 21.05
  Writing row to database: Multiplying 9 by 81.25
  Writing row to database: Dividing 22 by 7

After a successful execution, the client's transaction scope completes and all actions taken within that scope are committed. Specifically, the noted 5 records are persisted in the service's database. The first 2 of these have occurred within the scope of the client's transaction.

If an exception occurred anywhere within the client's TransactionScope then the transaction cannot complete. This causes the records logged within that scope to not be committed to the database. This effect can be observed by repeating the sample run after commenting out the call to complete the outer TransactionScope. On such a run, only the last 3 actions (from the second Subtract, the Multiply and the Divide requests) are logged because the client transaction did not flow to those.

To set up, build, and run the sample

  1. Ensure that you have installed SQL Server 2005 Express Edition or SQL Server 2005. In the service's App.config file, the database connectionString can be set or the database interactions can be disabled by setting the appSettings usingSql value to false.

  2. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

  3. Use the WsatConfig.exe tool from the Windows SDK to enable WCF Transactions network support.

  4. To run the sample in a single- or cross-machine configuration, follow the instructions in Running the Windows Communication Foundation Samples.

If you run the sample across machines, you must configure the Microsoft Distributed Transaction Coordinator (MSDTC) to enable network transaction flow and use the WsatConfig.exe tool to enable WCF transactions network support.

To configure the Microsoft Distributed Transaction Coordinator (MSDTC) to support running the sample across machines

  1. On the service machine, configure MSDTC to allow incoming network transactions.

    1. From the Start menu, navigate to Control Panel, then Administrative Tools, and then Component Services.

    2. Right-click My Computer and select Properties.

    3. On the MSDTC tab, click Security Configuration.

    4. Check Network DTC Access and Allow Inbound.

    5. Click Yes to restart the MSDTC service and then click OK.

    6. Click OK to close the dialog box.

  2. On the service machine and the client machine, configure the Windows Firewall to include the Microsoft Distributed Transaction Coordinator (MSDTC) to the list of excepted applications:

    1. Run the Windows Firewall application from Control Panel.

    2. From the Exceptions tab, click Add Program.

    3. Browse to the folder C:\WINDOWS\System32.

    4. Select Msdtc.exe and click Open.

    5. Click OK to close the Add Program dialog box, and click OK again to close the Windows Firewall applet.

  3. On the client machine, configure MSDTC to allow outgoing network transactions:

    1. From the Start menu, navigate to Control Panel, then Administrative Tools, and then Component Services.

    2. Right-click My Computer and select Properties.

    3. On the MSDTC tab, click Security Configuration.

    4. Check Network DTC Access and Allow Outbound.

    5. Click Yes to restart the MS DTC service and then click OK.

    6. Click OK to close the dialog box.

Footer image

Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.