ToolKit

Languages: C#

ASP.NET Versions: 1.0 | 1.1

Microsoft SOAP Trace Tool

Easily inspect your ASP.NET Web service's raw SOAP messages.

 

By Ken McNamee

 

The .NET Framework greatly simplifies the creation and consumption of SOAP messages in a distributed computing environment. Visual Studio .NET goes even further in facilitating this process by quickly generating the proxy classes for the remote methods, so the developer doesn't even need to know that he or she is invoking code executing on an entirely different machine. However, although all of this abstraction is great for most developers, there are still occasions where you need to have more control over the SOAP requests and responses that are being passed across the wire during this communication.

 

It might come as a surprise to some developers without extensive Web services experience that the .NET Framework allows very fine control over almost every aspect of the SOAP creation and consumption process. The first step in assuming this control is to know exactly what your SOAP looks like. That's where the Microsoft SOAP Trace Tool (MSSOAPT) comes into play. You aren't going to find this tool or its equivalent in the .NET Framework SDK or any version of Visual Studio .NET - which I found a little surprising. You'll have to download and install the Microsoft SOAP Toolkit, which is a holdover from the early days when COM components were used to create and consume Web services with tools such as Visual Basic 6.0. You can download the Toolkit from http://msdn.microsoft.com/downloads/list/websrv.asp.

 

Start the Trace

You can start MSSOAPT by clicking the "Trace Utility" item in your Windows Start menu after you've downloaded and installed the SOAP Toolkit. Under the File menu, start a new Formatted Trace. You should be presented with the Trace Setup dialog box, as displayed in Figure 1. If you are working local and using port 80 for the local Web site that contains the Web service, you probably won't need to change any of these values. Once you click OK, MSSOAPT will start listening for any network traffic on the port that you specified. It's worth mentioning at this point that this tool is not limited to listening for SOAP-based traffic. Any bytes that are sent to the port that it's listening on will be displayed - whether they are human-readable or not.

 


Figure 1. The Trace Setup dialog box allows you to customize the port that the Trace Tool should listen on and the host name and port to which it should forward SOAP requests.

 

One of the few drawbacks to this tracing tool is the necessity to temporarily modify your Web service proxy class so that it points to the proxy port. However, this is only a minor inconvenience. A more significant inconvenience in my opinion is the lack of a real logging feature, but there is a work-around to this as MSSOAPT stores all of the information it generates in your logged-in user's temporary folder. Simply root around in that folder for the newly created files after each Web service call. It's not an ideal solution but - as my former boss used to say about my code - it's better than nothing.

 

Each request you make to the trace port will generate an entry in the tool's treeview menu on the left. As shown in Figure 2, clicking on the message in the treeview will display the SOAP request in the upper-right pane and the SOAP response in the lower-right pane. These panes are actually embedded HTML controls so you can right-click and choose View Source to save off the messages as a logging alternative to finding the right document in your temporary folder.

 


Figure 2. One-click access to the actual SOAP messages that were transferred during the Web service conversation can be a real timesaver during the debugging process.

 

As seen in Figure 3, another useful feature is the HTTPHeaders item in the treeview. A misconfigured <soapaction> in the request headers is a common source of cross-platform Web services problems. You might also take note of the <content-type> and <cache-control> headers as points of weakness when problems arise.

 


Figure 3. The HTTPHeaders are a common source for problems in cross-platform Web service calls.

 

Build It Yourself

I'm one of those people who always looks at software and thinks, "I bet I could recreate that!" Then after I spend eight hours on the project I finally decide that - while I could finish it if I wanted to - it would be more cost effective to just buy the software. However, a SOAP tracing tool is actually very easy to create yourself. The simplest SOAP inspection method is to log requests and responses to a file by using a SoapExtension, which is a .NET Framework class that allows you to extend the built-in Web services architecture. If you go to the overview page for the SoapExtension class in the MSDN Library documentation you'll even find the code you need to accomplish this task: a custom class called TraceExtension. Understanding how this class works is also a useful exercise in understanding what goes on under the hood of every Web service call.

 

You might be thinking that you've never really had any problems arise concerning the format of SOAP messages and therefore don't see a need to use a tracing tool. Consider yourself lucky. SOAP formatting issues are most likely to pop up when you or another company try to consume a .NET Web service from another Web services platform. For example, I was recently asked to create a proof of concept regarding a .NET Web service that had to allow consumption from ASP.NET, classic ASP, PHP, Java, Perl, Cold Fusion, and Python. Needless to say, this was a very frustrating - yet instructive - development exercise.

 

Even though SOAP Web services promise greater ease with regard to cross-platform interoperation, there are still many challenges that must be overcome. SOAP tracing is one technique you should take advantage of to help facilitate your Web services development.

 

Resources

SOAP Toolkit: http://msdn.microsoft.com/downloads/list/websrv.asp

ProxyTrace: http://www.pocketsoap.com/tcptrace/pt.aspx

TraceExtension: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwebservicesprotocolssoapextensionclasstopic.asp

 

The sample code in this article is available for download.

 

Ken McNamee is an independent consultant who works with companies in need of highly scalable data-driven Web applications. And who doesn't need one of those these days? Prior to this, he led a team of developers in re-architecting the Home Shopping Network's e-commerce site, HSN.com, to 100% ASP.NET with C#. Readers can contact him at editors@devproconnections.com.