Viewing SOAP Message Exchanges

A good number of the bugs you tackle can be resolved by simply tracing the messages being exchanged between the client and server. One tool you will want is MSSOAPT.EXE, the trace utility provided with the Microsoft SOAP Toolkit v2. You can download the toolkit (SoapToolkit20.exe) from http://msdn.microsoft.com. To install just the trace utility, do the following:

To start the trace utility, choose the Start button on the taskbar and select Programs, Microsoft SOAP Toolkit, Trace Utility (MSSOAPT.EXE).

The trace utility works by using a fairly simple store and forward mechanism. To make it easy to view SOAP messages, you should always set the URL Behavior property on Web references to Dynamic. Doing so allows you to change the Web Service endpoint without rebuilding your source code. Figure 5.3 shows where to do this in the Visual Studio .NET environment.

Your first step in debugging should almost always be to open up this application and set it up to do a formatted trace. A formatted trace displays the requests and corresponding responses using the XML styles used by Internet Explorer. To access this functionality, open up the trace utility and select File, New, Formatted Trace. This will bring up the dialog shown in Figure 5.4. Typically, the default settings of listening on port 8080 and rerouting to localhost port 80 will work when debugging on the local machine. When debugging a client working with a remote server, just change the values appropriately. For example, a Web Service located on http://www.scottseely.com on port 9090 would set the destination host to www.scottseely.com and the destination port to 9090.When setting the Destination Host value, do not include things like the http prefix or the specific subdirectory. That information is carried in the SOAP message itself.

After this is set up, you can now look at the SOAP messages and maybe figure out what is going wrong. You will want the WSDL definition of the operation being called available. Then, start with basic debugging and examine the SOAP request. Many of these items will not be wrong for a proxy created with Visual Studio .NET. Because your job may involve using toolkits created by companies other than Microsoft, I am including the full set of things to look at when debugging:

• Is the SOAP namespace correct? It must be http://schemas.xmlsoap.org/soap/envelope/.

• Is the enclosing element named Envelope and does the namespace match the one associated with http://schemas.xmlsoap.org/soap/envelope/?

• Is there a Body element, and does the namespace match the one associated with http://schemas.xmlsoap.org/soap/envelope/?

• Does the method being called use the namespace specified in the types element's targetNamespace attribute?

• Do the method names and element names match the operation information shown in the WSDL file? Depending on the Web Service type (RPC/encoded or document/literal), this may matter. This also matters on different SOAP implementations. Regardless, this is yet another thing to check and might be stopping you from connecting to the other Web Service.

A formatted trace (without problems) is shown in Figure 5.5.

If everything looks correct, the other item you can check is the SOAPAction and the endpoint to which you are connecting. To see all of the information going between the two endpoints, select File, New, Unformatted Trace. The reading of data might be a bit cramped, but you can find out what the SOAPAction HTTP header is set to, as well as any other data being exchanged. Figure 5.6 shows an unformatted trace. See if you can spot the SOAPAction header.

When debugging client applications against a deployed Web Service, you can almost always be assured that if things are not working, it is your client code's fault. Because of this, you will spend a lot of time going over your SOAP messages making sure that all elements of the message are correct. Sometimes, the message might come back with no elements. Believe it or not, this can cause exceptions to be thrown on the client. During deserialization, the .NET runtime will try to take an empty element and deserialize that element into a value type (int, string, some class, and so on). If there is nothing to deserialize, this effort can sometimes cause an exception to be thrown. The only defense against this is to wrap the Web method call in a try/catch block.

Listing 5.1 shows an error handler that wraps the call and logs the error to a custom event log named myNewLog. The code itself calls to the Quote of the Day Web Service hosted by Microsoft at http://www.gotdotnet.com. To force the error to occur, the code contains a line that sets the URL to an endpoint that does not host the Web Service.

Listing 5.1. A Simple Error Handler

Sub Main()

    Dim svc As New com.gotdotnet.www.Quote()
    svc.Url = "http://www.scottseely.com/"

    Try
        Console.WriteLine(svc.GetQuote())
    Catch soapEx As System.Web.Services.Protocols.SoapException
        Dim log As New System.Diagnostics.EventLog( _
            "myNewLog", ".", "SOAP")
        log.WriteEntry("SOAP Fault was caught at " & _
            DateTime.Now.ToString() & vbCrLf & _
            "Code: " & soapEx.Code.ToString() & vbCrLf & _
            "Actor: " & soapEx.Actor & vbCrLf & _
            "Detail: " & soapEx.Detail.InnerXml)
        log.Dispose()
    Catch ex As Exception
        Dim log As New System.Diagnostics.EventLog( _
            "myNewLog", ".", "Unknown")
        log.WriteEntry( _
            "An exception was caught at " & _
            DateTime.Now.ToString() & vbCrLf & _
            "URL to contact: " & svc.Url & vbCrLf & _
            "Exception details: " & ex.ToString())
        log.Dispose()
    End Try

    Console.ReadLine()

End Sub
					

This error log will be stored on the local machine. Assuming that Windows is installed in the c:windows directory, the error log for the previous instance will be in the file named c:windowssystem32configmyNewLog.evt. You will need to add this file in the event viewer to view any events.

We also have to consider that something may be wrong at the server and, if the server is ours, we are responsible for that too. How do you debug the server?