Consuming a Web Service in Visual Studio .NET

335

7.3 Web-Service Descriptions

Web Service Description Language WSDL is a specification for encoding the definition of a web service as an XML document. This is analogous to providing type information for traditional COM software components. A web-service description identifies the name and URL of a web service, the web methods that are available from that service, the methods parameter names and types, and the methods return types. ASP.NET automatically generates the WSDL documents for web services that it hosts. This document can be viewed by clicking the Service Description link in the service test page refer back to Figur e 7- 1 . A portion of this document for the HelloWebService service is shown in Figur e 7- 4 . Figure 7-4. Viewing a WSDL document As you can see in Figur e 7- 4 , the WSDL document is intended more for tools that can read its contents than it is for humans. As shown in the next section, WSDL documents are used by client tools to generate code that knows how to talk to the given web service.

7.4 Consuming a Web Service

On the .NET platform, consuming a web service is as easy as creating one. This section contains the steps for creating a web-service client that can call the web service shown in Ex am ple 7- 1 .

7.4.1 Consuming a Web Service in Visual Studio .NET

To use a web service from a Visual Studio .NET project, right-click on the References node in the Solution Explorer window, and select Add Web Reference. This causes the Add Web Reference dialog box to appear. 336 In the Address field of the Add Web Reference dialog box, enter the URI of a web-service description document, and click the Add Reference button. When adding references to web services hosted by ASP.NET, the web-service description document is obtained by appending ?wsdl to the path of the service itself. For example: http:www.company.commyWebService.asmx?wsdl or http:localhostWebServicesHello-WebService.asmx?wsdl. Visual Studio .NET reads the web-service description document and builds a corresponding proxy class that knows how to access the described web service. The proxy class is local and exposes the same functionality as the web service. To call the web service from within the project, instantiate the proxy class and call its methods. For example, the following code instantiates the HelloWebService class and calls its SayHello method in response to a button click: Assumes that this code is part of a form having a button named btnOk_Click, a text box named txtName, and a text box named txtResult. Private Sub btnOk_Click _ ByVal sender As System.Object, _ ByVal e As System.EventArgs _ Handles btnOk.Click If txtName.Text Then Dim sName As String = txtName.Text Dim oWS As New localhost.HelloWebService Dim sMsg As String = oWS.SayHellosName oWS.Dispose txtResult.Text = sMsg End If End Sub Note that the web-server machine name is used as the namespace for the web-service class. Thus, for a class called HelloWebService exposed by the same machine as the caller, the namespace is localhost, and the fully qualified name of the class is localhost.HelloWebService. For machine names containing dots, the order of the parts is reversed. Thus, if the HelloWebService service were exposed by a machine named webservices.somecompany.com, the HelloWebService class namespace would be com.somecompany.webservices, and the fully qualified class name of the class would be com.somecompany.webservices.HelloWebService. Internally, the proxy class packages up method calls into SOAP wrappers and forwards them to the web service. This process is transparent to the client of the proxy class.

7.4.2 Consuming a Web Service in Notepad