The Web Services Description Language

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 cust

The Web Services Description

Language

Web 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

C H A P T E R 2

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="http://schemas.xmlsoap.org/wsdl/">

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

<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

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 svalidat-ingle source You can then import the XSD schema file into the WSDL document using a separate <import> root element as follows:

<import namespace="http://www.bluestonepartners.com/schemas/StockTrader/"

location="http://www.bluestonepartners.com/schemas/StockTrader.xsd" />

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)

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

• 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 mesmes-sage 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 mesmes-sage 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>

The <portType> Element

The <portType> element lists all of the operations that a Web service supports The <port>

element (described later in this chapter) 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

oper-ations 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

The four elements that we have discussed so far are presented in order of decreasing granularity Whereas an <operation> element lists a collection of <message> elements (which

in turn list a collection of <types> elements), a <portType> element lists a collection of

<operation> elements

For example, here is the <portType> element (named StockTraderServiceSoap) for a Web service that supports two operations, RequestQuote and PlaceTrade:

<portType name="StockTraderServiceSoap">

<operation name="RequestQuote">

<input message="tns:RequestQuoteSoapIn" />

<output message="tns:RequestQuoteSoapOut" />

<fault message=" tns:ExceptionMessage" />

</operation>

<operation name="PlaceTrade">

<input message="tns:PlaceTradeSoapIn" />

<output message="tns:PlaceTradeSoapOut" />

</operation>

</portType>

You may be surprised to see the <portType> listing like this We have pointed out on sev-eral occasions how the WSDL document is designed for efficiency If this were entirely the

case, then you would expect the <portType> element to look more like this:

<portType name="StockTraderServiceSoap">>

<operation name="RequestQuote" />

<operation name="PlaceTrade" />

</portType>

There is no easy explanation as to why the WSDL document takes a less efficient approach with the <portType> element other than to speculate that it is designed to be a

one-stop location for a client to retrieve a summary of the operations that the Web service

supports

The <binding> Element

The <binding> element links the abstract and concrete elements together within a WSDL

doc-ument 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

Keep in mind that the <portType> element is nothing more than an abstract definition for

a Web service, which is a concrete entity that implements a set of operations The <binding> element simply formalizes the association between a <portType> and a Web service

Here is what the <binding> element looks like for a Web service that supports a single operation called RequestQuote, and which communicates using the SOAP protocol:

<binding name="StockTraderServiceSoap" type="tns:StockTraderServiceSoap">

<soap:binding transport="http://schemas.xmlsoap.org/soap/http"

style="document" />

<operation name="RequestQuote">

<soap:operation soapAction="http://www.bluestonepartners.com/schemas/StockTrader/RequestQuote" style="document" />

<input>

<soap:body use="literal" />

</input>

<output>

<soap:body use="literal" />

</output>

</operation>

</binding>

There is no new abstract information here that you do not already know from the discussion so far For example, you already know the name of the <portType>, which is StockTraderServiceSoap And you already know that it includes an <operation> element named RequestQuote But the concrete information is new The <binding> element informs you that the Web service uses the SOAP transport protocol The <soap:operation> element tells you the name of the Web method that is associated with the RequestQuote operation, but

it does not reveal the physical location of the Web service (The soapAction attribute includes the namespace for the RequestQuote schema element, which appears to resemble a physical URL path.) Finally, you learned that the Web method uses literal encoding and a document style, which are both required settings for exchanging SOAP messages

The <port> Element

The <port> element defines the URL where the Web service is located, and it also implements

a <binding> element As you know, we have already defined the <binding> element for the Web service, but it does not indicate the physical location of the Web service This is what the

<port> element is for

Here is what the <port> element looks like for the StockTraderServiceSoap <binding> element:

<port name="StockTraderServiceSoap" binding="tns:StockTraderServiceSoap">

<soap:address location="http://localhost/StockTrader/StockTrader.asmx" />

</port>

Finally, you learn the physical location of the Web service, via the <soap:address>

element

The <service> Element

The <service> element encloses one or more <port> elements It is essentially a collection of

one or more Web service bindings In most cases, your WSDL document will describe one Web

service only, so the <service> element itself will provide no additional value However, the

WSDL specification requires that all <port> elements be contained within the <service>

ele-ment The listing in the previous section actually appears within a <service> element called

StockTraderService as follows:

<service name="StockTraderService">

<port name="StockTraderServiceSoap" binding="tns:StockTraderServiceSoap">

<soap:address location="http://localhost/StockTrader/StockTrader.asmx" />

</port>

</service>

The WSDL 1.1 Specification

The WSDL 1.1 specification that describes the complete document structure can be found at

http://www.w3.org/TR/wsdl It is worth looking at the original specification because you will

find useful elements that you can use even though they are not widely known or even

gener-ated using GUI tools such as Visual Studio NET For example, the <operation> element

contains a child element called <documentation> that allows you to insert an English

lan-guage description of what the operation does Here is an example:

<operation name="RequestQuote">

<documentation>

Returns a delayed 30-minute quote for a given stock ticker symbol

This operation returns a Quote XML type as defined in the XSD schema at:

http://www.bluestonepartners.com/schemas/StockTrader.xsd

</documentation>

<input message="s1:RequestQuoteSoapIn" />

<output message="s1:RequestQuoteSoapOut" />

</operation>

The <documentation> element adds a welcome level of readability to the WSDL docu-ment, which is challenging at best to read with human eyes

If you were to distill a WSDL document down to its most basic set of associated elements,

it would look like this:

<definitions>

<types />

<message />

<operation>

<message />

</operation>

<portType>

<operation />

</portType>

<operation />

</binding>

<service>

<port>

<binding />

</port>

</service>

</definitions>

Listing 2-1 shows the actual WSDL document for the StockTrader Web service that we will

be working with in detail in the following chapters You do not need to read the document line-by-line; but try scanning it and notice how much information you can get about the Web service without having seen any other documentation about it

Listing 2-1.The WSDL Document for the StockTrader Web Service

<?xml version="1.0" encoding="utf-8" ?>

<definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:s="http://www.w3.org/2001/XMLSchema"

xmlns:s0="http://www.bluestonepartners.com/schemas/StockTrader/"

xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:tns="http://www.bluestonepartners.com/schemas/StockTrader"

xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"

xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

targetNamespace="http://www.bluestonepartners.com/schemas/StockTrader"

xmlns="http://schemas.xmlsoap.org/wsdl/">

<import namespace="http://www.bluestonepartners.com/schemas/StockTrader/"

location="http://www.bluestonepartners.com/schemas/StockTrader.xsd" />

<types/>

<message name="RequestAllTradesSummarySoapIn">

<part name="Account" element="s1:Account" />

</message>

<message name="RequestAllTradesSummarySoapOut">

<part name="RequestAllTradesSummaryResult" element="s1:Trades" />

</message>

<message name="RequestTradeDetailsSoapIn">

<part name="Account" element="s1:Account" />

<part name="TradeID" element="s1:TradeID" />

</message>

<message name="RequestTradeDetailsSoapOut">

<part name="RequestTradeDetailsResult" element="s1:Trade" />

</message>

<message name="PlaceTradeSoapIn">

<part name="Account" element="s1:Account" />

<part name="Symbol" element="s1:Symbol" />

<part name="Shares" element="s1:Shares" />