ToolKit
LANGUAGES: All .NET Languages
TECHNOLOGIES: WSDL | Web Services | SOAP
Web Services on the Cheap
Make calling Web services easier with the free WSDL.exe.
By Ken McNamee
There's more than one way to consume a Web service. One of the easiest is to create a proxy class that serves as the communication mechanism between your code and the remote - or even local - Web service. You can create this class manually, but you'd need to have detailed knowledge of the .NET classes and syntax necessary to construct the SOAP plumbing. The better option is to create the class automatically, using one of two tools: Visual Studio .NET or WSDL.exe, which is a command-line tool. The only significant difference between these tools is that the WSDL tool is free and Visual Studio .NET is, well, not free.
If you own VS .NET and have tried consuming Web services, you're probably familiar with the process of adding a Web Reference to your project. The Web Reference creates the class that acts as a proxy to facilitate the process of calling the Web service. As you can see in Figure 1, this reference is created by pointing the Add Web Reference dialog box at the WSDL document for a Web service.
Figure 1. Visual Studio .NET's Add Web Reference dialog box provides an
easy way to create the proxy class that facilitates calling Web services from a
client.
Of course, you can take advantage of this wizard only if you own a copy of VS .NET. If you don't, however, you're not out of luck. The .NET Framework includes the WSDL.exe tool that performs the same function as the Add Web Reference dialog box, and it outputs nearly identical code for the proxy class. Although I can't confirm this, the wizard seems like merely a GUI wrapper for the WSDL command-line tool.
How It Works
There isn't much to the WSDL tool. It simply accepts a WSDL document - or an XSD or DISCO document - and outputs a .NET class file in C#, VB .NET, or JScript .NET. This class inherits from SoapHttpClientProtocol and implements, as public methods, all the Web methods in the Web service. Take, for example, an exciting and incredibly useful Web service for all you developers who have network administrators that enforce the most stringent password requirements (see Figure 2).
public class WsdlExample : WebService {
[WebMethod]
public string GetRandomPassword(int length) {
StringBuilder password = new StringBuilder();
Random rndCode = new Random();
Random rndCase = new Random();
Random rndType = new Random();
for (int i = 1; i < length + 1; i++) {
int chrType = (i == 1) ? 1 : rndType.Next(0, 2);
int asciiCode = (chrType == 1) ?
rndCode.Next(65, 90) : rndCode.Next(48, 57);
string chr = ((char)asciiCode).ToString();
password.Append((rndCase.Next(0, 3) == 1) ?
chr.ToLower() : chr.ToUpper());
}
return password.ToString();
}
}
Figure 2. Here's an example of a Web service that returns a password of the specified length containing random, mixed-case alpha-numeric characters.
No more passwords like DarthVader4, Rover16, and so on. So, if you want to incorporate this Web service into your own Web site as a way to generate or suggest a strong, random password for a user automatically, you first would need to create the proxy class that will do most of the heavy lifting for you. Here is the command for creating the proxy class using the WSDL tool:
wsdl /out:WsdlExampleProxy.cs
/language:CS
http://localhost/WsdlExample/WsdlExample.asmx?wsdl
There are many other switches and arguments you can pass in but, most of the time, your command will look similar to this. Keep in mind that C# is the default language used by this tool, so you even can drop that argument from the command if C# is your language choice.
The class file output is a product of the tool parsing the WSDL document and structuring the proxy such that it will communicate with the Web service using the correct SOAP formatting. Figure 3 shows what the proxy class looks like using the WSDL command.
[DebuggerStepThroughAttribute()]
[DesignerCategoryAttribute("code")]
[WebServiceBindingAttribute(Name="WsdlExampleSoap",
Namespace="http://tempuri.org/")]
public class WsdlExampleProxy : SoapHttpClientProtocol {
public WsdlExampleProxy() {
this.Url =
"http://localhost/WsdlExample/WsdlExample.asmx";
}
[SoapDocumentMethodAttribute(
"http://tempuri.org/GetRandomPassword",
RequestNamespace="http://tempuri.org/",
ResponseNamespace="http://tempuri.org/",
Use= SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]
public string GetRandomPassword(int length) {
object[] results = this.Invoke("GetRandomPassword",
new object[] {length});
return ((string)(results[0]));
}
public IAsyncResult BeginGetRandomPassword(
int length, AsyncCallback callback, object aState) {
return this.BeginInvoke("GetRandomPassword",
new object[] {length}, callback, aState);
}
public string EndGetRandomPassword(
IAsyncResult asyncResult) {
object[] results = this.EndInvoke(asyncResult);
return ((string)(results[0]));
}
}
Figure 3.The proxy class generated by the WSDL tool takes care of constructing all the SOAP plumbing and formats the Request and Response. This simplifies the task of calling the Web service such that the process is indistinguishable from calling a method in a local assembly.
Notice that the generated class contains a GetRandomPassword method with the same signature as its Web service counterpart. This probably is the only part of the class you will ever need to think about, but you certainly can do some research to educate yourself on the rest of the SOAP formatting syntax if it interests you. Now, if you take this file and compile it into your Web application, it can be called like this:
WsdlExampleProxy proxy = new WsdlExampleProxy();
string password = proxy.GetRandomPassword(8);
That's all it takes. Because the proxy class handles all the SOAP plumbing, you remain free to call the Web service as if the GetRandomPassword method were located in an assembly on your local Web server. Such is the magic of Web services, and such is the convenience of the WSDL tool.
References
WSDL Specification: http://www.w3.org/TR/wsdl
Introduction to WSDL: http://www.learnxmlws.com/tutors/wsdl/wsdl.aspx
A working example of the WSDL in action is available for download.
Ken McNamee is an independent consultant who works with companies in need of highly scalable data-driven Web applications. And who doesn't need one of those these days? Before this, he led a team of developers in re-architecting the Home Shopping Network's e-commerce site, HSN.com, to 100 percent ASP.NET with C#. E-mail him at [email protected].
Tell us what you think! Please send any comments about this article to [email protected]. Please include the article title and author.
