Building Servers





Building Servers

Let's get up and running by creating a sample XML Web service. Then, we'll take a step back and discuss the infrastructure in more detail, increasing our sample's complexity as we go.

Building an XML Web service with ASP.NET is easy. Here is a simplified list of the tasks required:

  1. Verify that you have IIS and the .NET Framework installed.

  2. Create a virtual directory, which acts as an application for ASP.NET. Let's call it "Test."

  3. Create a file named Test.asmx, and put it in this virtual directory.

  4. Add the WebService directive as the first line of the file:

    <%@ WebService Class="TestClass" Language="C#" %>
    
  5. Reference the System and System.Web.Services namespace.

  6. Create a class called "TestClass".

  7. Add a method to this class called Add, using the following code:

    public int Add( int a, int b)
    
  8. Declare this method to be callable as an XML Web service, using the WebMethod attribute, as follows:

    [WebMethod]
    

Your file should look something like Listing 3.1.

A Simple Web Service
<%@ WebService Class="TestClass" Language="C#" %>

using System;
using System.Web.Services;

public class TestClass {

     [WebMethod]
     public int Add( int a, int b)
     {
          return a+b;
     }
}

Now, using Internet Explorer (or whatever browser you prefer), open the following URL (uniform resource locator): http://localhost/test/test.asmx. (This URL assumes that you are using Internet Explorer on the server where you created the file, and that the virtual directory and file name are the same as the ones in the directions just given.) You should see an HTML page that resembles Figure. This help page is designed for design-time support of a Web service. Using it, you can gain access to the WSDL for the service, as well as examine each of the operations that your service implements. To learn more about WSDL, refer to Chapter 10, Describing Web Services.

1. The Web Services Help Page

graphics/03fig01.gif

With ASP.NET, only one class is exposed as a service, and each method of the class is mapped to a service operation. When you first access this help page, the name of the service (which by default maps to the name of the class exposed) is listed as the title along the top. The operations that the service exposes (each public method marked with the [WebMethod] attribute) are listed below. You can click each of these operations to view more information.

A line of text warns that this service is in the http://tempuri.org namespace. You can change the namespace with the [WebService] attribute, which is explained in greater detail later in this chapter. Chapter 8 (Data and Format: XML and XML Schemas) provides more information about namespaces in a Web service.

To add a description of this service, you can modify the [WebService] attribute to include a sentence description:

[WebService(Description="This is a test XML Web service.", 
            Namespace="http://sampletestservice/")]
public class TestClass

On the help page for the test service, you can click the Add operation. This page contains three items of interest: the form for testing the service, the samples of the wire format, and a description of the operation.

Currently, there is no description for this method, because none has been added. Adding a small description involves changing the [WebMethod] attribute:

[WebMethod(Description="This is a test operation.")] 

Refreshing the page, you see that this description is now included on the help page. This description also will be visible in the listing of services on the front page of the service. I highly recommend doing this for all of your methods, as it provides an easy means for adding some important documentation.

Entering values into the test form and then submitting the form cause the operation to be called with a nonstandard protocol called HTTP-GET—so named because it uses the GET verb in HTTP along with URL-encoded values for the method parameters. The response is XML.

Looking down the page, samples for SOAP, HTTP-GET, and HTTP-POST (another custom protocol similar to HTTP-GET) are listed. These are particularly useful for ensuring that the service is sending and receiving the right style of messages. If you disable a protocol, such as HTTP-GET, then the sample messages won't appear for this protocol. HTTP-GET cannot support operations in which the request message is too complex. For example, if a service uses a parameter that is more complex than a primitive type, then samples for that protocol will not be shown and the test form will not appear. As mentioned earlier, the help page also contains a link to the WSDL description of the service. This link takes you to the help page, with "?WSDL" appended to the end. For the test service just built, this WSDL document will look something like Figure.

2. A WSDL from a Service

graphics/03fig02.gif

Although not linked visibly from this document, you can also get a DISCO document for this service, by appending "?DISCO". Within the HTML of this help page is a link to the following view:

<link rel="/test/test.asmx?DISCO" type="text/xml"> 

This discovery document contains a link to the WSDL file for this service, and it is the document that Visual Studio .NET and the command line tool wsdl.exe use to find the WSDL document. To learn more about DISCO, refer to Chapter 11, Discovering Web Services.


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows