Instantiating and Invoking Web Services

   

---

After you've discovered a Web service and retrieved information about its interface, you can instantiate an object representing that Web service and then invoke its methods. In this section, you'll see two methods to integrate Web services into your applications, and you'll learn about testing a Web service as a consumer.

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 that you can use to invoke the Web service, as seen in Step by Step 4.8.

STEP BY STEP

4.8 Using the Web Services Description Language Tool

1. Select Start, Programs, Microsoft Visual Studio .NET, Visual Studio .NET Tools, Visual Studio .NET Command Prompt. This opens a command prompt window and sets up the environment 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 that you created in Step By Step 4.7.

3. Enter the following command to create a proxy class to call the Airport Weather Web service:

    wsdl /language:VB /out:aw.vb AirportWeather.wsdl 

4. The tool reads the WSDL file and creates a new file named aw.vb .

5. Add the aw.vb file to your Visual Studio .NET Windows application project by selecting File, Add Existing Item.

6. Add a new Form to your Visual Basic .NET Windows project.

7. Place a Label control, a TextBox control named txtCode , a Button control named btnGetSummary , and a ListBox control named lbResults on the Form. Use the same form design that you saw in Figure 4.2.

8. Double-click the Button control to open the Form's module. Enter this code to invoke the Web service when the user clicks the button:

    Private Sub btnGetSummary_Click(_  ByVal sender As System.Object, _  ByVal e As System.EventArgs) _  Handles btnGetSummary.Click     ' Connect to the Web service by declaring     ' a variable of the appropriate type     Dim aw As AirportWeather = _      New AirportWeather()     ' Call the Web service to get the summary     ' for the entered airport     Dim ws As WeatherSummary = _      aw.getSummary(txtCode.Text)     ' Display some of the properties     ' filled in by the Web service     With lbResults.Items         .Clear()         .Add(ws.location)         .Add("Temperature: " & ws.temp)         .Add("Visibility: " & ws.visibility)         .Add("Wind: " & ws.wind)     End With End Sub 

9. Set the Form as the startup object for the project.

10. Run the project and fill in a value for the airport code. Click the button. After a brief pause while the Web service is invoked, you'll see some information in the ListBox control, as shown in Figure 4.3. This information is delivered from the server where the Web service resides as properties of the WeatherSummary object. The difference between this and the version that you saw at the start of the chapter is that this code defines the objects that it uses explicitly rather than discovering them at runtime. The AirportWeather and WeatherSummary objects are proxy objects that pass calls through to the Web service and return results from the Web service.

Table 4.2 shows some of the command-line options that 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 4.2. Command-line Options for wsdl.exe

Option	Meaning
/domain: DomainName	Domain name to use when connecting to a server that requires authentication.
/language: LanguageCode	Specifies the language for the generated class. The LanguageCode parameter can be CS (for C#), VB (for VB .NET), or JS (for JScript).
/namespace: Namespace	Specifies a namespace for the generated class.
/out: Filename	Filename for the generated output. If not specified, the filename will be derived from the Web service name.
/password: Password	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	Username to use when connecting to a server that requires authentication.
/?	Displays full help on the tool.

EXAM TIP

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 it's easier to update the proxy classes 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.

Using Web References

As an alternative to using the Web Service Discovery Tool and the Web Service Description Language Tool to create explicit proxy classes, you can simply add a Web reference to your project to enable the project to use the Web service. You've seen Web references several times in this chapter, starting with Step By Step 4.1.

In fact, in the end result there's no difference between using the tools to create a proxy class and adding a Web reference. That's because, behind the scenes, the Web reference creates its own proxy class. To see this, click the Show All Files toolbar button within 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 4.13.

Figure 4.13. Files generated by adding a Web reference.

The .disco , .wsdl , and .map files are the same files that would be generated by running the Web Service Discovery Tool on the URL of the Web reference. The .vb 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 that you generated with the Web Services Description Language Tool is that the auto-generated file uses a namespace based on the name of the Web reference.

Testing a Web Service

If you'd like to test a Web service without building an entire client application, you can use a testing tool. Several such tools are easily available:

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

• The .NET WebService Studio tool comes from Microsoft. You can download a free copy from http://www.gotdotnet.com/team/tools/web_svc/default.aspx.

• 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 http://www.xmlspy.com/default.asp.

All three of these tools work in the same basic way: They intercept SOAP messages between Web services clients and servers so that you can inspect and, if you like, alter the results. In Step By Step 4.9, you'll use one of these tools to see a Web service in action.

STEP BY STEP

4.9 Testing a Web Service Without a Client Project

1. Download the .NET WebService Studio tool from http://www.gotdotnet.com/team/tools/web_svc/default.aspx and install it on your computer.

2. Launch the WebServiceStudio.exe application.

3. Enter http://live.capescience.com/wsdl/AirportWeather.wsdl as the WSDL EndPoint and click the Get button.

4. The tool reads the WSDL file from the Web service and constructs the necessary proxy classes to invoke it. Click the getSummary entry in the left pane on the Invoke tab to use the getSummary Web method.

5. In the Input section, select the arg0 item. You can now enter a value for this item in the Value section. Enter an airport code such as "KSEA" for the value.

6. Click the Invoke button. The tool sends a SOAP message to the Web service using your chosen parameters and then displays the results, as shown in Figure 4.14.

   Figure 4.14. Invoking a Web service with the .NET WebService Studio Tool.

   

7. Click the Request/Response tab to view the outgoing and incoming SOAP messages.

8. Click the WSDLs & Proxy tab to see the WSDL file and the generated proxy class for this Web service.

REVIEW BREAK

• You can generate proxy classes for a Web service manually by using the Web Services Description Language tool.

• You can generate proxy classes for a Web service automatically by setting a Web reference to point to the Web service.

• You can test and debug a Web service without a client application by using one of several SOAP proxy tools.

---

Top