Self-Description of XML Web Services: The WSDL File

For programmers to develop client applications that use our XML Web service, we need to provide a description of what our service does and what a client has to say to the service to make the service perform its task. For example, a client of our XML Web service would like to know the methods the service exposes, the parameters those methods require, and the protocols they support—information conceptually similar to the type library that a standard COM component would carry. The problem with type libraries, however, is that they are Microsoft COM specific, and we want non-Microsoft systems to be able to become clients of our XML Web service. We also want to be able to write descriptions of non-Microsoft services running on non-Microsoft systems so that our Microsoft-built client applications can use those services. What we need is a universal approach, not restricted to the Microsoft world, of describing a service. (Did you ever think you’d read these words in a Microsoft book? Me neither. Different world today.) And we need this approach to be machine-readable so that intelligent development environments can make use of it (again, like type libraries).

XML Web services need to provide a description of their functionality to interested clients.

The ASP.NET infrastructure can generate just such a description by examining the metadata (see Chapter 2) in the code that implements the service. The description is stored in an XML file that uses a vocabulary called WSDL (Web Service Description Language).^[4] The WSDL file for an XML Web service is sometimes known as its contract because it lists the things that the service is capable of doing and tells you how to ask for them. You obtain the WSDL file from ASP.NET by requesting the .ASMX file with the characters ?WSDL attached to the URL. For example, on my local machine, I obtained the file for my sample XML Web service by requesting the URL http://localhost/simplestwebservicevb/TimeServiceVB.asmx?WSDL. That’s what the Service Description link on the page shown in Figure 4-4 does.

The description of an XML Web service is provided in the form of a WSDL file. The .NET infrastructure can generate this description from your code.

When you wrote COM components in Visual Basic 6 and Visual C++ 6, sometimes you wrote the component first and then wrote a type library to describe it. Other times you started with a type library describing an interface and wrote code that implemented it. WSDL can work in both of these ways as well. You can write the code first, as I’ve done in this sample, in which case ASP.NET will generate a WSDL file for interested clients. Alternatively, I could have written the WSDL file first, or gotten it from a third party, describing what the service should do, and then used the SDK utility program Wsdl.exe to generate a template file that implements the service that the WSDL file describes. (This approach is similar to using the Implements keyword in Visual Basic 6.)

Alternatively, you can write the description first and generate the code from it.

The WSDL file is somewhat complex, so I’ve extracted just one portion, shown in Listing 4-2, to illustrate the sorts of things that it contains. The <s:schema> element holds subelements that describe the function calls that a client can make and the responses it will receive from the server. You can see that there’s an element named GetTime, containing a boolean element named ShowSeconds that must appear exactly once. You can see that the response (return value) is in the form of a string, which is optional. Just as you usually interact with a type library by means of an interpretive viewer instead of picking apart its binary constituents, you will probably not deal with raw WSDL files unless you are writing a programming tool that digests them. Instead, you will use WSDL files through interpretive tools, such as the test page provided by ASP.NET. I’ll describe some of these tools and how they help you write XML Web service clients next.

A sample excerpt of a WSDL file is shown here.

Listing 4-2: An excerpt from a WSDL file.

<s:schema elementFormDefault="qualified"  targetNamespace="http://tempuri.org/"> <s:element name="GetTime"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="ShowSeconds" type="s:boolean" /> </s:sequence> </s:complexType> </s:element> <s:element name="GetTimeResponse"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="GetTimeResult"  type="s:string" /> </s:sequence> </s:complexType> </s:element> <s:element name="string" nillable="true" type="s:string" /> </s:schema> 

In addition to the testing capacity shown previously in Figure 4-5, the same page interprets the WSDL file to show you the protocols it supports and the manner in which you must employ them in order to access the service. The screen shot in Figure 4-7 shows the portion of the page describing how to access our time service through the SOAP protocol.

Various development tools read and interpret WSDL for you.

Figure 4-7: Accessing time service through SOAP.

^[4]You will note that many of the acronyms used in .NET aren’t the TLAs (Three-Letter Acronyms; TLA itself is a TLA) you’re used to seeing in most computing projects. That’s because only 17,576 unique TLAs exist, and Microsoft ran out of them halfway through the project. I foresaw this problem three years ago and offered the solution of folding TLAs into CCTs (Clever Compound TLAs; CCT itself is a CCT). While the XML world seems to have adopted this idea (for example, XSL, XML Stylesheet Language, or SAX, Simple API for XML, a semisaturated CCT), Microsoft seems to have spurned it, opting instead to increase the word length to produce acronyms such as SOAP, WSDL, and UDDI. These nomenclature objects haven’t been named yet, so I hereby declare them to be FLAPs, which stands for Four-Letter Acronym Packages. And, naturally, FLAP itself is a FLAP.