Windows Client for the XML Web Services Four Function Calculator
See all Sams Teach Yourself on InformIT Web Development Tutorials.
In this hour, you will learn to create client applications that consume XML Web services. You will also learn how to create proxy classes that enable your application code and XML Web services to easily communicate via SOAP messages. Also in this hour, you will see how to use the WebServiceUtil.exe file to accomplish many important XML Web servicerelated tasks.
In this hour, we will discuss the following items:
Consuming XML Web services
Using dialogs to create proxy classes
Adding Web references
Using the WSDL.exe
Creating a Client Application
Since an XML Web service lacks any real interface of its own, it requires that client applications be built to use its functionality. Client applications can range from ASP applications and Windows-native applications to simple Web pages that use get and post form methods to communicate with a service.
In Hour 9, you will learn to create applications that make use of XML Web services via scripting code and form methods; for now, we will focus on creating Windows-native clients and ASP applications that use XML Web services.
Building the Four Function Calculator Client Application
Create a Windows application and call it CalcClient. Create a form in the CalcClient application that contains three text boxes and four buttons. Set up the form to look like Figure 8.1. For convenience, leave the name property of all the controls to the default settings (that is, Button1, Button2, and so on).
Figure 8.1 The client for the four function calculator.
To use your four function calculator XML Web service, you need to create a proxy class to handle the calls to your service. What the proxy class does is expose methods to your application that are identical to the methods used by the XML Web service. For example, if you have an XML Web service method named Chance that accepts an integer and a string and returns a long, your proxy class will also have a method named Chance that accepts and integer and a string and returns a long.
Behind the scenes, the proxy class wraps your parameters (an integer and a string in this example) into a SOAP call to the Web class method (Chance in this case). The Web class then returns a SOAP package containing the long return value to the proxy class, which unwraps it and passes the long value to your application.
Creating the Proxy Class
To create the proxy class to your XML Web service, choose Add Web Reference from the Project menu of Visual Studio .NET. When you use this wizard, Visual Studio creates and compiles the proxy class into a DLL and includes a reference to it in your project automatically.
After you choose Add Web Reference, the screen in Figure 8.2 is displayed. From this screen, you are able to choose known local XML Web services by clicking the link Web References or Local Web Server, or you can seek other services via the link Microsoft UDDI. For this example, we will use the local link.
If you wish to review how to use UDDI in searching for XML Web services, reread Hour 5.
Figure 8.2 Using the Web Reference dialog.
Now Visual Studio brings up a list of all the discovery (DISCO) files as Linked Reference Groups, related services that are usually members of the same project, on your local server (see Figure 8.3). Search through this listing and find the URL to FourFunctionCalc.disco.
Figure 8.3 Finding the XML Web service on the server.
After you select the link to an XML Web service (in this case, Service1 of your FourFunctionCalc Group), the discovery file is displayed on the screen, and you are provided with links to the contract and documentation for this service (see Figure 8.4). These links are important when you are using multiple XML Web services to develop applications and you cannot remember what they all do.
Figure 8.4 Viewing the DISCO file of the XML Web service.
Choose the link View Documentation to bring up the auto-generated documentation files (seen in Figure 8.5) that you became familiar with in Hour 7. If you choose the View Contract link, the XML Web services WSDL file is displayed in place of documentation file in Figure 8.5.
The ability to understand the XML syntax of the WSDL document is a major boon when you are trying to decide whether a given XML Web service meets the needs of your application. If you are having trouble deciphering the WSDL files, go back and reread Hours 2 and 3 again.
Figure 8.5 Viewing the documentation of the XML Web service.
After you have navigated to the service that you wish to reference in your project, click the Add Reference button and Visual Studio.Net will add the appropriate reference to your project and create a proxy class for the service.
Now that Visual Studio.NET has created the proxy class for you and included it in your CalcClient application, you can add any other references that you need for your project. In this case, you will need to add a reference to the System.Web.Services.dll. This DLL exposes some extra functionality that comes in handy when developing XML Web service clients, and it is good practice to include it in your client applications.
To add the System.Web.Services.dll to your project, choose Add Reference from the Project menu. This brings up the Add Reference window, shown in Figure 8.6. Double-click the System.Web.Services.dll to display it in the bottom window, Selected Components. Once you have done this, you can click Okay to close the window and add the reference to your project.
Figure 8.6 Adding a reference to the System.Web. Services.dll.
Using a Web Service Proxy Class in Client Applications
Now that you have a reference to the FourFunctionCalc XML Web service, you can create an instance of it in your application. Add the following line of code to the general declarations section of your client application's Form1.
Dim oCalc As New localhost.Service1()
If you are using C#, your object declaration should be the following:
localHost.Service1 oCalc = New localhost.Service1;
With the new oCalc object created in your application, you can begin using the methods of the XML Web service, via the proxy, in your application. The general syntax for calling a XML Web service's method is
where proxyObject is the name of your object, oCalc is the case of your CalcClient application, and MethodName is the name of the method that you are trying to access. Any arguments that the XML Web service's method expects are represented by args.
One tremendous benefit of the proxy class is that, because it contains local methods for all the methods exposed by the service, it allows you to take advantage of Visual Studio .NET's autocompletion features. This saves you from having to memorize all of the function calls and their methods when you try to implement a service in your applications.
Listing 8.1 shows the Visual Basic code to add the FourFunctionCalc methods to the button-click events of your form. Each of the calls uses the CInt function to convert the contents of the text boxes into the integer variables that the method requires. You then use the ToString method to convert the type long answer returned by the service's method into a string that can be displayed in the output text box.
Listing 8.1 The Four Function Calculator's Button Events
1: Protected Sub Button1_Click(ByVal sender As Object, _ 2: ByVal e As System.EventArgs) 3: 4: TextBox3.Text = oCalc.Add(CInt(TextBox1.Text), _ 5: CInt(TextBox2.Text)).ToString 6: 7: End Sub 8: 9: Protected Sub Button2_Click(ByVal sender As Object, _ 10: ByVal e As System.EventArgs) 11: 12: TextBox3.Text = oCalc.Subtract( _ 13: CInt(TextBox1.Text), CInt(TextBox2.Text)).ToString 14: 15: End Sub 16: 17: Public Sub Button3_Click(ByVal sender As Object, _ 18: ByVal e As System.EventArgs) 19: 20: TextBox3.Text = oCalc.Mulitply(CInt(TextBox1.Text), _ 21: CInt(TextBox2.Text)).ToString 22: 23: End Sub 24: Public Sub Button4_Click(ByVal sender As Object, _ 25: ByVal e As System.EventArgs) 26: 27: TextBox3.Text = oCalc.Divide(CInt(TextBox1.Text), _ 28: CInt(TextBox2.Text)).ToString 29: 30: End Sub
Once you have finished coding the button-click events, save your project. Now, choose Start from the Build menu, or simply press F5. This will start the CalcClient application, shown in Figure 8.7.
Figure 8.7 The four-function calculator at work.
Try typing some variables and testing that the code works. Remember that we have not added any code to ensure that only integers are typed into the text boxes. If you wish to add code to ensure that the data entered into TextBox1 and TextBox2 is of type integer, you are free to do so.