Consuming XML Web Services

Now that you have seen how Visual Studio .NET helps you to create and publish an XML Web service, you are ready to learn how to create client applications. In this section, Exercise 4.2 shows how to create a Windows application that calls a web service. Exercise 4.3 creates a web page application.

Before you create the client applications, it is important to understand the mechanisms used by client applications to locate and see the methods that an XML Web service offers. The two technologies that are used to do this are discovery, for locating a web service, and Web Services Description Language (WSDL) for describing its functions.

Using Discovery

A discovery document enables clients to obtain information about which XML Web services are available at a given endpoint (or on a web server). This is an XML document with a specific set of tag names. You can create this document manually and place it in a directory on the web server; make sure you use the filename extension .disco. If you are running your XML Web service on Microsoft Internet Information Server (IIS) with ASP.NET, however, a discovery document will be generated whenever a request for it is made by a client. For example, a client can request the following URL for the XML Web service you created in Exercise 4.1:

http://localhost/SquareRootService/square.asmx?disco 

The resulting discovery document will look like Listing 4.2.

Listing 4.2: The .disco File for the SquareRootService

start example
<?xml version="1.0" encoding="utf-8"?> <discovery xmlns:xsd="http://www.w3.org/2001/XMLSchema"         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http:// schemas.xmlsoap.org/disco/">   <contractRef ref="http://localhost/SquareRootService/square.asmx?wsdl"  docRef="http://localhost/SquareRootService/square.asmx"         xmlns="http://schemas.xmlsoap.org/disco/scl/" />   <soap address="http://localhost/SquareRootService/square.asmx"  xmlns:q1="http://tempuri.org/" binding="q1:SquareSoap"         xmlns="http://schemas.xmlsoap.org/disco/soap/" /> </discovery>
end example

The <contractRef> tag in Listing 4.2 is particularly important because it gives the location of the WSDL document, or the contract that states how your Web service works.

Using this type of .disco file is called static discovery. It requires that the client has some prior knowledge about the URL for your web service. Visual Studio .NET also supports something called dynamic discovery. In dynamic discovery, the client is allowed to search all the directories on the web server until it locates an available XML Web service. In this case, there is a .vsdisco file in either the default website directory or in one of your application virtual directories. When you install Visual Studio .NET, a file called Default.vsdisco is placed into the default website directory, and a ServiceName.vsdisco file is placed in the project directory. These files are used by Visual Studio .NET, and you can leave them in place on development servers. However, when deploying a publicly available XML Web service to a production server, you should remove these files and use static discovery.

Listing 4.3 shows the contents of the SquareRootService.vsdisco file that was added by default to the XML Web service project. The default file lists those directories (marked with <exclude> tags) that should remain private on the web server and not be searched by client applications.

Listing 4.3: The SquareRootService.vsdisco File

start example
<?xml version="1.0" encoding="utf-8" ?> <dynamicDiscovery xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17"> <exclude path="_vti_cnf" /> <exclude path="_vti_pvt" /> <exclude path="_vti_log" /> <exclude path="_vti_script" /> <exclude path="_vti_txt" /> <exclude path="Web References" /> </dynamicDiscovery>
end example

Using Web Services Description Language

Web Services Description Language (WSDL) is another defined format of XML tags that are used to describe the contract between the publisher of a web service and their clients. As you saw in the preceding code, the generated discovery document for a web service contains a reference to its WSDL document for further information. A WSDL document shows all the methods of the web service, the arguments that are passed when a method is called, the data types for the arguments, and the data type of the return value of the method call. In the same way that Visual Studio .NET generated the .disco file, Visual Studio .NET will also generate a WSDL document to describe your web service. For example, request the following URL for the XML Web service you created in Exercise 4.1:

http://localhost/SquareRootService/square.asmx?wsdl

The resulting discovery document will look like Figure 4.1. Figure 4.1 shows the partial listing. Test this with the SquareRootService project that you created in Exercise 4.1 to see the full WSDL that is generated.

click to expand
Figure 4.1: The WSDL document for the SquareRootProject

Note 

In conversation, many people pronounce the acronym WSDL as “wiz-dull” rather than spelling it out.

Notice that the methods of the SquareRootServiceGetSquare and GetSquareRoot—are shown. You can also see the parameter name, inputVal, and data type, which is Double. The WSDL document contains all the information that a client application needs in order to call methods of the XML Web service.

A Visual Studio .NET client application interacts with a web service by reading the WSDL information and then using this information to create a proxy class in the client project. The client application programmer can then access a Web service in the same way as they access any local object. In Visual Studio .NET, this proxy class code is generated automatically for you when you add a Web reference to an XML Web service to your client project. If you are not using Visual Studio .NET, a command-line tool called wsdl.exe can be used to generate the proxy class from the WSDL file. Figure 4.2 shows the partial code for a proxy class in a client application that consumes the SquareRootService. When you are working on Exercises 4.2 and 4.3, you will be able to see the complete code.

click to expand
Figure 4.2: The proxy class for the SquareRootProject

After the proxy class is added to your project, you can instantiate objects from the class and call their methods, just as though the web service code was running on your local computer. The code in the proxy class, the runtime, and ASP.NET take care of the details of contacting the XML Web services across the Internet. One thing that you will notice when you get to step 10 in Exercise 4.2 is that the web service proxy has its own namespace. In Visual Studio .NET projects, when you declare or instantiate the web service object, you will need to refer to it by its fully qualified name, like this:

Dim objSquare As SquareRootService.Square = _     New SquareRootService.Square()

After the object is instantiated, you can call its methods just like any other local object:

webResult = objSquare.GetSquare(inputValue) 

In Exercise 4.2, you will create a Windows form application that consumes the SquareRootService XML Web service.

Exercise 4.2: Using an XML Web Service from a Windows Application

start example
  1. Create a new Visual Studio .NET project by using the Windows Application project template. Select an appropriate project directory and name the project SquareRootClientProject.

  2. Rename the default Form1.vb to frmSquares.vb.

  3. Create a user interface for the form that looks like the following graphic. Create two text boxes and two command buttons. Name the controls as follows:

    • TextBox1: txtValue

    • TextBox2: txtResult

    • Button1: btnSquare

    • Button2: btnRoot

  4. Add a Web reference to the SquareRootService. Right-click the SquareRootClientProject in the Solution Explorer and choose Add Web Reference. Type the URL for the SquareRootService: http://localhost/SquareRootService/Square.asmx.

  5. Click the Go button. Displayed in the left pane of the Add Web Reference dialog box, you will see the same test page that you saw when testing the Web service at the end of Exercise 4.1. In the right pane, there are two links. Click the View Contract link to view the WSDL. Click the View Documentation link to redisplay the test page. You might have to click the blue Back button in the toolbar to return to a page containing the View Documentation link.

  6. Click the Add Reference button to add the Web reference to your project.

    click to expand

  7. You will now see a node for Web references added to the Solution Explorer window. Click the Show All Files toolbar button to display all the files. (The Show All Files button is the fourth button from the left, at the top of the Solution Explorer window, as shown here.)

    click to expand

  8. Right-click the localhost node and choose Rename. Change the name to SquareRootService.

  9. You can now view the proxy class that was created. In the Solution Explorer window, under the Web References node, expand the SquareRootService node. You will see a node called Reference.map. Expand that node and you will see Reference.vb. Right-click Reference.vb and choose View Code. Review this code.

  10. Use the Visual Studio .NET menus to choose View Ø Other Windows Ø Object Browser. Expand the SquareRootClientProject node and then expand SquareRootClientProject.SquareRootService and click the Square class. You can see the available methods of the Web service class in the panel on the right, as shown in the following graphic.

    click to expand

  11. Now you can add code to the Windows form to call the methods of the SquareRootService. Create a procedure for the Click event of the Get Square command button. Your code should look like this:

    Private Sub btnSquare_Click(ByVal sender As System.Object, _         ByVal e As System.EventArgs) Handles btnSquare.Click     Dim objSquare As SquareRootService.Square = _         New SquareRootService.Square()     Dim inputValue As Double     Dim webResult As Double     inputValue = CType(txtValue.Text, Double)     webResult = objSquare.GetSquare(inputValue)     txtResult.Text = webResult.ToString     objSquare = Nothing End Sub
  12. Create a similar procedure for the Get Square Root command button, this time calling the GetSquareRoot method.

  13. Save your work. Test the client application by choosing Debug Ø Start from the menu. Type in a value and click one of the buttons. After you have clicked the button, you will notice a slight delay on the first request while ASP.NET loads and compiles the web service, but all subsequent requests will be much faster.

end example

The procedure for creating an ASP.NET Web application that consumes an XML Web service is substantially the same as using a Windows application. Exercise 4.3 shows an example but provides less detail. If any of the steps are unclear, review Exercise 4.2.

Exercise 4.3: Using an XML Web Service from an ASP.NET Web Application

start example
  1. Create a new Visual Studio .NET project by using the ASP.NET Web Application project template. Create the new project at http://localhost/SquareRootClientWeb.

    Use localhost as the server name if you are running a web server on your development machine; otherwise, replace it with an appropriate server name.

  2. Rename the default WebForm1.aspx to SquareClient.aspx. Right-click this file and choose Set As Start Page.

  3. Create a user interface for the form that looks like the next graphic. Create three TextBox Web Forms controls and an HTML Submit button. Name the TextBox controls as follows:

    • txtValue

    • txtSquare

    • txtRoot

      click to expand

  4. Add a Web reference to your project by following the same procedures as in Exercise 4.2. Change the name of the Web reference from localhost to SquareRootService.

  5. Add code to the Page_Load event in SquareClient.aspx.vb to instantiate the object and call its methods. Notice that this code is slightly different from that in Exercise 4.2. Rather than allowing the user to select which method to call, it always runs both on the input value. Your code should look like the following:

    Private Sub Page_Load(ByVal sender As System.Object, _     ByVal e As System.EventArgs) Handles MyBase.Load         If Page.IsPostBack Then             Dim objSquare As SquareRootService.Square = _                 New SquareRootService.Square()             Dim inputValue As Double             Dim webResult1 As Double, webResult2 As Double             inputValue = CType(txtValue.Text, Double)             webResult1 = objSquare.GetSquare(inputValue)             txtSquare.Text = webResult1.ToString             webResult2 = objSquare.GetSquareRoot(inputValue)             txtRoot.Text = webResult2.ToString             objSquare = Nothing         End If End Sub 
  6. Save your work. Test the client application by choosing Debug Ø Start from the menu. Type a value in the Value textbox and click the Submit button. The square and square root of the value that you input should be displayed.

end example

Now that you understand the basics of creating and consuming XML Web services we can look at a way to call those methods asynchronously. When making calls over the Internet or even a busy Intranet, asynchronous calls will allow you manage calls that do not seem to be getting through to their intended destination or taking a long time to complete. You can also provide status messages to your users to let them know that the method call is still in progress. The next section shows how to call Web methods asynchronously.



MCAD/MCSD(c) Visual Basic. NET XML Web Services and Server Components Study Guide
MCAD/MCSD: Visual Basic .NET XML Web Services and Server Components Study Guide
ISBN: 0782141935
EAN: 2147483647
Year: 2005
Pages: 153

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net