Consuming XML Web Services with FrontPage

  • Article

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

July 2002

Company: Jimco

Summary: Learn how to consume a Microsoft .NET XML Web service using FrontPage. (8 pages)

Download FPWebSvc.exe.

Contents

XML Web Services
Requirements for Consuming Web Services
Preparing the Web Service for Use

XML Web Services

One of the most exciting aspects of the Microsoft® .NET Framework is the inclusion of Extensible Markup Language (XML) Web services. A Web service allows for applications to communicate and exchange information in a standards-based manner. Microsoft's implementation of Web services has many inherent benefits. The information is exchanged in XML format, using Hypertext Transfer Protocol (HTTP) and Transmission Control Protocol/Internet Protocol (TCP/IP). Therefore, Web services use existing infrastructure and can be implemented easily in existing environments.

In this article, we will use the EightBall Web service from the Microsoft GotDotNet Web site. We will create a Web page that will send a request to the EightBall Web service. The EightBall Web service will take our request, process it, and send back a response to us which can be displayed on our Web page. This process of using a response from a Web service is known as "consuming" the Web service.

Requirements for Consuming Web Services

Several pieces have to be in place in order to consume a Web service. If you are using Microsoft Visual Studio® .NET, these pieces are automatically put into place for you. However, for the purposes of this article, we will consume the Web service using the Microsoft FrontPage® Web site creation and management tool.

To consume a Web service using FrontPage, you will need:

  • Microsoft .NET Framework Software Development Kit (SDK)
  • Microsoft Internet Information Services (IIS), the Web server built into the Windows® 2000 Server operating system
  • Web service proxy
  • ASP.NET Web form

Microsoft .NET Framework SDK

The Microsoft .NET Framework provides the programming model for Microsoft's .NET platform. It allows us to create robust Web services and applications. The .NET Framework allows us to create the ASP.NET page that is necessary to consume the EightBall Web service. To complete the steps outlined in this article, you will need the .NET Framework SDK.

Microsoft Internet Information Services

We must have a Web server, and the Web server must support ASP.NET. We can use Microsoft Internet Information Services on Windows 2000 or Windows XP. You may need to install necessary security updates as well. You can determine if any updates are needed by visiting Windows Update.

If you install IIS after you install the .NET Framework SDK, you will need to install ASP.NET support by running Aspnet_regiis.exe in your .NET Framework directory. See the Microsoft Knowledge Base for more information.

Web Service Proxy

A client and a Web service communicate using Simple Object Access Protocol (SOAP) messages. See the SOAP site for more information. The Web service proxy is responsible for the formation of the SOAP messages and sending them across the network. This makes it extremely easy to consume a Web service because it is not necessary to concern yourself with mapping out your parameters to XML elements. The Web service proxy consists of a dynamic-link library (DLL) on the local Web server. Using a utility that ships with the .NET Framework SDK called WSDL.exe, we can generate a Microsoft Visual Basic® .NET or C# source code file and then use that file to compile our Web service proxy. This is very easy to do, and we will go into it in detail later.

ASP.NET Web Form

We need to provide the user with a means of asking the magic eight ball a question. We will use an ASP.NET Web form to accomplish that. Because FrontPage does not have the ability to generate ASP.NET components inside the user interface, we will hand-code the Web form in HTML view.

Preparing the Web Service for Use

Assuming that you have installed the Microsoft .NET Framework SDK and Internet Information Services, we can dig right into consuming the EightBall Web service. Here are the steps we will take to consume the Web service:

  1. Examine the Web service.
  2. Generate a source code file.
  3. Compile the Web service proxy.
  4. Design the ASP.NET interface.
  5. Connect the Web service.
  6. Copy the proxy.
  7. Test the ASP.NET application.

Examine the Web Service

To examine our Web service and see what type of information it provides, we browse to the Web service access point. The link for this particular Web service is http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=4ae605e3-a008-427d-abb5-dafae42a1fdb. If you browse to that URL, you will see a list of operations supported by the Web service. In this case, you will see a link to the Ask operation.

Aa140118.odc_fpwsvc01(en-us,office.10).gif

Figure 1: HTTP Post information for the Ask operation

If you click the link to the Ask operation, you will see a sample of the SOAP request and response from the Web service. If you examine the request and response, you will see that the Ask operation expects a string to be passed to it (note the psQuestion=string text in the HTTP POST section) and returns a string. Included on this page is a text box in which you can type a question and receive an answer from the EightBall Web service in XML format.

This information is needed to design an interface in FrontPage to consume this Web service. By examining the information at the Web service access point, we have determined that we need to design a form with a text box to enter a question and a button to submit that question to the Web service. We then need to provide a page element to contain the answer returned from the Web service. We'll get more in-depth about that later. Right now, we need to generate a source code file that we can use to compile our Web service proxy class.

Generate a Source Code File

The actual .NET assembly for a Web service resides on the Web server hosting the Web service. However, a proxy class on the client is responsible for creating properly formatted SOAP requests for the Web service. Therefore, we need to create a .NET assembly on our local Web server to act as the proxy class. Microsoft makes this very easy to do with tools provided by the .NET Framework SDK.

To generate a source code file for our proxy class, we will use the Web Services Description Language utility, WSDL.exe. (See http://www.w3.org/TR/wsdl for more information.) You will find this utility in the directory in which you installed the .NET Framework SDK. (By default, this will be installed in the c:\Program Files\Microsoft Visual Studio .NET\FrameworkSDK\Bin folder.) WSDL.exe will allow us to create a source file for our proxy class.

Before we generate our source file, create a directory in the root of drive C for our Web service files. Call the directory 8Ball. After you have created the directory, we can begin generating the necessary files to consume the EightBall Web service.

To generate a source code file:

  1. Click Start, point to All Programs, point to Accessories, and click Command Prompt to open a command prompt window.

  2. Change to the directory containing the WSDL.exe utility.

  3. At the command line, type the following and press ENTER:

    wsdl /l:VB /o:c:\8ball\8ball.vb http://www.gotdotnet.com/playground/services/EightBall/eightballws.asmx?wsdl

We use the following switches with WSDL.exe to generate our source file:

/l - This switch specifies the language for the source file. In this case, we specified Visual Basic as the language. You can also specify CS (C#) as the language, and a C# source file will be generated.

/o - This switch specifies the name of the output file. A Visual Basic source file should have a .vb file extension. A C# source file should have a .cs file extension.

Note: More information about WSDL can be obtained using the /? switch.

The URL we pass to WSDL is the URL to the Web service contract. The Web service contract is a document that outlines the type of information the Web service expects you to provide and the kind of information that it will return to you. The URL for the Web service contract is simply the URL for the Web service access point with ?wsdl tacked on the end.

We have now successfully generated a Visual Basic .NET source code file that we will use to compile our Web service proxy class.

Compile the Web Service Proxy

Now that we have created our Visual Basic .NET source file, we need to compile it into a Web service proxy. To do that, we will use the Visual Basic .NET compiler that ships with the .NET Framework SDK.

To compile the proxy class, type the following at the command prompt that you have open:

Vbc /t:library /out:c:\8Ball\8BallClient.dll /r:System.dll /r:System.XML.dll /r:System.Web.Services.dll c:\8Ball\8Ball.vb

We use the following switches to generate our proxy class:

/t - This switch specifies the type of assembly to create. In our case, we are compiling a DLL file, so we specify the assembly type as library.

/out - This switch specifies the output file name. Because we specified an assembly type of library, the output file name must have a .dll file extension.

/r - This switch specifies references for the assembly. In this case, we are referencing three Microsoft .NET namespaces that are necessary for all Web service proxy clients. They are the System, System.XML, and System.Web.Services namespaces.

After the compiler finishes compiling the proxy class, you will have a file called 8BallClient.dll in the 8Ball directory on drive C. This is the proxy client. We will move it to the correct location a little bit later. You can close the command-line window, and we'll move on to creating the interface for interacting with the EightBall Web service.

Design the ASP.NET Interface

We now have a general idea of the interface we need to create, and we have successfully compiled a Web service proxy class. Our next step is to create an ASP.NET form to interact with the EightBall Web service.

Before we design the ASP.NET interface, we need to create a FrontPage project. Create a new one-page Web site and call it 8Ball. It is important that you create this site on your Web server with ASP.NET installed.

After you have created the 8Ball site, you need to make sure that it is marked as an application root. To do this:

  1. Click Start, point to Settings, and click Control Panel to open the Control Panel.
  2. Double-click Administrative Tools.
  3. Double-click Internet Services Manager (Windows 2000) or Internet Information Services (Windows XP Professional).
  4. Expand the Default Web Site node so that you can see your 8Ball site. (On Windows XP Professional, you will need to expand the Web Sites node to get to the Default Web Site node.)
  5. Right-click the 8Ball node and choose Properties.
  6. The Properties dialog box should open with the Directory tab showing. If not, click the Directory tab.
  7. In the Application Settings section, click the Create button to make this site an application root.
  8. Click OK.

Your Web is now an application root, and we can proceed with creating our ASP.NET user interface.

We are going to use three ASP.NET Web form controls in our user interface. We will use the TextBox control to enter our question for the EightBall Web service, the Button control to initiate the request to the Web service, and the Label control to display the answer received from the Web service. All of these controls will be contained within an ASP.NET form.

Using Microsoft Visual Studio .NET, it is extremely easy to design a Web form by simply dragging and dropping form elements and setting properties of those elements in the user interface. In our case, we aren't using Visual Studio .NET, so we will need to manually code our form elements.

Creating the Web Form

The first thing we need to do is create the code for the Web form itself. If you are familiar with Hypertext Markup Language (HTML) form code, this code will look very familiar to you. Open the home page for the 8Ball site and switch to HTML view. Type the following code between the existing <body> tags:

   <form runat="server">
   </form>

This code is exactly the same as an HTML form except for the addition of the runat attribute. The runat attribute's value is server, which indicates that this form is an ASP.NET server control. This is an excellent example of the simplicity of ASP.NET. To make an HTML element an ASP.NET server control, we simply add the runat attribute and set the value to server.

At this point, you should go ahead and save this page. Save the page as 8ball.aspx.

Adding the ASP.NET Web Form Controls

Now that we have created our form, we need to add the ASP.NET Web form controls.

First we will add the TextBox control. This is where the user of our Web page will enter a question for the EightBall Web service. To add the TextBox control, add the following code between the opening and closing <form> tags we added previously:

   <asp:TextBox id="tbQuestion" runat="server"/>

This code may look unfamiliar to you if you have never coded in ASP.NET. The asp: appended to the name of the control indicates that this is an ASP.NET Web form control. (For more information, see ASP.NET Web form controls).

Add the remaining code to the page so that your form code appears as follows:

   <form runat="server">
      <asp:TextBox id="tbQuestion" runat="server"/>
      <asp:Button id="btnGo" runat="server" 
      Text="Submit Question" onClick="getAnswer"/><br><br>
      <asp:Label id="lblAnswer" runat="server"/>
   </form>

You may notice that you do not see these controls in Normal view in FrontPage. That is expected and is because these are ASP.NET Web form controls, and FrontPage cannot render them.

Connect the Web Service

If you review the code we've already added, you will see that we are calling a procedure called getAnswer when the button is clicked. This is our server-side procedure that is responsible for the following:

  • Creating an instance of our proxy client class.
  • Calling the Ask function of the EightBall Web service and passing the question we asked to it.
  • Setting the text of our Label control so that it displays the answer received from the Web service.

To create this procedure, add the following code to your page immediately before the closing </head> tag:

   <script runat="server">
   Sub getAnswer(sender as Object, e As System.EventArgs)
      Dim clsEightBall As EightBallWS = New EightBallWS
      Dim strAnswer As String
      strAnswer = clsEightBall.Ask(tbQuestion.Text)
      lblAnswer.Text = strAnswer
   End Sub
</script>

Let's briefly examine this code.

The <script> tag is a basic script tag, but we've added runat="server" to it so that it will be processed on the server. We then define our getAnswer procedure. Notice that this procedure takes two parameters: sender and e. This is the required signature for Microsoft .NET event handlers.

Next, we create an instance of our proxy client class. How do we know that the class is called EightBallWS? By using Notepad to examine the Visual Basic source file that we created using WSDL, you will see the following code:

   Public Class EightBallWS

Each proxy class will have a name associated with it, and that is the class name that we use when we create a new instance of that class. We called our instance of the EightBallWS class clsEightBall. This name was chosen arbitrarily.

Next, we create a string value (strAnswer) to hold the answer returned by the Web service. Remember that we examined the Web service earlier and determined that there was an operation called Ask that accepted a string as a parameter and returned a string.

We assign a value to strAnswer by calling the Ask operation of the Web service and passing our question to it.

   strAnswer = clsEightBall.Ask(tbQuestion.Text)   

We pass the question to it by passing the Text property of the TextBox Web form control (tbQuestion) that we created earlier. We already know that the Ask operation of the Web service returns the answer to us as a string. Therefore, after we've executed the line above, strAnswer will contain a string consisting of the answer to our question returned from the Web service.

All that's left to do now is display the answer that we've retrieved. We do that by assigning the Text property of the Label control to the value contained in strAnswer.

   lblAnswer.Text = strAnswer

You should save this page now. Make sure that the page is saved as 8ball.aspx.

Copy the Proxy Class

The last step before testing our new ASP.NET page is to copy the proxy class that we compiled to the correct location inside our ASP.NET application.

  1. Create a new folder in your FrontPage site and name the folder bin.
  2. Import the 8BallClient.dll file you compiled earlier into that folder.

Test the ASP.NET Application

Now we are ready to test our ASP.NET application. Browse to the 8ball.aspx page. You should see a text box and a button. Enter a question in the text box and click the button. You should see a response from the Web service displayed under the text box.

Aa140118.odc_fpwsvc02(en-us,office.10).gif

Figure 2: The EightBall Web service in action

Conclusion

In this article, we created a very simple ASP.NET Web form to consume a simple Web service with Microsoft FrontPage. We've demonstrated the benefits of the XML Web service architecture and described how we can find out specific information about a Web service by reviewing the Web service access point.

Consuming a simple Web service (such as the EightBall Web service) is extremely easy. If you would like to consume a complex Web service, you may want to consider using Microsoft Visual Studio .NET because it provides a robust tool set for consuming Web services and designing ASP.NET Web forms in a what-you-see-is-what-you-get (WYSIWYG) environment.