Instantiating and Invoking Web Services

After you have discovered a Web service and retrieved information about its interface, you can instantiate an object representing that Web service and then invoke its methods .

Creating Proxy Classes with the Web Services Description Language Tool ( wsdl.exe )

The .NET Framework SDK includes the Web Services Description Language tool, wsdl.exe . This tool can take a WSDL file and generate a corresponding proxy class you can use to invoke the Web service. This tool does not require the Web service client to use Visual Studio .NET. The following steps show how to use wsdl.exe :

1. Select Start, Programs, Microsoft Visual Studio, Visual Studio .NET Tools, Visual Studio .NET Command Prompt. A command prompt window opens and the environment is set so that you can use any of the command-line tools from the .NET Framework SDK.

2. Navigate to the folder that contains the WSDL file you created using disco.exe .

3. Enter the following command to create a proxy class to call the AirportWeather Web service: wsdl /language:CS /out:AirportWeatherProxy.cs AirportWeather.wsdl .

   The tool reads the WSDL file and creates a new file, named AirportWeatherProxy.cs .

4. Create a new Visual C# ASP.NET Web application in the current solution and name it Example9_3 . Select Project, Add Reference to add a reference to System.Web.Services.dll .

5. Add the AirportWeatherProxy.cs file to the project by selecting File, Add Existing Item.

6. Place a Label control, TextBox control ( txtCode ), Button control ( btnGetWeather ), and Listbox control ( lbResults ) on the Web form. Change the Text property of the label to Airport Code: .

7. Double-click the Button control and enter the following code to invoke the Web service when the user clicks the Get Weather button:

    private void btnGetWeather_Click(object sender,     System.EventArgs e) {     // Connect to the Web service by declaring     // a variable of the appropriate type     // available in the proxy     AirportWeather aw = new AirportWeather();     // Invoke the service to get a summary object     WeatherSummary ws = aw.getSummary(txtCode.Text);    // And display the results    lbResults.Items.Clear();    lbResults.Items.Add(ws.location);    lbResults.Items.Add("Wind " + ws.wind);    lbResults.Items.Add("Sky " + ws.sky);    lbResults.Items.Add("Temperature " + ws.temp);    lbResults.Items.Add("Humidity " + ws.humidity);    lbResults.Items.Add("Barometer " + ws.pressure);    lbResults.Items.Add("Visibility " + ws.visibility); } 

8. Set the project as the start page for the solution. Select Debug, Start to execute the project.

9. Use the Web form to invoke the Web service. The difference between this project and Example9_1 is that this code explicitly defines the objects it uses rather than discovering them at runtime. The AirportWeather and WeatherSummary objects are proxy objects that pass calls to the Web service and return results from the Web service.

Table 9.1 shows some of the command-line options you can use with wsdl.exe . You don't need to memorize this material, but you should be familiar with the overall capabilities of the tool. You can use either the path to a local WSDL or Disco file or the URL of a remote WSDL or Disco file with this tool.

Table 9.1. Command-line Options for wsdl.exe

Option	Meaning
/domain: DomainName /d: DomainName	Specifies the domain name to use when connecting to a server that requires authentication.
/language: LanguageCode /l: LanguageCode	Specifies the language for the generated class. The LanguageCode parameter can be CS (for C#, which is the default), VB (for Visual Basic .NET), or JS (for JScript).
/namespace: Namespace /n: Namespace	Specifies a namespace for the generated class.
/out: Filename /o: FileName	Specifies the filename for the generated output. If it's not specified, the filename is derived from the Web service name.
/password: Password /p:Password	Specifies the password to use when connecting to a server that requires authentication.
/server	Generates a class to create a server based on the input file. By default, the tool generates a client proxy object.
/username: Username /u:Username	Specifies the username to use when connecting to a server that requires authentication.
/?	Displays full help on the tool.

Using Web References

As an alternative to using the Web Services Discovery and Web Services Description Language tools to create explicit proxy classes, you can simply add a Web reference to your project to enable the project to use the Web service. This is the same technique you used in the Example9_1 project.

In fact, there's no difference in the end result between using the tools to create a proxy class and adding a Web reference because, behind the scenes, the Web reference creates its own proxy class. To see this, click the Show All Files toolbar button in Solution Explorer and then expand the Solution Explorer node for a Web reference. You'll see a set of files similar to that shown in Figure 9.4.

Figure 9.4. When you add a Web reference, the proxy file is automatically generated.

The .wsdl file is the same file that is generated by running the Web Services Discovery tool on the URL of the Web reference, and the .map file is the same as the .discomap file generated by the Web Services Discovery tool. The .cs file defines the proxy objects to be used with the Web service represented by this Web reference, as you can see by opening this file. The major difference between this file and the proxy you generated with the Web Services Description Language tool is that the autogenerated file uses a namespace based on the name of the Web reference.

Why use a Web reference? The major benefit of using a Web reference (as compared to constructing proxy classes with the command-line tools) is that updating the proxy classes is easier if the Web service changes. All you need to do in that case is right-click the Web Reference node in Solution Explorer and select Update Web Reference.

Testing a Web Service

If you want to test a Web service without building an entire client application, you can use a testing tool. Several of these tools are easily available:

• NetTool A free Web services proxy tool from CapeClear. You can get a copy from http://capescience. capeclear .com/articles/using_nettool.

• .NET Webservice Studio This tool comes from Microsoft. You can download a free copy from www.gotdotnet.com/team/tools/web_svc.

• XML Spy Includes a SOAP debugger that can be used to test Web services. You can download a trial copy of this XML editor and toolkit from www.xmlspy.com.

All three of these tools work in the same basic way: They intercept SOAP messages between Web service clients and servers so that you can inspect and, if you like, alter the results.