Accessing an XML Web Service Through a Proxy Class

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:

Use the Wsdl.exe tool to generate the source code file for the proxy class.
Compile the source code file for the proxy class.
Copy the compiled proxy class into the ASP.NET application's /bin directory.

NOTE

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.

CAUTION

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.

graphics/22fig03.jpg

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:

/nologo: Prevents the banner text for the Wsdl.exe tool from being displayed.
/language: or /l: By default, classes are generated using the C# language. You can specify CS for C#, VB for Visual Basic, VJS for J#, or JS for JScript.
/server: Generates an abstract class for the Web service instead of the default proxy class.
/namespace: or /n: Specifies the namespace to use for the proxy class. By default, the proxy class uses the global namespace.
/out: Indicates the filename for the proxy class.
/protocol: Indicates the protocol to use with the proxy class. By default, a proxy class uses the SOAP protocol. You can specify SOAP , SOAP12 , HttpGet , or HttpPost .
/username: or /u: Specifies the username to use when connecting to a server that requires authentication.
/password: or /p: Indicates the password to use when connecting to a server that requires authentication.
/domain: or /d: Specifies the domain to use when connecting to a server that requires authentication.
/proxy: Specifies the URL of a proxy server to use for HTTP requests (defaults to Internet Explorer settings).
/proxyusername: or /pu: Specifies the username to use with the proxy server.
/proxypassword: or /pp: Specifies the password to use with the proxy server.
/appsettingurlkey: or /urlkey: Specifies the Url property for the Web service proxy class from a key in the <appSettings> section of the web.config file.
/appsettingbaseurl: or /baseurl: Specifies the base URL for the Web service proxy class from a key in the <appSettings> section of the web.config file.

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.

NOTE

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:

AllowAutoRedirect A Boolean value that specifies whether a request to a Web service can be automatically redirected to another URL (default value is False ).
ClientCertificates X509CertificateCollection of client-side certificates.
CookieContainer A CookieContainer that contains the cookies associated with the proxy class.
Credentials A class implementing ICredentials (such as NetworkCredential ) that can be used for Basic, Digest, NTLM, or Kerberos authentication.
PreAuthenticate A Boolean value indicating whether a WWW-authenticate header is sent with each request (default value is False ).
Proxy A class implementing IWebProxy that contains information for making requests through a firewall.
RequestEncoding The character encoding used for proxy requests.
Timeout An integer value in milliseconds that specifies when a proxy request times out (default is -1 which represents infinity).
UserAgent A string that specifies the value of the User -Agent header. The default is MS Web Services Client Protocol .
Url The URL used by the proxy when making requests.

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.