Building transactional Web services with WebSphere Application Server and Microsoft .NET using WS-AtomicTransaction

This article describes how to create a transactional Web service provider using IBM® Rational® Application Developer for WebSphere® V7, and a corresponding service consumer using the Microsoft .NET 3.0 Software Development Kit. It walks you through the steps required for deployment to WebSphere Application Server V6.1 and Microsoft™ .NET™ Framework, including troubleshooting hints and tips for both platforms.

Share:

Billy Lo (blo@ca.ibm.com), Senior IT Architect, IBM

Author1 photoBilly Lo is a Senior I/T Architect with IBM Global Business Services in Toronto, Canada. He consults with customers on using Web services technologies to build service-oriented business applications using heterogeneous platforms such as WebSphere, CICS, Microsoft .NET, BEA WebLogic and Apache Axis. Billy is a frequent speaker at conferences on Web services development and interoperability. You can reach him at blo@ca.ibm.com.



11 July 2007

Introduction

In August 2005, IBM, Microsoft, IONA®, BEA® and partners jointly released a family of Web services specifications that enables applications to invoke Web services in a transactional fashion. These specifications include:

  • WS-AtomicTransaction (WS-AT), which handles short-lived transactional activities. As with other transactional systems such as Java™ Transaction API (JTA) or Customer Information Control System (CICS), you can take advantage of WS-AT to ensure that all resource updates made by Web services partcipants are either completed or rolled back as one unit of work.
  • WS-BusinessActivity (WS-BA), which addresses coordination of long-running activities and supports the concept of compensation.
  • WS-Coordination (WS-Coor), which provides the underlying mechanism for the creation and exchange of transaction context.

WebSphere Application Server V6 and V6.1, WebSphere Process Server V6, CICS Transaction Server V3.1 and Microsoft .NET 3.0 Windows Communication Framework (WCF) support WS-AT.

This article explains the basic concepts of WS-AT and guides you through the key steps in building transactional Web services between WebSphere Application Server and Microsoft .NET 3.0. It is intended for Web services developers, architects and administrators, who want to build and deploy transactional Web services across different platforms. You should have basic understanding of Java programming, Web services development, WSDL and SOAP.


The big picture

WS-AT is typically used to coordinate activities performed by Web services participants so that all updates are completed in a single unit of work. For example, a retail business may want to ensure that inventory is available and payment is received before committing to a shipment. The InventoryService, PaymentService and ShipmentService can reside in different systems with heterogeneous technology stacks or even across organizational boundaries. WS-AT ensures that invocation of these three Web services is performed in a transactional fashion, providing Atomicity, Consistency, Isolation and Durability (ACID) semantics to the application.

Because the underlying platforms provide this quality of service, Web services developers don't need to develop custom error handling logic or issue manual reversals in case of failures or timeout conditions.

Figure 1 shows an example in which the order processing functionality (SubmitOrder.jsp) updates multiple systems using Web services calls to three service providers: InventoryService, PaymentService and ShipmentService. These service providers are running on different operating environments accessing different databases and/or resources. With the help of WS-AT, all updates are coordinated by a global transaction.

Figure 1. Example order processing with transactional support
Figure 1. Example order processing with transactional support

Prerequisites

To complete the example in this article, you need the following software installed on a Microsoft Windows™ XP platform.

WS-AT is operating system and platform neutral. For example, you can use WebSphere Application Server running on other distributed platforms such as Linux, AIX or zOS to interoperate transactionally with Microsoft .NET running on Microsoft platforms such as Windows Vista, Windows Server 2003 or Windows XP.

WebSphere Application Server V6 users must use WebSphere Application Server V6.0.2.19 (or higher) to interoperate with Microsoft .NET using WS-AT.


Getting started

Figure 2 summarizes the high-level steps for building transactional Web service consumers and providers.

Figure 2. High-level steps for enabling WS-AT between WebSphere and .NET
Figure 2. High-level steps for enabling WS-AT between WebSphere and .NET

These steps are described in the following sections.


Step 1: Develop a transactional Web service provider using Rational Application Developer

The example in this article follows a top-down approach. First, we'll create a WSDL document to describe the service interface HelloWorldTX, then we'll generate a service implementation, and finally we'll introduce transactional support to the service endpoint.

Create a WSDL document

To host the service provider, you need to create a Java® 2 Platform, Enterprise Edition® (J2EE) enterprise application project with the appropriate Web module by doing the following:

  1. Enable J2EE and Web services developer capabilities in Rational Application Developer by selecting Windows => Preferences => General => Capabilities, and check Web Developer and Web service Developer.
  2. Create a new J2EE project by selecting File => New => Project. Select J2EE – Enterprise Application Project and click Next.
  3. Enter HelloWorldTX as the Project Name, select WebSphere Application Server v6.1 as the Target Runtime, then click Next.
  4. Accept the defaults for Project Facets and click Next.
  5. Create a new Web module by selecting New Module. Uncheck Application Client Module, EJB Module and Connector Module, then click Finish.
  6. Click Finish to complete the creation of J2EE project
  7. In the J2EE perspective, expand the new HelloWorldTX project, right-click WebContent and select New => Other = > Web Services => WSDL and click Next
  8. Enter HelloWorldTX.wsdl as the File Name and click Next and Finish to accept the defaults
  9. Download the sample HelloWorldTX.wsdl and cut and paste its content into your newly created HelloWorldTX.wsdl file.

Generate a service implementation

To generate a service implementation, complete the following steps:

  1. Right-click HelloWorldTX.wsdl, select Web Services => Generate Java bean skeleton and click Finish.
  2. Modify the generated HelloWorldTXSOAPImpl.java to return “Hello, ” + in;.

Enable WS-AT transactional support

In WebSphere Application Server, WS-AT transactional support is specified using deployment descriptors. No special Java coding is necessary.

  1. Expand HelloWorldTXWeb => WebContent => WEB-INF and open web.xml.
  2. On the Servlets tab, select the HelloWorldTXSOAPImpl servlet
  3. Scroll down the list of options on the right. Under WebSphere Extensions => Global Transaction, check Execute using Web Services Atomic Transaction on incoming requests.
  4. Press Ctrl+S to save the changes to the Web deployment descriptor (web.xml).

    This instructs the WebSphere runtime to process any received WS-AT context and dispatch the application component under a global transaction that is coordinated by the external requester.

At this point, your HelloWorldTX Web service is ready for consumption.


Step 2: Develop a transactional Web service consumer using Microsoft .NET Framework 3.0

Microsoft .NET Framework 3.0 supports transactional Web services. Your service consumer can be a standalone .NET application or a Web application running in Internet Information Services (IIS.) In this article, we'll build a standalone C# client application that accesses the HelloWorldTX service in WebSphere.

The following steps describe how to build your C# client from scratch using the WSDL document. You can also download the pre-built .NET client provided with this article.

  1. Start a Windows SDK command shell by selecting Windows SDK => CMD Shell.
  2. Create a working directory to store your client source code (for example, C:\HelloWorldTXConsoleClient) and change to that directory.
  3. Copy HelloWorldTX.wsdl from your Rational Application Developer workspace to your working directory.
  4. Generate a C# proxy class by issuing the command : svcutil HelloWorldTX.wsdl.
  5. Add the TransactionFlowAttribute attribute to the generated HelloWorldTX.cs source file as shown in Listing 1:
    Listing 1. HelloWorldTX Interface in C#
    public interface HelloWorldTX
    {
        
        // CODEGEN: Generating message contract since element name in from 
    namespace is not marked nillable
    
    [System.ServiceModel.TransactionFlowAttribute(System.ServiceModel.Trans
    actionFlowOption.Mandatory)]
    
    [System.ServiceModel.OperationContractAttribute
    Action="http://helloworldtx.example.wsat.ibm.com/
    sayHello", ReplyAction="*")]
    	sayHelloResponse sayHello(sayHelloRequest request);
  6. Create a simple HelloWorldTXConsoleClient C# class to trigger the invocation of the Web service operation. Listing 2 shows a sample HelloWorldTXConsoleClient.cs.
    Listing 2. HelloWorldTXConsoleClient.cs
    using System;
    using System.Transactions;
    
    namespace HelloWorldTXConsoleClient
    {
        class HelloWorldTXConsoleClient
        {
            static void Main(string[] args)
            {
                // start transaction
    
                using (TransactionScope transScope = new 
    TransactionScope(TransactionScopeOption.RequiresNew))
                
                {
                    HelloWorldTXClient proxy = new HelloWorldTXClient();
                    Console.WriteLine("Invoking HelloWorldTX service...");
    
                    // invoke HelloWorldTX running on WebSphere with WS-AT
    
                    String response = proxy.sayHello("World");
                    transScope.Complete();
    
                    Console.WriteLine("Transaction completed successfully.
    Response = " + response);
                }
            }
  7. Create a HelloWorldTXConsoleClient.exe.config file, as shown in Listing 3, for specifying the client endpoint and transfer protocols. A custom binding is required for this scenario, instead of the standard wsHttpBinding in .NET, because wsHttpBinding uses SOAP 1.2 by default. WebSphere Application Server V6.1, on the other hand, supports SOAP 1.1.
    Listing 3. HelloWorldTXConsoleClient.exe.config
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
        <system.serviceModel>
            <bindings>
                <customBinding>
                    <binding name="Soap11AddressingBinding" transactionFlow="true">
                       <textMessageEncoding messageVersion="Soap11WSAddressing10" />
                       <transactionFlow transactionProtocol=
    			"WSAtomicTransactionOctober2004"/>                  
                       <httpTransport/>
                    </binding>
                </customBinding>
            </bindings>
            <client>
                <endpoint address="http://localhost:9080/
    			HelloWorldTXWeb/services/HelloWorldTXSOAP"
                    binding="customBinding"
                    bindingConfiguration="Soap11AddressingBinding" 
                    contract="HelloWorldTX" name="HelloWorldTXSOAP" />
            </client>
        </system.serviceModel>
    </configuration>
  8. Compile all source files by entering the following command at the Windows SDK command shell prompt:
    csc HelloWorldTX.cs HelloWorldTXConsoleClient.cs /reference: "%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\System.ServiceModel.dll"; "%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\System.Runtime.Serialization.dll".
  9. Confirm that the HelloWorldTXConsoleClient.exe is produced successfully.

Step 3: Enable network access in Microsoft Distributed Transaction Coordinator (MSDTC)

In Windows XP, support for distributed transaction and WS-AT is disabled by default. To enable it, do the following:

  1. Install the Update for Windows Communication Foundation (KB912817).
  2. Install the WS-AtomicTransaction Configuration MMC Snap-in (WsatUI.dll) (WsatUI.dll), and register the DLL by entering the following command:
    C:/> regasm /codebase "%PROGRAMFILES%\Microsoft SDKs\Windows\v6.0\Bin\WsatUI.dll"
  3. Enable DTC network access by doing the following:
    • Select Control Panel => Administrative Tools => Component Services. Under Console Root, expand Component Services => Computers.
    • Right-click My Computer in MMC, select Properties, then click the MSDTC tab.
    • Click Security Configuration.
    • In the Security Configuration dialog, check the following options, as shown in Figure 3: Network DTC Access, Allow Remote Clients, Allow Inbound, Allow Outbound, Enable TIP Transactions, Enable XA Transactions.
      Figure 3. Security configuration
      Figure 3. Security configuration
    • Click OK and then OK again to exit.

Step 4: Set up WebSphere security, SSL certificates and transaction service for WS-AT message exchange

WebSphere Application Server supports either secure or non-secure exchange of transaction protocol messages (for example, Register, Prepare, Commit, Rollback.) However, Microsoft .NET requires the protocol messages to be secured using SSL mutual authentication. This means that you need to configure SSL security and set up certificates before WS-AT can operate across the two platforms.

In a production environment, a certificate from a recognized certificate authority would be used for each participant. However, for the sake of simplicity in this example, we'll produce a self-signed certificate for both WebSphere and .NET. To do this, complete the following steps:

  1. Enable WebSphere Global Security using the WebSphere administrative console. Under Security => Secure administration, applications, and infrastructure, click Security Configuration Wizard.
    • Check Enable Application Security and click Next.
    • Select Local Operating System and click Next.
    • Enter <your-operating-system-userid> as the Primary administrative user name and click Next.
    • Click Finish.
  2. Create a self-signed certificate using the administrative console as follows:
    • Select Security => SSL certificate and key management => Key Store and Certificates => NodeDefaultKeyStore => Personal certificates => Create a self-signed certificate.
    • Specify the following, then click OK:
      • Alias = <your_hostname>
      • Common Name = <your_hostname>. (The common name on the certificate must match the DNS name of your machine with suffix.)
      • Organization = <your_organization_name>
    • Click Save Changes to Master Configuration.
  3. To assign the newly created certificate as the default, select Security => SSL certificate and key management > SSL configurations => NodeDefaultSSLSettings, then select the newly created certificates for Default server certificate alias and Default client certificate alias. Then click OK.
  4. Import the signer certificate into the trust store by selecting Security => SSL certificate and key management => Key stores and certificates, then selecting both NodeDefaultKeyStore and NodeDefaultTrustStore and clicking Exchange signers.
  5. Select the newly created certificate and add it to the NodeDefaultTrustStore by selecting it and clicking Add, then OK.
  6. Configure the WebSphere transaction service, by doing the following:
    • Select Servers => Application servers => server1 => Container Services => Transaction Service
    • Uncheck Enable protocol security. This must be disabled for .NET interoperability. Protocol messages will still be secured using SSL transport-level security, but role-based authorization of received protocol messages is disabled. Role-based authorization of transaction protocol messages is supported only for WebSphere-to-WebSphere interactions.
    • For HTTPS proxy prefix, enter https://<your_websphere_server_hostname>:9443. If you are not using default ports (as configured for the WCInboundDefaultSecure Web container transport chain), replace 9443 with your SSL Inbound port. Note: If the WebSphere server is behind an HTTPS proxy, you should use the host name of the HTTPS proxy.
    • Click OK.
  7. Optionally, enable WebSphere Web services message tracing to verify that WS-AT is working properly. Select Troubleshooting => Logs and Trace => server1 => Diagnostic Trace => Change Log Level Details, then add the following trace specification: com.ibm.ws.webservices.trace.MessageTrace=finest and click OK.
  8. Save your changes and stop WebSphere Application Server.
  9. If you're using Rational Application Developer or the WebSphere Application Server Toolkit, open your server configuration and expand the Security section. Check Security is enabled on this server and enter the user ID and password you used to enable WebSphere Global Security. Press Ctrl+S to save the changes.
  10. Restart WebSphere Application Server.

Step 5: Import SSL certificates and configure WS-AT in Windows XP

MSDTC is responsible for transaction management and the handling of WS-AT messages. You can configure MSDTC by following the steps below. For WS-AT to work, you must import your SSL certificate into the LocalMachine Certificate Store, instead of the User Certificate Store, because the MSDTC process operates in a different security context.

  1. Select Start => Run => mmc to open the Microsoft Management Console.
  2. In MMC, select File => Add/Remove Snap-in => Add => Certificates => Add => Computer Account => Next => Local Computer => Finish => Close => OK.
  3. Expand Certificates, Personal
  4. Select Action, All Tasks, Import…, Next, Browse…
    • Filename = %WAS_HOME%\profiles\<your-server>\config\cells\<your-cell>\nodes\<your-node>\key.p12
    • Password = WebAS
    • Place them into the Personal Certificate Store, Press Next and then Finish
  5. Expand Certificates, Trusted Root Certificate Authority and repeat Step 4 above to import the certificate into the trust CA store as well
  6. Close MMC
  7. Click Start => Control Panel => Administrative Tools => Component Services => Computers => My Computer.
  8. Right-click My Computer, select Properties, then select the WS-AT tab. On the WS-AT tab, do the following:
    • Check Enable WS-Atomic Transaction network support.
    • In the Endpoint certificate field, click Select and choose the newly imported certificate (with your hostname as alias).
    • In the Authorized certificates field, click Select, as shown in Figure 4.
      Figure 4. Configure WS-AT
      Figure 4. Configure WS-AT
    • Check the newly created certificate and click OK, as shown in Figure 5.
      Figure 5. Select Authorized Certificate dialog
      Figure 5. Select Authorized Certificate dialog
  9. Click OK and restart MSDTC as prompted.

Step 6: Test the end-to-end message flows

Now you're ready to test the end-to-end message flows between .NET and WebSphere. Start your .NET client application by running HelloWorldTXConsoleClient.exe from the command prompt. If everything works properly, you should see the Hello, World response message coming back.

To verify that a transactional message exchange has taken place, open %WAS_HOME%/profiles/<your-server>/logs/server1/trace.log, and search for wsat to find the detailed trace of WS-AT message exchanges. Figure 6 shows the entire sequence of message flows.

Figure 6. Detailed message flow between .NET and WebSphere
Figure 6. Detailed message flow between .NET and WebSphere

As you can see, multiple SOAP message exchanges are required to process transactional Web service invocations. In this example, application SOAP messages and WS-AT transaction message exchanges use different endpoint URLs and TCP ports.


Troubleshooting hints and tips

If you encounter problems with the end-to-end flow, check the WebSphere MessageTrace in trace.log to see the progression of the message exchanges. Following are some things to check:

  • Request 1: Does the application request from .NET contain SOAP headers with transaction context? If not, confirm that your client code is running in a transaction and that the required System.ServiceModel.TransactionFlowAttribute has been added to the generated proxy class HelloWorldTX.cs.
  • Request 2: Is WebSphere Transaction Service able to register with MSDTC? If not, verify that the target URL in Request 2 is correct. It should be https://<your_hostname>/WsatService/Registration/Coordinator/. Also verify that the SSL certificate setup procedures are completed successfully on both Windows and the WebSphere admistrative console.
  • WebSphere WS-AT and Transaction Trace: Enable this trace specification (WSCoor=all:Transaction=all) using the WebSphere administrative console to reveal any issues with the transaction handshake. The exception information in the FFDC directory is also very useful in identifying root causes.
  • MSDTC / WS-AT Transaction Bridge Trace: Create a file named msdtc.exe.config in %windir%\system32 to capture details of the transaction handshake as described in this forum thread.
  • If your service consumer or service provider update any resources (for example, using JDBC), ensure that an XA-compliant JDBC driver is configured and XADataSource is used in the application logic.

Conclusion

WS-AT opens up a new set of Web service use cases that were previously very challenging to implement. It shields application developers from the complexity of transaction error and timeout handling related to remote Web services invocation.

In this article, you've learned the basic concepts of WS-AT and how to apply it in a heterogeneous Web services environment. You've also learned how to invoke WebSphere Web services transactionally from a Microsoft .NET environment, along with some common problem-solving techniques on both platforms.


Acknowledgments

The author would like to thank the following people for their invaluable comments and contributions to this article:

  • Ian Robinson, WebSphere Transaction Architect, IBM Hursley Lab, UK
  • Jon Hawkes, WS-AT Developer, IBM Hursley Lab, UK
  • Jackie Paradis, Senior I/T Specialist, IBM Global Business Services, Canada

Downloads

DescriptionNameSize
HelloWorldTX Web services descriptionHelloWorldTX.wsdl3KB
HelloWorldTXConsoleClient (.NET 3.0)HelloWorldTXConsoleClient.zip5KB
HelloWorldTX Service Provider (EAR)HelloWorldTX.ear9KB

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=240788
ArticleTitle=Building transactional Web services with WebSphere Application Server and Microsoft .NET using WS-AtomicTransaction
publish-date=07112007