Generating a Client Proxy from XML Metadata

Microsoft provides a few tools in its .NET Framework to aid in developing client proxies to access Web Services. The WSDL executable, located in the bin directory of the framework SDK, does all the dirty work for you. The syntax for running wsdl.exe from the command line is as follows:

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

Table 8-1 documents the WSDL.exe command's arguments.

Table 8-1 WSDL Command Syntax

Parameter	Value
<url or path>	A URL or path to a service description, a file describing a Web Service in WSDL. If you specify a file, supply a file containing the service description. For example: myWebservice.wsdl If you specify a URL, the URL needs to reference an .asmx page or return a service description. For ASP.NET Web Services you can return a service description by appending WSDL to the URL of the Web Service. For example, http://www.contoso.com/MyWebService.asmx?WSDL
/language:language	(Optional) 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. If no language option is specified, the proxy class is generated in C#.
/protocol:protocol	(Optional) The protocol used to invoke the Web Service methods. Available options include SOAP, HttpGET, and HttpPOST. If no protocol is specified, SOAP is the default.
/namespace: myNameSpace	(Optional) The namespace of the generated proxy. Default value is the global namespace.
/out:filename	(Optional) The name of the file to create containing the proxy class. Default name is based on the name of the Web Service.
/username:username	(Optional) The username to use when connecting to a Web server that requires authentication.
/password:password	(Optional) The password to use when connecting to a Web server that requires authentication.
/domain:domain	(Optional) The domain to use when connecting to a Web server that requires authentication.

Let's use this tool on our CreatePerson Web Service.

 wsdl /language:CS /out:PersonCreator.cs http://localhost/
CSharpWebService/Service1.asmx?WSDL 

The tool created the Listing 8-15 file that contains all the proxy code needed to access the service. This file can be imported into our client .NET project and used out of the box. Here is the code that the WSDL.exe utility generated for us.

Listing 8-15 PersonCreator.cs: A C# source file containing the proxy code required to access the createPerson( ) Web Service method.

 //------------------------------------------------------------------ // <autogenerated> //   This code was generated by a tool. //   Runtime Version: 1.0.2914.11 // //   Changes to this file may cause incorrect behavior and will be lost if  //   the code is regenerated. // </autogenerated> //----------------------------------------------------------------- //  // This source code was auto-generated by wsdl, Version=1.0.2914.11. //  using System.Diagnostics; using System.Xml.Serialization; using System; using System.Web.Services.Protocols; using System.Web.Services; [System.Web.Services.WebServiceBindingAttribute (Name="Service1Soap", Namespace="http://tempuri.org/")] public class Service1 : System.Web.Services.Protocols. SoapHttpClientProtocol { [System.Diagnostics.DebuggerStepThroughAttribute()] public Service1() { this.Url = "http://localhost/CSharpWebService/Service1.asmx"; } [System.Diagnostics.DebuggerStepThroughAttribute()] [System.Web.Services.Protocols.SoapDocumentMethodAttribute ("http://tempuri.org/CreatePerson", Use=System.Web.Services. Description.SoapBindingUse.Literal, ParameterStyle=System.Web. Services.Protocols.SoapParameterStyle.Wrapped)] public Person CreatePerson(string firstName, string lastName, 
string birthDate, string hairColor, string favoriteColor, string address1, 
string address2, string city, string state,  string postalCode, string country) { object[] results = this.Invoke("CreatePerson", new object[] { firstName, lastName, birthDate, hairColor, favoriteColor, address1, address2, city, state, postalCode, country}); return ((Person)(results[0])); } [System.Diagnostics.DebuggerStepThroughAttribute()] public System.IAsyncResult BeginCreatePerson(string firstName, 
string lastName, string birthDate, string hairColor, string  favoriteColor, string address1, string address2, string city, string state, 
string postalCode, string country, System.AsyncCallback  callback, object asyncState) { return this.BeginInvoke("CreatePerson", new object[] { firstName, lastName, birthDate, hairColor, favoriteColor, address1, address2, city, state, postalCode, country}, callback, asyncState); }  [System.Diagnostics.DebuggerStepThroughAttribute()] public Person EndCreatePerson(System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((Person)(results[0])); } } public class Person { public string firstName; public string lastName; public string birthDate; public string hairColor; public string favoriteColor; public Address address; } public class Address { public string address1; public string address2; public string address3; public string city; public string state; public string postalCode; public string country; } 

You might notice that this file looks similar to the PersonCreator class shown in Listing 8-14. One significant difference is the introduction of two new methods: BeginCreatePerson( ) and EndCreatePerson( ). These functions, generated by the WSDL.exe utility, allow you to invoke the CreatePerson service asynchronously.

.NET supports a design pattern that implements asynchronous Web method invocation, regardless of how the Web method was written. The pattern prescribes two new asynchronous methods, Begin( ) and End( ), for every synchronous method. These functions give non-blocking access to Web Services that take a long time to complete. To call the function asynchronously you must alter your client to call BeginCreatePerson( ) instead of CreatePerson( ). BeginCreatePerson( ) kicks off the Web Service but doesn't wait for it to finish. Instead it returns a handle to an object that implements the IAsyncResult interface. The IAsyncResult interface contains a WaitHandle object that handles all of the synchronization involved in waiting for the Web Service to complete.

Once the CreatePerson service has completed, you must call the EndCreatePerson( ) function to retrieve the results. The call to EndCreatePerson( ) can happen via a callback function passed into BeginCreatePerson( ), or you can wait on the WaitHandle object explicitly and call EndCreatePerson( ) when the service has finished its job. EndCreatePerson( ) requires you to pass in the IAsyncResult handle as an argument. It returns the result the same way the synchronous method does.

Visual Studio .NET will automate the creation of Web Service proxies for you. By adding a "Web reference" to your project you can dynamically generate all the code you need to access a particular Web Service.