Creating an XML Web Service Proxy

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

By definition, Web services can be communicated with over a network using industry standard protocols, including SOAP. That is, a client and a Web service communicate using SOAP messages, which encapsulate the in and out parameters as XML. Fortunately, for Web service clients, the proxy class handles the work of mapping parameters to XML elements and then sending the SOAP message over the network.

As long as a service description exists, a proxy class can be generated if the service description conforms to the Web Services Description Language (WSDL). A service description defines how to communicate with a Web service. With a service description, a proxy class can be created with the Wsdl.exe tool. In turn, a Web service client can then invoke methods of the proxy class, which communicate with a Web service over the network by processing the SOAP messages sent to and from the Web service. Because the proxy class communicates with the Web service across the Internet, it is a good idea to verify that the Url property of the proxy class references a trusted destination.

By default, the proxy class uses SOAP over HTTP to communicate with the Web service. However, Wsdl.exe can generate proxy classes to communicate with a Web service, using either the HTTP-GET protocol or HTTP-POST protocol. To specify that the proxy class should use HTTP-GET or HTTP-POST, provide the /protocol switch to the Wsdl.exe tool, as described in the following table.

Using Wsdl.exe to Generate an XML Web Service Proxy Class

You can use the Web Services Description Language tool (Wsdl.exe) from a command prompt to create a proxy class, specifying (at a minimum) the URL to a Web service or a service description, or the path to a saved service description.

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

Generated Proxy Class Details

When Wsdl.exe is used to generate a proxy class, a single source file is generated in the specified language. This file contains a proxy class that exposes both synchronous and asynchronous methods for each Web service method of the Web service. For example, if a Web service contains a Web service method named Add, the proxy class has the following methods for calling the Add Web service method: Add, BeginAdd, and EndAdd. The Add method of the proxy class is used to communicate with the Add Web service method synchronously, but the BeginAdd and EndAdd methods are used to communicate with a Web service method asynchronously. For more information about communicating with Web service methods asynchronously, see Communicating with XML Web Services Asynchronously.

Each method of the generated proxy class contains the appropriate code to communicate with the Web service method. If an error occurs during communication with the Web service and the proxy class, an exception is thrown. For more information about handling exceptions, see Handling and Throwing Exceptions in XML Web Services.

The parameter order may differ between the defined order in the Web service method and the associated method of the proxy class. In most cases, the parameter order matches. However, if the Web service expects Document formatted SOAP messages, there is one case where the parameter order does not match. If a Web service method has out parameters defined prior to an in parameter, the out parameters are placed after all the in parameters in the proxy class. For example, in the following code example, the Web service method MyWebMethod has the outStr out parameter declared prior to the inStr in parameter. However, in the proxy class, the inStr parameter is declared prior to outStr.

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

In some cases, the proxy class generated by Wsdl.exe uses a least common denominator approach for casting objects to a type specified in a service description. As a result, the generated type in the proxy class might not be what the developer wants or expects. For example, when Wsdl.exe encounters an ArrayList type in a service description, it creates an Object array in the generated proxy class. To ensure the correct object type casts, open the file that contains the generated proxy class and change any incorrect object types to the expected object type.

Warnings Thrown by Wsdl.exe

When supplying multiple service descriptions to Wsdl.exe, two of the error messages that might be raised are the following:

• Warning: Ignoring duplicate service description with TargetNamespace=<schema namespace> from location <schema URI>.

  Indicates the TargetNamespace for two or more of the supplied service descriptions are identical. As the TargetNamespace is supposed to be a unique identifier for a particular XML document, which in this case is a service description, Wsdl.exe assumes that the two service descriptions are identical. In doing so, Wsdl.exe builds just one proxy class for one of the service descriptions. If this is not your intended result, you can change this. For service descriptions that represent Web services created using ASP.NET, you can apply a WebService attribute that specifies a unique Namespace property to the class that implements the Web service. That Namespace property is then used as the TargetNamespace in the service description to uniquely identify the Web service.

• Warning: Ignoring duplicate schema with TargetNamespace=<schema Namespace> from location <schema URI>.

  Indicates the TargetNamespace for two or more XML schemas within the supplied service descriptions are identical. Because the TargetNamespace is supposed to be a unique identifier for a particular XML document, which in this case is the XML schema, Wsdl.exe assumes that the two XML schemas are identical. In doing so, Wsdl.exe builds a class for just one of the schemas. If this is not the intended result, the TargetNamespace for each XML schema must be changed to a unique URI. Exactly how the TargetNamespace is modified depends on the origin of the particular XML schemas.

See Also

Tasks

How to: Explore Existing XML Web Services Created Using ASP.NET
How to: Access XML Web Services from a Browser

Concepts

Building XML Web Service Clients
Web Services Discovery
Communicating with XML Web Services Asynchronously

Other Resources

Creating Clients for XML Web Services