• Article

Adding SOAP Trace Support to Client Applications

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

When you developing Web client applications for Native XML Web Services in SQL Server, a helpful tool for troubleshooting is the ability to trace and observe SOAP messages that are exchanged between an instance of SQL Server and your client application.

This topic features a sample class library that implements SOAP extension headers that support SOAP tracing of your client application project from within Visual Studio 2005. When integrated with your project, these extensions trace and display the actual contents of the SOAP request and response message.

This library can be added as to existing Visual Studio 2005 SOAP client projects. This includes the sample applications provided in Sample Applications for Sending Native HTTP SOAP Requests. We recommend that you be familiar with the conceptual and procedural information provided in Setting the Server to Listen for Native XML Web Services Requests and Writing Client Applications.

Additionally, if you are not familiar with the format of SOAP messages, see the following topics:

Note

The following procedure assumes that you have created an existing SOAP client application by using Visual Studio 2005 and have added a Web reference to an HTTP SOAP endpoint that was created by using SQL Server, as shown in Sending SOAP Requests by Using Visual Studio 2005 Client (C#).

To add the SOAP trace sample library to a Visual Studio project

  1. Using Notepad, copy and paste the contents of the C# Code Listing for SQL SOAP Trace Sample Class Library and save it with the name "SqlSoapTracer.cs" in the same folder that contains the SOAP client project files.

  2. On the client computer, from the Microsoft Visual Studio 2005 program group, start Microsoft Visual Studio 2005.

  3. Click Open Project.

  4. Browse and select your SOAP client project (.csproj) file.

  5. In the Solution Explorer window, perform the following steps:

    1. Select the project by name, right-click and point to Add, and then select Add Existing Item.

    2. In the Add Existing Item dialog box, browse and select the SqlSoapTracer.cs file from the location you saved it to in step 1.

    3. Select Show All Files and expand the Web References node and select the Reference.cs file.

  6. In the Code Editor window, update the Reference.cs file by locating the entry points for your Web methods there.

    For example, if you are adding SOAP trace support to the sample project provided in Sending SOAP Requests by Using Visual Studio 2005 Client (C#), the published Web method entry points for the various Web methods included in that project will appear as follows:

    public object[] GetCustomerInfo([System.Xml.Serialization.XmlElementAttribute(IsNullable=true)] System.Data.SqlTypes.SqlString CustomerID, [System.Xml.Serialization.XmlElementAttribute(IsNullable=true)] ref System.Data.SqlTypes.SqlString OutputParam) {
            object[] results = this.Invoke("s2MsgGetCustomerInfoSoapIn", new object[] {
                        CustomerID,
                        OutputParam});
            OutputParam = ((System.Data.SqlTypes.SqlString)(results[1]));
            return ((object[])(results[0]));
        }

...

public System.Data.SqlTypes.SqlInt32 UDFReturningAScalar() {
            object[] results = this.Invoke("s1MsgUDFReturningAScalarSoapIn", new object[0]);
            return ((System.Data.SqlTypes.SqlInt32)(results[0]));
        }

  7. To add SOAP trace support when the Web methods execute in client code, add the following snoopattribute() call in the Reference.cs code directly before the entry point for each Web method you want to trace, as shown in the following lines of code.

    [snoopattribute()]
public object[] GetCustomerInfo(...) {...}
...
[snoopattribute()]
public System.Data.SqlTypes.SqlInt32 UDFReturningAScalar() {...}

    This registers a SOAP extension that invokes the SOAP tracing of these Web methods when they are executed.

Using SOAP Trace Support to Test Your Application

To use the SOAP trace support extensions provided in the previous code when you are running the SOAP client application in the Visual Studio development environment, you must complete the following steps:

  1. By using either SQL Server Management Studio or the osql command utility, add a Web method to expose the stored procedure or user-defined function that you want to test on your endpoint.

    For more information, see Exposing SQL Programmability to the Web.

  2. In Visual Studio, if you have not done so already, code, debug and build a SOAP client application project.

    Optionally, you can use the sample project provided in Sending SOAP Requests by Using Visual Studio 2005 Client (C#).

  3. Add the SqlSoapTracer.cs class to the project as described in the previous section.

  4. Save, build and run your client application in the Visual Studio development environment.

    By running your application, a Windows Clipboard viewer object is created. When the Web methods that you enabled for tracing in step 3 are executed, this viewer object displays the following for each of the Web methods:

    • The SOAP client request message as generated by the client code.

    • The SOAP server response message as returned by Native XML Web Services for SQL Server.

    To view the contents of the clipboard after trace activity has occurred, you can paste the current Windows Clipboard contents into Notepad.

How the SOAP Trace Support Works

The tracing mechanism uses predefined callbacks and events that are part of how Native XML Web Services in SQL Server is implemented. These include two events: BeforeSerialize and AfterSerialize.

These events and callbacks allow the SOAP request and its corresponding SOAP response from the server to be trapped and redirected to an output stream. In the provided code, the output is redirected to a System.Windows.Forms.Clipboard object. The Clipboard object receives and displays the SOAP client request and server response messages that are exchanged by executing Web methods that are directly preceded by snoopattribute() calls.

The output of the client request, and the response issued by SQL Server in response to it, will appear in a format similar to the SOAP request message structure and SOAP response message structure. In the response, any results that are generated by the server, such as the serialized XML output if the Web method successful executed, will also appear. In the case of an error, a SOAP fault message structure will appear instead of the serialized XML output within the response returned by the server.