Tracing SOAP Messages

So far, you have seen several examples of how the SOAP message is constructed. If you are a developer dealing with SOAP, you invariably need to see the SOAP messages that are being sent back and forth across the wire for debugging purposes. If you want to see the entire SOAP message, how do you go about it? Well, actually, it is fairly simple, but you must take a few steps to set it up.

Web services toolsets that are present on certain platforms have some tracing capabilities built into them. For instance, IBM's WebSphere has a SOAP tracing capability built into it, as does Microsoft's Web Services Enhancements (WSE) toolset. Another possibility includes some open-source tools such as PocketSOAP (found at http://www.pocketsoap.com).

This chapter discusses two tools for monitoring SOAP messages for the purposes of SOAP debugging-one is the Microsoft Trace Utility, and the other is Altova's SOAP debugging capabilities found in the XMLSpy Enterprise Edition.

The Microsoft Trace Utility

To view SOAP messages as they are sent back and forth across the wire, you must download the Microsoft SOAP Toolkit 3.0 from Microsoft's MSDN site at http://www.msdn.microsoft.com/webservices/Downloads. The SOAP Toolkit 3.0 includes a number of tools, but you really only need to install the Trace Utility tool that is encased inside this offering.

You can use the Trace Utility within the SOAP Toolkit to trace SOAP messages as they are being sent and received by a Web service client application. One nice feature of this tool is that it is free.

Using the Trace Utility

You must take a few preliminary steps in order to use the Trace Utility. First, you need a Web service that you can consume. Next, you must build an application that consumes this Web service and is able to send a SOAP request to it that causes the Web service to issue a response in return.

The Trace Utility runs the request and response messages through a port that it has opened and is monitoring. After the Trace Utility receives one of these messages, it records the message and then forwards the message to the appropriate port for handling.

To see this in action, open up the Trace Utility. You are then presented with a blank application. To start a new SOAP debugging session, select File New Formatted Trace from the menu of the application. What opens next is the Trace Setup window that enables you to specify the local port number that you want the Trace Utility tool to use, as well as the destination host and port number. This dialog is shown in Figure 20-3.

Figure 20-3

After you click the OK button, tracing is enabled, and you are ready to run your consuming application in order to have the SOAP messages that are communicated and recorded by the Trace Utility application. To do this, however, you have to set up your application to run through port 8080 as specified in the Trace Setup dialog from Figure 20-3.

Modifying the Consuming Application

In .NET 1. x, you accomplish this by changing the URL attribute in the Reference.cs or the Reference.vb file contained in your Web Reference to include the new specified port.

      <lit>this.Url = "http://localhost:8080/XMLWS/WebService1.asmx"; 

In .NET 2.0, you accomplish this by changing the URL in the web.config or app.config file of your application.

      <appSettings>         <add key="localhost.Service" value="http://localhost:8080/XMLWS/Service.asmx"/>      </appSettings> 

Viewing the SOAP Messages

After you have your consuming application set to run through port 8080, then you can run the application as you normally would. The Trace Utility application then traces all the SOAP communications that occur between your application and the Web services it is working with.

Both the Web service client application and the Trace Utility tool from Microsoft should be open when you are doing this. After you have run the application to invoke the remote Web service, you find the results directly in the Trace Utility.

Looking at the Trace Utility, you can see an entry in the left pane of the application. The set of numbers you see, 127.0.0.1, is your local IP address. Expand the plus sign next to this IP address and you see Message #1. Highlight Message #1 to see the SOAP messages show up in the other two panes within the utility. Figure 20-4 shows what the Trace Utility looks like after you have taken these steps.

Figure 20-4

After completing these steps, you can watch the SOAP messages that are sent to and from your Web services. This is quite beneficial for debugging and for forming your SOAP messages to the appropriate format. Remember that you shouldn't be doing this tracing operation on production clients or Web services because it greatly hurts the performance of these items. Also, the Trace Utility has some limitations when working with SOAP 1.2. The image shown in Figure 20-4 is a set of SOAP 1.1 messages. When you use this tool with a SOAP 1.2 message, notice that all the beautiful formatting of the SOAP messages is removed and you are left with a single, long, and unformatted string of XML which is the SOAP 1.2 message. It still works, but the result is harder to visualize and decipher.

XMLSpy's SOAP Debugging

When debugging your SOAP messages, the other option you have is Altova's XMLSpy's SOAP debugging capabilities. Note that you have this capability only when using the XMLSpy 2006 Enterprise Edition.

Using the SOAP Debugging Capabilities

To get the SOAP debugging capabilities of XMLSpy up and running, the first step (after you have XMLSpy open, of course) is to select SOAP SOAP Debugger Session. This launches a dialog that asks for the WSDL file to use for the operation. This dialog is presented in Figure 20-5.

Figure 20-5

After you have pointed to the location of the WSDL file, click the OK button to proceed. After clicking the OK button, you are presented with a dialog to configure the listening and forwarding ports. Similar to the Microsoft Trace Utility tool, XMLSpy monitors communication on a specific port that you must configure your application to work with. This dialog is presented in Figure 20-6.

Figure 20-6

When you have the ports set up as you wish, click the OK button and you are presented with everything wired up for SOAP debugging as presented in Figure 20-7.

Figure 20-7

From this figure, you can see that (at the bottom of the IDE) two HelloWorld methods are presented in the Soap Function list. This is because the WSDL file I am using comes from a C# 2.0 Web service that exposes a Hello World method using SOAP 1.1 and another that uses SOAP 1.2; so it really uses two separate methods.

To take the final steps to use this SOAP debugging tool, check the check boxes for the methods you are interested in monitoring. Looking at Figure 20-7, you can see that I am interested in both the request and the response because I have checked both check boxes. After the appropriate check boxes are checked, click the green arrow found directly above the SOAP Request dialog to start the proxy server. You are now ready to run your application.

Running your application captures only the SOAP request at first, and the application pauses while waiting for a response. The request is presented in the SOAP Request dialog of XMLSpy as shown in Figure 20-8.

Figure 20-8

In this figure, you can see the SOAP request. Now that the SOAP request is shown in this dialog, you can press the green arrow again to actually send the SOAP request to the Web service. You are presented with a SOAP response as shown in Figure 20-9.

Figure 20-9

After the response is retrieved, you click the green arrow again to forward the response onto the actual consuming application. The nice thing with XMLSpy is that you can look at the SOAP messages in a couple of different formats. The request and response shown in Figures 21-8 and 21-9 are the text views of the SOAP message. It is also possible, however, to look at the request or response in a Grid view as well as a Browser view, which gives the same view as the Trace Utility tool shown earlier. The Grid view is presented in Figure 20-10.

Figure 20-10

Using XMLSpy to Issue SOAP Requests

Probably one of the more exciting SOAP capabilities found in XMLSpy 2006 Enterprise Edition is its capability to issue SOAP requests directly from the tool itself to the Web services you are interested in testing or consuming. If you are a Web services developer, you no longer have to build a consuming application in order to test your Web services; instead, you can use XMLSpy and to test the Web services you are interested in.

To accomplish this, select SOAP Create New SOAP Request from the XMLSpy menu. This launches a dialog where you specify the location of the WSDL file (this is the same dialog which was presented earlier in Figure 20-5). From this dialog, point to the location of the WSDL file for the Web service you are interested in consuming. After you have specified the location of the WSDL file, click OK and you are presented with a dialog asking you which service you are interested in consuming. This is presented in Figure 20-11.

Figure 20-11

In this case, I have selected Service-ServiceSoap12, which is the SOAP 1.2 version of my Web service (the other is the SOAP 1.1 version). After I select OK, I select the Method I am interested in consuming. For this Web service, there is only one-HelloWorld() (shown in Figure 20-12).

Figure 20-12

After you click OK in this dialog, you are presented with a sample SOAP request to be sent to the HelloWorld() Method. This is illustrated in Figure 20-13.

Figure 20-13

Looking over this SOAP request, you can see that it is perfectly structured for sending to the HelloWorld() Method. The only problem is that XMLSpy doesn't know which parameters I want to send to the Web service in order to invoke it. (This service doesn't require any parameters for the HelloWorld() method.) It also doesn't know what to place inside the SOAP header block that this message contains. In place of the values, it puts the name of the data type as illustrated in the following code:

      <m:RequiredServiceHeader xmlns:m="http://www.wrox.com/ws">         <m:Username>String</m:Username>         <m:Password>String</m:Password>      </m:RequiredServiceHeader> 

The nice thing about this tool is that you can go into this message and change the values from String to whatever you want before sending the message to the Web service. So, change the values and then select SOAP Send Request To Server from the XMLSpy menu. This sends the structured SOAP message to the Web service you have specified, and it receives and displays the response in the same way as the SOAP request was displayed. This is presented in Figure 20-14.

Figure 20-14

As you can see, although the Trace Utility does allow for basic SOAP tracing for debugging purposes, XMLSpy ups it a notch by adding other ways of viewing the data and easier ways to invoke the services.