Creating an XML Web Service Proxy

By definition, XML Web services can be communicated with over a network using industry standard protocols, including SOAP. That is, a client and an XML Web service communicate using SOAP messages, which encapsulate the in and out parameters as XML. Fortunately, for XML 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 an XML Web service. With a service description, a proxy class can be created with the Wsdl.exe tool. In turn, an XML Web service client can then invoke methods of the proxy class, which communicate with an XML Web service over the network by processing the SOAP messages sent to and from the XML Web service. Because the proxy class communicates with the XML 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 XML Web service. However, Wsdl.exe can generate proxy classes to communicate with an XML 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 table below.

To generate an XML Web service proxy class

• From a command prompt, use Wsdl.exe to create a proxy class, specifying (at a minimum) the URL to an XML 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>
  

  Note: The arguments listed previously are the commonly used arguments for the Wsdl.exe tool. For the full syntax of the Wsdl.exe tool, see ** Web Services Description Language Tool (Wsdl.exe).

  Parameter	Value
  <url or path>	A URL or path to a service description (a file describing an XML Web service in Web Services Description Language). If you specify a file, supply a file containing the service description. For example: mywebservice.wsdl If you specify a URL, the URL must reference an .asmx page or return a service description. For XML Web services created using ASP.NET, you can return a service description by appending ?WSDL to the URL of the XML Web service. For example, https://www.contoso.com/MyWebService.asmx?WSDL
  /language:language	The language the proxy class is generated in. Available options include CS, VB, and JS, referring to C#, Visual Basic .NET, and JScript .NET, respectively. The default language is C#. (Optional)
  /protocol:protocol	The protocol used to communicate with the XML Web service methods. Available options include SOAP, HTTP-GET, and HTTP-POST. The default protocol is SOAP. (Optional)
  /namespace:myNameSpace	The namespace of the generated proxy. The default value is the global namespace. (Optional)
  /out:filename	The name of the file to create containing the proxy class. The default name is based on the name of the class implementing the XML Web service. (Optional)
  /username:username	The user name to use when connecting to a Web server that requires authentication. (Optional)
  /password:password	The password to use when connecting to a Web server that requires authentication. (Optional)
  /domain:domain	The domain to use when connecting to a Web server that requires authentication. (Optional)

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 exposing both synchronous and asynchronous methods for each XML Web service method of the XML Web service. For instance, if an XML Web service contains an XML Web service method named Add, the proxy class has the following methods for calling the Add XML Web service method: Add, BeginAdd, and EndAdd. The Add method of the proxy class is used to communicate with the Add XML Web service method synchronously, but the BeginAdd and EndAdd methods are used to communicate with an XML Web service method asynchronously. For more information on communicating with XML 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 XML Web service method. If an error occurs during communication with the XML Web service and the proxy class, an exception is thrown. For details on handling exceptions, see Handling and Throwing Exceptions in XML Web Services.

The parameter order may differ between the defined order in the XML Web service method and the associated method of the proxy class. In most cases, the parameter order will match. However, if the XML Web service expects Document formatted SOAP messages, there is one case where the parameter order will not match. If an XML 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 instance, in the following code example, the XML 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.

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 correct object type casts, open the file containing the generated proxy class and change any incorrect object types to the expected object type.

' Declare MyWebMethod in the XML 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)
[C#]
// Declare MyWebMethod in the XML 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 correct object type casts, open the file containing 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 representing XML Web services created using ASP.NET, you can apply a WebService attribute specifying a unique Namespace property to the class implementing the XML Web service. That Namespace property is then used as the TargetNamespace in the service description to uniquely identify the XML Web service. For more information on setting the Namespace property, see Applying a WebService attribute.

• 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

Building XML Web Service Clients | Discovering XML Web Services | Creating Clients for XML Web Services | Exploring Existing XML Web Services Created Using ASP.NET | Communicating with XML Web Services Asynchronously | Accessing XML Web Services from a Browser