Using a Web Service

A large number of Web services projects will involve the construction of a client application. At least a couple of reasons for this exist. First, the use of a Web service requires a client application. You do not execute a Web service without a client application, except in test mode. A Web service typically has no user interface. Furthermore, one Web service can have multiple client applications. These multiple client applications can expose various Web methods within a Web service or can offer the full set of Web methods available from a Web service in various environments. As an example, this section shows two clients that apply to a single Web service. The first client is a Web application. The second client is a Windows application. You use the same general approach to the construction of each client application.

Building a Web Application Client for a Web Service

To start the construction of the Web application, create a new ASP.NET Web Application project named WebZipCodeClient. Before you can build a client for a Web service, the client application needs a reference to the Web service. Several variations for building this reference exist. When the reference exists in a UDDI registry, you can select it from the registry. This sample draws on a Web service to resolve zip codes based on a street address, city, and state, along with an access code. At the writing of this chapter, the Web service we re using in this example resides in the Test Microsoft UDDI Directory. Microsoft makes this UDDI directory available as a test registry for Web service demonstration projects. The Web services in the registry are provided by third-party organizations.

Adding a Web Reference to a Project

Choose Project, Add Web Reference to show the Add Web Reference dialog box. The left pane contains a link to the Test Microsoft UDDI Directory. Click the link. Next, you need to enter the name of a third-party organization supplying the Web service. EraServer.Net is the name of the third-party organization supplying the zip code resolver for the current application. Therefore, type EraServer.Net in the Business Name text box, and click Search. Scroll down the resulting list in the left pane until you see EraServer.Net: ZipCodeResolver . Click the expand button (+) to expose the tModel for the Web service. A tModel uniquely identifies a Web service within a UDDI registry.

Figure 12-1 shows the cursor pointing at the description of the ZipCodeResolver Web service. A small box opens to display the URL or port for accessing the Web service, http:// webservices .eraserver.net/zipcoderesolver/zipcoderesolver.asmx . The .asmx file is the access point for the Web service. Clicking the name of the tModel opens in the left pane of the Add Web Reference dialog box the WSDL script that describes the Web service. One important role of the WSDL script is to define a contract for the Web service. For example, the contract states that if a client application invokes one Web method with a list of arguments, the Web service will return a result in a specific format, but if a user invokes another Web method within the Web service, the client will return a different result in another format. Therefore, the WSDL script serves as a contract between a Web service and its client applications.

Figure 12-1: The Add Web Reference dialog box exposing the tModel for a Web service that resolves zip codes

Clicking the Add Reference button in the dialog box adds a reference named net.eraserver.webservices to the WebZipCodeClient project. This reference appears in Solution Explorer as a subfolder within the Web References folder. The net.eraserver.webservices reference contains two entries pointing at files: Reference.map and zipcoderesolver.wsdl. The Reference.map file designates the entry point for the Web service on the host computer. As mentioned, this point is an .asmx file. The zipcoderesolver.wsdl file contains the WSDL script that describes the Web service. Visual Studio .NET uses the contents of the Reference.map and zipcoderesolver.wsdl files when your application invokes Web methods through a proxy object that points at the Web service. The proxy object exposes in a client application the Web methods for a remote Web service hosted on another computer.

Note  

Web services do not require that the host computer and client computer be two separate computers. However, you do not need Web services for a one-computer scenario because you can simply reference a class that is already on a computer. The significant benefit of Web services is to enable you to reference a class (the Web service) on one computer (the host) from a second computer (the client).

Learning About a Web Service

The .wsdl file does not contain the code implementing the Web methods, but the file identifies how to communicate with those methods. For example, the .wsdl file names the Web methods as types, and it specifies the inputs and outputs from the Web methods. This is the minimum that you need to invoke a Web method from a Web service on a remote computer. When developing a client to invoke a Web service, you need to perform due diligence so that you grasp the role of each Web method that you want to use within a Web service. This includes having a thorough understanding of the input and output requirements. The input and output definitions in the .wsdl file do not eliminate the requirement for due diligence. The .wsdl file contents in the client application are for use by Visual Studio .NET in sending a SOAP message to the host computer and in interpreting a SOAP message from the host computer.

Although you need to know more about a Web service than its .wsdl file tells you, the .wsdl file contains valuable clues about it. The following excerpt from the zipcoderesolver.wsdl file identifies the inputs and outputs for the FullZipCode and ShortZipCode methods in the ZipCodeResolver Web service. (A few especially long, logical lines in the listing from the .wsdl file wrap onto a second line in order to fit on the book page.) As you can see, WSDL script is verbose, but this characteristic helps to make it relatively easy to read and understand, even if you do not have a firm grasp of XML syntax.

Notice that the format for the excerpt includes tags, such as s:element , that sometimes contain attribute settings. Furthermore, some tags are hierarchically organized. For example, the FullZipCode element contains four other elements: accessCode , address , city , and state . These nested elements define the arguments for the FullZipCode Web method within the Web service. The attribute settings for the nested arguments are all strings, and they can occur in the call statement no more than once ( maxOccurs ="1"). But these arguments do not have to appear ( minOccurs ="0") for the Web method to return a response. The FullZipCodeResponse and ShortZipCodeResponse elements define return values from the methods.

 <s:element name="FullZipCode"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="accessCode" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="address" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="city" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="state" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="FullZipCodeResponse"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="FullZipCodeResult" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="ShortZipCode"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="accessCode" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="address" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="city" type="s:string" /> <s:element minOccurs="0" maxOccurs="1" name="state" type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="ShortZipCodeResponse"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="ShortZipCodeResult" type="s:string" /> </s:sequence> </s:complexType> </s:element> 

Showing Design and Operational Views

Figure 12-2 shows a Design view and an operational view of the client application. The top window in the figure contains three text boxes with corresponding labels separated from a fourth text box and its label by a Button control. The top three buttons are for the street , city , and state arguments to the FullZipCode Web method. Clicking the Button control ( Button1 ) invokes the Web method and assigns the return value to the Text property of the last TextBox ( TextBox4 ) on the Web page.

Figure 12-2: Design and operational views of a Web application client for the ZipCodeResolver Web service

The bottom window shows the page with my address in the top three text boxes after I clicked the Button control. A little experimentation with the client application indicated that the Web service does not always return a zip code. For example, when I input an address known to be bogus , the return zip code was 00000-0000. In addition, I input selected addresses of my seminar registrants. Some of these addresses worked, but others failed. Try the Web service for your address and see whether it works. This kind of experimentation is part of the due diligence that you need to perform when evaluating a Web service for use in your applications. As stated earlier, this Web service is merely a test service to illustrate general application issues. It is not meant for use in production environments.

The Code Behind the Web Page

The code behind the Web page in Figure 12-2 consists of a Page_Load procedure and a Button1_Click procedure. The Page_Load procedure makes the initial assignments of the Text and TabIndex property values for the controls on the Web page. After the initial assignments, the Web page automatically restores the values from the last round-trip of a page or assigns any new values made by a user to the controls on the page.

The most significant part of this application is in the code for the Button1_Click procedure. The Dim statement for wsc1 shows the syntax for declaring and instantiating a proxy variable. IntelliSense helps you write out the reference to the ZipCodeResolver Web service from the net.eraserver.webservices Web reference. As mentioned, the Web reference name appears in the Web References folder of Solution Explorer for the WebZipCodeClient project. After the New keyword, all you need to specify is net . Then, IntelliSense offers a menu for selecting each additional element name for the proxy class. The assignment statement in the Button1_Click procedure demonstrates the syntax for invoking a Web method with the proxy variable. Again, IntelliSense offers a menu of items to select after you specify the proxy variable name.

 Private Sub Page_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load Make initial control assignments If Not IsPostBack Then Assign Text property values Label1.Text = "Street address" Label2.Text = "City" Label3.Text = "State" Label4.Text = "Zip Code" Button1.Text = "Add Zip Code" Assign tab order for controls TextBox1.TabIndex = 1 TextBox2.TabIndex = 2 TextBox3.TabIndex = 3 Button1.TabIndex = 4 End If End Sub Private Sub Button1_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles Button1.Click Designate wsc1 as a proxy variable for the ZipCodeResolver Web service Dim wsc1 As New net.eraserver.webservices.ZipCodeResolver() Pass four arguments to the FullZipCode Web method TextBox4.Text = wsc1.FullZipCode("9", _ TextBox1.Text, TextBox2.Text, TextBox3.Text) End Sub 

As you can see, Visual Studio .NET trivializes invoking a Web service on another computer in a remote location from the client application. The combination of the powerful technology that Web services exposes and its ease of use make Web services an exciting way to build that draws on the resources of multiple computers and organizations with varied skills. A subsequent sample in this chapter will illustrate how to extend the reach of Access databases via Web services.

Building a Windows Application Client for a Web Service

One of my favorite Web services features in Visual Studio .NET is that you can both create and consume a Web service from a Windows application. This means that everything you already know about creating Windows solutions and ADO.NET solutions applies transparently to Web services. For example, a Windows Form object can serve as a client for the ZipCodeResolver Web service just as the Web page in the preceding sample did. Many Access developers find Windows Forms a more natural environment, so this capability is good for us. The key is that you must have an open connection to the Web through which you connect to your Web service. If the Web service is located at an Internet site, you need an open Internet connection from the computer running the Windows application. On the other hand, you can connect to a Web service via your local intranet, which does not require Internet connectivity.

Building the Windows Application Client

Open a new Windows application project. You can name it WindowsZipCodeClient to correspond to the convention for the previous Web application client. Then, add a Web reference to the ZipCodeResolver Web service. You can follow the same steps described in the previous sample. Whether you are adding a Web reference to a Web application or to a Windows application, the process is the same.

After adding the Web reference, you can add controls to Form1 in the WindowsZipCodeClient project for collecting address information and displaying the resolved zip code. Figure 12-3 shows Design and operational views of the Windows form. The Design view in the left window shows an arrangement of controls that mimics those for the Web page in the preceding sample. Of course, some minor differences exist between the way controls behave in a Windows Forms instance and the way they behave in a Web page. Two salient issues are the contents of the text boxes and the sizing of the Button control. The TextBox controls in Form1 are not blank by default (as they are in a Web page). Instead, the TextBox controls have unique Name property assignments that appear as their Text properties. It is normal practice in Windows Forms programming to clear the Text property settings for text boxes. In addition, Button controls on a Windows Forms instance do not automatically expand to accommodate the size of the Text property setting (as a Button control on a Web page does). Because the Text property assignment is longer than the default Width property setting for Button1 , the client application needs to assign a new Width property to Button1 .

12-3 : Design and operational views of a Windows application client for the ZipCodeResolver Web service

The window on the right in Figure 12-3 shows the operational view of the Windows client. I entered my address and clicked the Add Zip Code button ( Button1 ). After its click event procedure executed, the application populated the Zip Code text box ( TextBox4 ). The computer running the sample had an open Internet connection so that it could invoke the ZipCodeResolver Web service at EraServer.net within the Button1_Click procedure.

The Code Behind Form1

The code behind Form1 in the Windows application client is similar to that behind the WebForm1 page in the Web application client. The Form1_Load procedure in the Windows application corresponds roughly to the Page_Load procedure in the Web application. In addition, the Button1_Click procedure is identical in both the Windows application and the Web application. Therefore, the only differences between the two clients are cosmetic ones related to how Windows and Web applications process form controls.

The Form1_Load procedure starts with the same code that appears in the Page_Load procedure for assigning the Text and TabIndex properties of selected controls on the form. However, the Form1_Load procedure has additional code for formatting the TextBox and Button controls. A loop passes through all the controls on Form1 and assigns a zero-length string to the Text property of any TextBox control. In addition, a Size structure assignment revises the default Width property of Button1 to 100 pixels. This widens the control from its default Width property value of 75 pixels so that Button1 does not crop its Text property value when Form1 displays.

 Private Sub Form1_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load Assign Label Text property values Label1.Text = "Street address" Label2.Text = "City" Label3.Text = "State" Label4.Text = "Zip Code" Assign tab order for controls TextBox1.TabIndex = 1 TextBox2.TabIndex = 2 TextBox3.TabIndex = 3 Button1.TabIndex = 4 Assign zero-length strings to all text boxes on the form Dim ctl1 As Control Dim str1 As String For Each ctl1 In Me.Controls If ctl1.GetType.ToString = _ "System.Windows.Forms.TextBox" Then ctl1.Text = "" End If Next Format button control Button1.Text = "Add Zip Code" Button1.Size = _ New System.Drawing.Size(100, Button1.Height) End Sub Private Sub Button1_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles Button1.Click Designate wsc1 as a proxy variable for the ZipCodeResolver Web service Dim wsc1 As New net.eraserver.webservices.ZipCodeResolver() Pass four arguments to the FullZipCode Web method TextBox4.Text = wsc1.FullZipCode("9", _ TextBox1.Text, TextBox2.Text, TextBox3.Text) End Sub