The Web Services Description Language

The Web Services Description
Language
W
eb services are formally and fully described using an XML-based document called the
Web Services Description Language (WSDL) document. The WSDL document communicates
metadata information about the Web service to potential clients and shows them what opera-
tions (methods) the Web service supports and how to bind to them.
Visual Studio .NET automatically generates WSDL documents for your XML Web services
and uses them behind the scenes, although it conveniently allows you to avoid opening the
actual WSDL documents. WSDL documents are, for example, used by Visual Studio .NET when
you select the Add Web Reference menu option to allow your project to use the methods of an
outside Web service.
In this chapter, we will describe the elements of a WSDL document so that you can under-
stand how it fully describes a Web service. We will also show you those aspects of the WSDL
document that you may wish to edit manually.
Elements of the WSDL Document
In an SOA, the WSDL document is a critically important document, and one that you will need
to understand in detail so that you can exert tighter control over the Web services that you
develop. This is because development tools such as Visual Studio .NET create the most generic
WSDL documents with bindings only for the SOAP protocol.
Web services can exchange messages over several different protocols in addition to SOAP,
including HTTP POST, HTTP GET, and SMTP. However, keep in mind that SOAP is the most
suitable protocol for exchanging complex XML-based messages. If you have built a true
service-oriented Web service, then these messages cannot, for example, be represented using
simple URL arguments as are used by the HTTP GET protocol. You can use the HTTP POST
protocol to exchange XML messages, but XML is not qualified with namespaces, nor does it
provide the organized SOAP structure that is so critical to technologies such as WSE 2.0. You
can see a comparison between the messages exchanged over SOAP vs. HTTP POST by brows-
ing a Web service directly. Visual Studio .NET generates a generic input page for each Web
method that shows you how the exchanged input and output messages will be generated.
WSDL documents fully describe a Web service, including the operations that it supports,

the messages that it exchanges, and the data types that these messages use (both intrinsic and
custom). The best way to approach a WSDL document is to understand that different XML
15
CHAPTER 2
701xCH02.qxd 7/14/06 4:55 PM Page 15
elements take responsibility for describing different levels of detail. For example, the
<message> element is a detailed listing of the types that factor into a given message. On
the other hand, the <operation> element simply lists the messages that factor into a given
operation without going into any detail as to what these messages look like. This additional
information would be unnecessary because the <message> element already does an excellent
job of documenting the types that factor into a given message. This division of responsibility
makes the WSDL document very efficient but at the same time hard to read, because you have
to look in several places to assemble the full details of the documented Web service. But if you
keep in mind that this is the approach that the WSDL document is following, you will find the
document much easier to understand.
■
Note
All chapter code samples installed on a Windows 2003 server will try to install their web sites
under IIS (Internet Information Services) if IIS is installed and configured. If IIS 6 is installed, make sure
to configure .NET 2.0 to be the default version for IIS to use. Visual Studio will prompt you to convert the
project to .NET 2.0 if this is not done.
The WSDL document is itself an XML document, so it obeys the rules that you expect for
any well-formed XML document. This begins with schema namespace definitions, which are
included as a root element in the WSDL document that’s using the <definitions> element. A
typical WSDL document includes several schema definitions, but the most important one is
the following:
<definitions xmlns=" />The <definitions> root element encloses the contents of the WSDL document entirely.
All of the elements presented next are child elements of the <definitions> root element.
The WSDL document contains seven primary XML elements (in addition to the
<definitions> root element), all of which belong to the schema listed previously. The seven

XML elements fall into two main groups:
• Abstract description: XML elements that document the Web service interface, including
the methods that it supports, the input parameters, and the return types
• Concrete implementation: XML elements that show the client how to physically bind to
the Web service and to use its supported operations
There are four XML elements for abstract description:
<types>: This element lists all of the data types that are exchanged by the XML messages
as input parameters or return types. The <types> element is equivalent to an embedded
XSD schema definition file.
<message>: This element describes a SOAP message, which may be an input, an output, or
a fault message for a Web service operation. A SOAP message is subdivided into parts that
are represented by <part> child elements and that document the types that are included
in the SOAP message.
CHAPTER 2
■
THE WEB SERVICES DESCRIPTION LANGUAGE16
701xCH02.qxd 7/14/06 4:55 PM Page 16
<operation>: This element is analogous to a method definition; however, it only allows
you to define input, output, and fault messages that are associated with the operation.
You can then consult the individual message details to determine what input parameters
and return types are involved.
<portType>: This element lists all of the operations that a Web service supports. The
<port> element corresponds to a single Web service, while the <portType> element
describes the available operations. The previous three elements (<types>, <message>, and
<operation>) all describe granular, individual pieces of the Web service operations and its
message types. The <portType> element avoids many of these lower-level details and
instead provides a high-level summary of the operations (and associated input, output,
and fault messages) that the Web service provides. The <portType> element provides a
single location for a client to browse the offerings of a particular Web service.
There are three XML elements for concrete implementation:

<binding>: This element links the abstract and concrete elements together within a WSDL
document. The <binding> element is associated with a specific <portType> element, and
it also lists the address of the Web service that is associated with the <portType> element.
Finally, the <binding> element lists the protocol that is used to communicate with the
Web service.
<port>: This element defines the Uniform Resource Identifier (URI) where the Web service
is located, and it also implements a <binding> element.
<service>: This element encloses one or more <port> elements.
Figure 2-1 shows the high-level structure of a WSDL document and how the various XML
elements relate to each other within the document. The following sections examine each of
the seven elements in further detail.
Figure 2-1. WSDL document structure
CHAPTER 2
■
THE WEB SERVICES DESCRIPTION LANGUAGE 17
701xCH02.qxd 7/14/06 4:55 PM Page 17
The <types> Element
The <types> element lists all of the data types that are exchanged by the XML messages as
input parameters or return types. The <types> element is equivalent to an embedded XSD
schema definition file. For design purposes, it is useful to separate your XSD schema defini-
tions into another file. This allows you to reference type information independently of the
WSDL document, which is important because it provides a central reference point for validat-
ing XML documents against a single source. You can then import the XSD schema file into the
WSDL document using a separate <import> root element as follows:
<import namespace=" />location=" />
With this approach the <types> element is no longer needed, so you can just include it as
an empty element as follows:
<types/>
Having shown you this approach, we need to immediately point out that it does not con-
form to the WS-I Basic Profile, which states that the <import> element may only be used to

import another WSDL document, not an external XSD schema file. You will still need to design
and build XSD schema files separately from the WSDL document; however, once this task is
complete, you will need to embed the XSD elements directly within the WSDL document’s
<types> section. The <import> element must not appear within a WSDL document for XSD
schema information. This rule holds true for WSDL documents that are generated by either
WSE 2.0 or by WSE 3.0.
You cannot omit the <types> element, even if it is unused, because this will generate
parsing errors in the WSDL document.
XSD schema definition files are described in detail in Chapter 3. They are essential docu-
ments for describing the data types of XML messages in an SOA. The discussion in Chapter 3
shows you how to build XSD schema files manually and then incorporate them into a WSDL
document. You will also use XSD schema files to autogenerate code-based type definitions.
The <message> Element
The <message> element describes a SOAP message, which may be an input, an output, or a
fault message for a Web service operation. A SOAP message is subdivided into parts that are
represented by <part> child elements and that document the types that are included in the
SOAP message.
For example, consider a Web method called RequestQuote. It accepts a stock ticker sym-
bol and returns a complex XML Quote message, which contains multiple levels of detail,
including the opening and closing prices of the stock, as well as long-term statistics such as
52-week high and low values. A client that expects to use the RequestQuote method does not
care how this Web method is implemented. However, the client does need to know the struc-
ture of the messages for communicating with the Web method (or operation, as it is referred to
in WSDL).
CHAPTER 2
■
THE WEB SERVICES DESCRIPTION LANGUAGE18
701xCH02.qxd 7/14/06 4:55 PM Page 18
The RequestQuote operation uses a request (input) message and a response (output)
message. The input message looks like this:

<message name="RequestQuoteSoapIn">
<part name="Symbol" element="s1:Symbol" />
</message>
The output message looks like this:
<message name="RequestQuoteSoapOut">
<part name="RequestQuoteResult" element="s1:Quote" />
</message>
Both messages use types from a namespace called StockTrader, which is referenced in
the <definitions> element of the WSDL document. The <message> element does not need to
document what these types look like; it simply needs to reference them. Notice that the opera-
tion’s parameters are documented within the <message> root element using <part> child
elements. If the RequestQuote operation required five input parameters, the corresponding
input <message> element would include five corresponding <part> child elements.
The <operation> Element
The <operation> element is analogous to a method definition; however, it only allows you to
define input, output, and fault messages that are associated with the operation. You can then
consult the individual message details to determine what input parameters and return types
are involved.
In the previous section, we described the <message> element using an example operation
called RequestQuote. We presented the input and output messages, but observant readers
will notice that we did not formally associate these messages to the same operation beyond
verbally stating that they were associated. This is what the <operation> element is for. It is
responsible for formally associating messages with a given operation. The <message> element
is a root element; so, in theory, you can define a message within the WSDL document and then
use it across multiple operations. This is perfectly legal within the WSDL document.
Here is what the <operation> element looks like for the RequestQuote operation:
<operation name="RequestQuote">
<input message="tns:RequestQuoteSoapIn" />
<output message="tns:RequestQuoteSoapOut" />
<fault message="tns:ExceptionMessage" />

</operation>
Notice that no additional description is provided for the messages beyond their names.
For more details, you must reference the corresponding <message> elements.
Operations can be defined in one of four modes:
• Request/Response: The client sends a request message to the Web service, and the Web
service returns a response message.
• One Way: The client sends a request message to the Web service but receives no
response message in return.
CHAPTER 2
■
THE WEB SERVICES DESCRIPTION LANGUAGE 19
701xCH02.qxd 7/14/06 4:55 PM Page 19
• Solicit/Response: This is the reverse of Request/Response. The Web service sends a mes-
sage to the client, and then the client sends a response message to the Web service.
• Notification: This is the reverse of One Way. The Web service sends a message to the
client but receives no response message in return.
The WSDL document does not contain special attributes for describing how an operation
is called. Instead, you must infer this information by the arrangement and inclusion (or exclu-
sion) of input and output messages. Although we have used the concept of request and
response messages to describe the interaction between Web service and client, this model
does not really apply in a WSDL document. Instead, we refer to input and output messages.
The difference may be semantic, but in a WSDL document, Web services never make requests
or send input messages to a client. Any message that originates from a Web service is referred
to as an output message, even in Solicit/Response or Notification mode. Accordingly, here is
how you define each of the four modes in WSDL:
• Request/Response: The client sends a request message to the Web service, and the Web
service returns a response message.
<operation name="MyOperation">
<input message="MyInputMessage" />
<output message=" MyOutputMessage" />

</operation>
• One Way: The client sends a request message to the Web service but receives no
response message in return.
<operation name="MyOperation">
<input message="MyInputMessage" />
</operation>
• Solicit/Response: This is the reverse of Request/Response. The Web service sends a mes-
sage to the client, and then the client sends a response message to the Web service. The
<operation> element lists the output and input messages in reverse order.
<operation name="MyOperation">
<output message=" MyOutputMessage" />
<input message="MyInputMessage" />
</operation>
• Notification: This is the reverse of One Way. The Web service sends a message to the
client but receives no response message in return.
<operation name="MyOperation">
<output message=" MyOutputMessage" />
</operation>
CHAPTER 2
■
THE WEB SERVICES DESCRIPTION LANGUAGE20
701xCH02.qxd 7/14/06 4:55 PM Page 20