You can access a Web service from within an application by creating a Web service proxy class . This type of proxy class is a local representation of the properties and methods of a remote Web service class.
After you create a proxy class, you can treat the class exactly like any other .NET framework class. For example, imagine that the TemperatureService Web service is hosted at an Internet service provider located in central Borneo. After you create a proxy class, you can invoke the methods of the remote Web service class within your application as though the class were located on your computer.
Generating an XML Web Service Proxy Class
You can generate a proxy class by using the Wsdl.exe (Web Services Description Language tool) command-line tool included with the .NET Framework Software Development Kit. To generate a proxy class, you need to complete the following steps:
If you install Visual Studio .NET, then you cannot execute the command-line tools from the default command prompt (the proper path environmental variable is not set). Instead, you need to execute the compiler by opening the Visual Studio .NET Command Prompt located at Start, Programs, Microsoft Visual Studio .NET, Visual Studio .NET Tools.
To compile a proxy class for the TemperatureService Web service, for example, you would execute the Wsdl.exe tool from a command line prompt like this:
wsdl.exe /l:vb http://www.YourSite.com/Services/TemperatureService.asmx?wsdl
The /l switch indicates the language used for generating the source code file for the proxy class. Because you want to generate a Visual Basic class, you supply the argument vb .
The Web address supplied to the tool is the address of the Web service Description Language (WSDL) file for the Web service. You can always retrieve the WSDL file for a Web service by appending the query string ?wsdl to its address.
A WSDL file is an XML file that describes all the methods and properties of a Web service. This file is generated automatically for you. If you're curious , you can view the WSDL file for a Web service by opening the Web Service Help page and clicking the Web Service Description Language link.
You can use localhost to refer to the current server when generating a proxy class with the Wsdl.exe tool. Typically, however, using this server is not a good idea. If you use localhost then, by default, the proxy class works only on the same computer as the Web service.
Executing the Wsdl.exe tool generates a file named TemperatureService.vb that contains the source code for a Visual Basic class file. You can open this file in Notepad if you want to see its contents.
Before you can use the TemperatureService.vb file, you first need to compile it by executing the Visual Basic command-line compiler like this:
vbc /t:library /r:System.dll,System.Web.Services.dll,System.Xml.dll TemperatureService.vb
This statement references all the needed assemblies to compile the TemperatureService.vb file into a DLL file.
After the class is compiled, you need to copy it to your ASP.NET application's /bin directory so that it is visible to your ASP.NET pages. If the /bin directory does not exist, you can create it.
Using an XML Web Service Proxy Class
After you create the Web service proxy class and copy it to your /bin directory, you can start using the class in your applications. For example, the page in Listing 22.5 invokes the TemperatureService Web service from within an ASP.NET page (see Figure 22.3).
Listing 22.5 ConvertTemperature.aspx
<Script Runat="Server"> Sub Button_Click( s As Object, e As EventArgs ) Dim objTemp As New TemperatureService lblCelsius.Text = objTemp.ToCelsius( txtFahrenheit.Text ) End Sub </Script> <html> <head><title>ConvertTemperature.aspx</title></head> <body> <form Runat="Server"> Fahrenheit: <asp:TextBox ID="txtFahrenheit" Runat="Server" /> <asp:Button Text="Convert!" OnClick="Button_Click" Runat="Server" /> <hr> <asp:Label ID="lblCelsius" Runat="Server" /> </form> </body> </html>
The C# version of this code can be found on the CD-ROM.
Figure 22.3. The ConvertTemperature.aspx page.
The page in Listing 25.5 displays a Web form that contains a TextBox and Button control. When you enter a number into the TextBox control and submit the form, the Button_Click subroutine is executed.
The Button_Click subroutine creates an instance of the TemperatureService Web service proxy class. Next, it calls the ToCelsius method of the proxy class to convert the temperature entered into the form from degrees Fahrenheit to degrees Celsius. Finally, the converted number is displayed in a Label control named lblCelsius .
From the perspective of the ASP.NET page in Listing 25.5, the proxy class is just a normal .NET class. However, when you call one of the methods of the proxy class, a lot of work happens behind the scenes. A SOAP message must be sent across the network to the TemperatureService Web service, and a response must be returned. Even if the TemperatureService Web service were located on the other side of the world, the page would still work.
Working with the Web Services Description Language Tool
In the preceding section, you used the Web Services Description Language tool (Wsdl.exe) to generate the source code for the Web service proxy class. This section goes into the details of how this tool works.
You can use any of the following options with Wsdl.exe:
The protocol option is particularly important. You can use it to create proxy classes that use HTTP-Post or HTTP-Get instead of the default SOAP protocol. Using a protocol other than SOAP can result in better performance because less data needs to be sent over the wire. However, the HTTP-Get and HTTP-Post protocols support fewer data types than SOAP.
The /appsettingurlkey option is also interesting. It enables you to avoid hardwiring the location of the Web service into the proxy class. If you specify a value for this option, the proxy class will first attempt to retrieve the URL for the Web service from the web.config file. Otherwise, the proxy class will use the URL from the WSDL file.
You can supply three types of documents to the Wsdl.exe tool: WSDL contract files, XSD schemas, and .discomap discovery files. The tool generates a proxy class from any of these file types.
You can use the Web service Discovery Tool (Disco.exe) to generate .discomap files.
To specify the location of a WSDL contract file or an XSD schema, you can provide either a URL or the path to a file on your hard drive. (You are required to specify a file path in the case of a .discomap discovery file.) For example, you can save the WSDL contract file generated by the Web Service Help Page to your hard drive and generate a proxy class based on the saved file.
Setting Proxy Class Properties
A Web service proxy class derives from the SoapHttpClientProtocol class. Many of the properties of this class are useful for controlling the behavior of your Web service. Here is a list of some of the more useful of these properties:
For example, if you want to ignore slow responses from Web sites, you might want to change the default Timeout value to a shorter value. We'll use the CookieContainer property in the final section of this chapter (in the section entitled "XML Web services and Session State") to enable session state in a Web service.