By now, you’ve almost certainly been exposed to Web services: distributed applications that communicate by means of Simple Object Access Protocol (SOAP) messages. Perhaps your clients are already starting to use Web services internally, or testing the waters with their business partners in an extranet. Of course, as a consultant, you know what that means: Soon enough you’ll be asked to troubleshoot a communications problem involving SOAP.
Developer tools such as Visual Studio .NET or Cape Clear 4 Studio will help you build full client applications that use Web services, but they’re not very good for ad hoc debugging sessions. I’ve found a pair of tools that you can easily pack into your laptop to help you troubleshoot any SOAP issues that arise when you’re on site.
.NET WebService Studio
Questions about the interface of a Web service can often be answered just by interacting with that Web service. By sending SOAP requests and examining the SOAP responses that come back, you can determine what the Web service is expecting as input and what it returns. In other cases, you might not know precisely what can be sent in a particular argument of the SOAP request, or what will come back in the response. For those situations, there’s a free tool from Microsoft named .NET WebService Studio (see Figure A).
To use .NET WebService Studio, you must first connect to a WSDL (Web Services Description Language) endpoint that describes the service that you want to interact with. After entering a URL for a WSDL file, click the Get button. The tool will retrieve the file and build a .NET proxy class using C#. You can inspect both the WSDL and the proxy class by clicking the WSDLs & Proxy tab in the tool.
After going through this bit of setup, you’re ready to interact with the Web service. Click the Invoke tab. You’ll find a tree view containing all of the operations that the Web service supports. Select an operation and fill in the arguments that it requires in the Input section of the user interface.
Figure A shows the value of KSEA assigned to the arg0 argument of the GetSummary method. Click the Invoke button, and the tool will send an appropriate SOAP request to the Web service and display the SOAP response in the Output section of the user interface. In the figure, we’ve retrieved a bit of weather information from the Seattle-Tacoma International Airport.
The most annoying bugs to track down are always the intermittent ones. What do you do when a Web service is failing to send the expected data, but only some of the time? The best solution is to monitor the SOAP traffic, so that you can analyze it over a period of time. For this purpose, the newly released SOAPscope Personal 1.0, from Mindreef, is ideal. You can get a trial version, or purchase a $99 license for continued use.
SOAPscope functions in two modes: sniffer and proxy. In sniffer mode, it monitors the local network interface for SOAP messages. In proxy mode, it accepts messages from SOAP clients and forwards them to SOAP servers, receiving the responses and sending them back to the original client application.
Sniffer mode is ideal when you have a troublesome application running on the same computer where SOAPscope is involved. Proxy mode lets you plug into a network, make a modification to the failing client (most client packages make it easy to specify a SOAP proxy), and then watch the traffic going by.
SOAPscope has two parts: a command-line application that watches traffic and stores it in a relational database, and a user interface that helps you analyze the captured data. Figure B shows the SOAPscope Viewer in action.
SOAPscope snags each SOAP message that goes by in either direction and matches up requests and responses. The messages are stored in its database, which persists across SOAPscope sessions so that you can come back to messages later. You might find this convenient when there’s a lot of SOAP traffic; you can more conveniently analyze it back in your office, for example.
Viewing the captured traffic is as easy as clicking a hyperlink in the SOAPscope viewer. Messages can be displayed in their raw XML format, or in a special pseudocode view that uses color-coding to highlight the important sections. You can also view WSDL files in a pseudocode view that makes their contents much easier to decipher.
SOAPscope’s utility doesn’t end there. The SOAP requests that the application captured are editable, so you can easily change their contents and resend them directly from the SOAPscope interface. You have your choice of working with the messages in XML or pseudocode format here as well. SOAPscope also saves all of the HTTP message headers in both directions. This comes in handy when you’re trying to track down errors such as character set mismatches.
There’s one more neat feature here for developers: annotations. Mindreef provides code that you can install on a Web service to add annotations to SOAP messages. You can think of these as the Web service equivalent of adding Debug.Print statements; annotations give you a way to insert information into the SOAP response so that it shows up in the SOAPscope interface.
Standards are not always standards
Even though SOAP is theoretically a W3C standard, in practice the world is a messy place. The youthfulness of the standard, coupled with the explosive growth of Web services and the number of competing vendors involved, has resulted in both subtle and blatant incompatibilities. For example, Visual Studio .NET can easily create Web services that are very difficult to consume from non-Microsoft products because of their reliance on Microsoft-only data types. So even though Web services can take you a long way towards the dream of perfect interoperability, you must be prepared to handle the occasional but inevitable breakdowns. Make sure you have some SOAP tools in your toolkit before that happens.