XML Web Service Plumbing

XML Web services are based on a cluster of open standards. Table 5-1 lists the key players.

Table 5-1. XML Web Service Technologies 

Standard	Description
WSDL (Web Services Description Language)	An XML-based format that describes everything a client needs to interact with an XML Web service. This includes the XML Web service's methods, the data types used for all parameters and return value, and the supported methods of communication.
HTTP (Hypertext Transfer Protocol)	The communication protocol used to send XML Web service requests and responses over the Internet.
SOAP (Simple Object Access ­Protocol)	An XML-based format used to encode the information in XML Web service messages. SOAP includes a rich, cross-platform way of representing common data types (such as integers, strings, and arrays).
DISCO (Discovery)	DISCO is Microsoft's first crack at a lightweight way to create a simple list of XML Web service links. This can allow clients to discover the XML Web services offered by a particular organization. DISCO is slated for replacement by another similar standard called WS-Inspection, which was developed jointly with IBM.
UDDI (Universal Description, Discovery, and Integration)	The youngest and least evolved of the standards. UDDI is a business repository of XML Web service links designed to allow one business to find another based on the type of service, the business name, and so on. This specification is sure to go through many iterations before it becomes widely accepted.

So how do all these standards fit together? We'll begin with the process of creating the XML Web service, which can be summarized in three steps:

1. Create a dedicated virtual directory to host the XML Web service on your Web server, using IIS.

2. Code the custom XML Web service class, using the <WebMethod> attribute to mark each method that should be remotely callable. At its simplest, the XML Web service class is a collection of stateless methods. .NET takes care of the communication infrastructure that allows the client to discover and call these methods.

3. Deploy the XML Web service files to the virtual directory.

The second step is for the client to find and use your XML Web service:

1. The client finds the XML Web service, either through a predetermined URL or by using a discovery document or the UDDI registry.

2. The client requests the WSDL document that describes the XML Web service. .NET creates this document quickly and automatically by examining your XML Web service.

3. The client generates a proxy class based on the WSDL document. If the client is written using .NET, this step is performed automatically.

4. The client uses the proxy class much as it would use an XML Web service class if it were instantiated in the local process. Behind the scenes, the proxy sends a SOAP message to the XML Web service and receives a SOAP message result. The proxy class handles the Internet communication and SOAP formatting automatically (as shown in Figure 5-1).

   Figure 5-1. XML Web service interaction

   

This process is similar to .NET Remoting in several respects. First of all, the client communicates using a proxy class. The proxy class mimics the XML Web service and handles all the low-level details. Many programming platforms, including .NET, provide tools that create this proxy automatically.

The key difference is in how the proxy class is created. With .NET Remoting, the proxy object is generated dynamically. As soon as a .NET client instantiates a remote object, the runtime springs into action, creating the proxy based on the information in the assembly that describes the remote class. With XML Web services, the proxy class is created using the information found in the WSDL document. This is similar to the type of information contained in the assembly metadata, but it's stored in a cross-platform, human-readable XML format.

Another difference is the fact that the XML Web service proxy class is created during the development cycle. If the XML Web service changes, the proxy class must be manually regenerated. This process sidesteps the headaches required with .NET Remoting, where the client always needs a reference to the assembly that describes the remote component (or a supported interface). The WSDL document also contains enough information for non-.NET clients to communicate with the XML Web service on their own, without requiring a proprietary tool. We'll look at this issue at the end of the chapter.

The Role of IIS

With XML Web services, you don't worry about creating a server program that listens for requests and creates the required object. Instead, ASP.NET and IIS work together to perform this service for you.

IIS is the software that allows your computer to become a Web server and allows remote clients to download HTML pages (or run ASP.NET pages). IIS is included with Microsoft Windows 2000, Windows XP, and Windows .NET Server, but it isn't necessarily installed by default. To ensure that your computer has IIS installed, try typing the following into your Web browser: http://localhost/localstart.asp.

Here, localhost is the special "loopback" alias that always refers to the current computer. (Alternatively, you can use the specific server name or IP address.) localstart.asp is a traditional ASP file that is stored in the root directory of your computer's Web site home directory. If you receive an error when you attempt this request, you should check to make sure you have IIS installed.

To install IIS, follow these steps:

1. From the Start menu, choose Settings, Control Panel.

2. Select Add Or Remove Programs, and then click Add/Remove Windows Components.

3. Select Internet Information Services in the list, and click Next to install the appropriate files.

You must install IIS on your development computer even if the XML Web service will ultimately be hosted on a different Web server.

For those who aren't familiar with IIS, here are the key fundamentals you need to understand before you can create XML Web services:

• IIS provides access to the Web server through virtual directories.

  If you want to provide access to the C:\MyWeb directory, for example, you might create a virtual directory http://[ComputerName]/MyWeb. In this example, the virtual directory name (MyWeb) is the same as the physical directory name, but this isn't required. If your computer is accessible over the Internet (or an intranet), clients can browse to a Web page in the virtual directory. For example, you can view the HTML page C:\MyWeb\index.html by requesting http://[ComputerName]/MyWeb/index.html.

• Virtual directories don't have the same permissions as normal directories.

  By default, remote clients aren't allowed to browse the virtual directory, run executables, create files, or download restricted file types (such as Microsoft Visual Basic source code files). You can configure some of these settings using IIS Manager and add further restrictions such as authentication requirements.

• IIS handles your computer's Internet exposure.

  However, it doesn't run ASP or ASP.NET pages or XML Web services. Instead, IIS maintains a list of registered file extensions. For example, ASP.NET pages (ASPX files) and XML Web services (.asmx files) are registered to the ASP.NET worker process. If IIS receives a request for one of these file types, it hands the work off to the ASP.NET worker process, which handles the rest of the work.

Creating a Virtual Directory

Before you create an XML Web service project in Visual Studio .NET, you should create a dedicated virtual directory. Otherwise, all your code files will be automatically located in a subdirectory of C:\Inetpub\wwwroot, which is the default home directory for IIS. This can cause a great deal of confusion, particularly when it comes time to move your XML Web service project to another computer.

Luckily, creating your own virtual directory is easy. Follow these steps:

1. Create the physical directory on your hard drive.

2. Start IIS Manager by choosing Settings, Control Panel, Administrative Tools, Internet Services Manager from the taskbar.

3. Start the Virtual Directory Wizard in IIS Manager by right-clicking on the Default Web Site item (under your computer in the tree) and choosing New, Virtual Directory from the shortcut menu.

4. Click Next to get started. Specify the alias, which is the name that your virtual directory will have for Web requests. Click Next to continue.

5. Specify the physical directory that will be exposed as the virtual directory. Click Next to continue.

6. The final wizard window gives you the chance to adjust the virtual directory permissions. The default settings allow clients to run ASP.NET pages and XML Web services but not make any modifications or upload files. This is the recommended configuration.

7. Click Next, and then click Finish to end the wizard. You will see the virtual directory in the IIS Manager tree display (as shown in Figure 5-2). After you have created a virtual directory, you can create a Web project in it using Visual Studio .NET.

   Figure 5-2. IIS Manager

   

The XML Web Service File Format

As mentioned earlier, XML Web services are special files with the extension .asmx. The ASP.NET worker process is registered to handle Web requests for this type of file. When it receives a request, it loads the .asmx file, compiles the appropriate class, executes the relevant Web method, and returns the result. This process is similar to the process used for ASP.NET pages (.aspx files). However, .aspx files contain significant information about the controls used on a Web page. The .asmx file is really just a text document that tells ASP.NET where it can find the relevant XML Web service class. Technically, you can create an .asmx file that contains the code itself, but it's almost always easier (and better in terms of organization) to place the XML Web service class in a separate file or dedicated assembly. This is also the model that Visual Studio .NET enforces.

The following sample .asmx file indicates that the XML Web service class called MyWebService can be found in a separate MyWebService.vb code file. ASP.NET is gracious enough to compile this file automatically when needed (a service that ordinary .NET components don't provide).

 <%@ WebService Language="VB" Codebehind="MyWebService.vb"      %> 

And here's a more typical example that indicates that the XML Web service class is named MyWebService and is already compiled into a DLL assembly called MyAssembly:

 <%@ WebService Language="VB"  %> 

Most developers will program XML Web services with Visual Studio .NET. In this case, the .asmx file is created automatically. (In fact, Visual Studio .NET doesn't even display the contents of .asmx files in the integrated development environment [IDE], but if you use Notepad to examine these files, you'll see content similar to what's shown here.) Visual Studio .NET also compiles all the XML Web service classes in the project into a single DLL assembly. Therefore, when it comes time to deploy the completed project to a production Web server, all you need to do is copy the individual .asmx files and a single DLL assembly. You can safely leave the Visual Basic source code files behind.

Note

Every .asmx file contains a reference to one XML Web service. However, a given virtual directory can contain any number of .asmx files, and a Web server can contain any number of virtual directories. The important fact to remember is that each virtual directory acts like a separate ASP.NET application that runs in a dedicated process space and does not share any memory. This becomes important if you use the ASP.NET platform services. XML Web services in the same virtual directory use a common data cache and state collection, which XML Web services in different directories can't access.