C# ПІДРУЧНИКИ / c# / Hungry Minds - ASP.NET Bible VB.NET & C#

<xsd:element name="forecast">

<xsd:complexType>

<xsd:all>

<xsd:element ref="temperature" />

<xsd:element ref="humidity" />

<xsd:element ref="skies" />

</xsd:all>

<xsd:attribute ref="date" />

</xsd:complexType>

</xsd:element>

<xsd:element name="location">

<xsd:complexType>

<xsd:all>

<xsd:element ref="forecast"

minOccurs="1" maxOccurs="unbounded" />

</xsd:all>

<xsd:attribute ref="city" />

</xsd:complexType>

</xsd:element>

<xsd:element name="weather">

<xsd:complexType>

<xsd:all>

<xsd:element ref="location"

minOccurs="1" maxOccurs="unbounded" />

</xsd:all>

</xsd:complexType>

</xsd:element>

</xsd:schema>

The schema begins by declaring the <xsd:schema> root element.

The next several lines of the schema declare simple type elements and attributes, such as the <skies> element and the <city> attribute. As in regular programming, it is good practice to declare variables before they are referenced. This same practice is followed in defining XML schemas. All elements, whether simple or complex, should have their constituent types declared before they are referenced by other element declarations. Following the simple type declarations are the complex type declarations, indicated by the <complexType> tag. The first of these is the <temperature> element declaration. Recall that any elements that contain attributes or other elements are defined as complex types. Because the <temperature> element has an associated "units" attribute, the declaration uses the <complexType> tag to form the declaration of this element. This same structure is used to declare the <humidity> element as well.

Note that this is the first use of the XSD schema "ref" attribute. This attribute is used to refer to a previously declared element in the schema. In this instance, you're referring to the "units" attribute that was declared earlier in the schema document.

The next part of the schema declares the <forecast> element. This is also a complex type declaration, as indicated by the <complexType> tag. The <all> tag indicates that the child elements can appear in any order within the <forecast> element.

The declaration of the <location> element closely resembles that of the <forecast> element. The major difference is the inclusion of the "minOccurs" and "maxOccurs" attributes in the declaration of the <forecast> element reference. These attributes control how many times a particular element can occur. The declaration states that at least one <forecast> element must appear within a <location> element. The term "unbounded" indicates that there is no upper limit to the number of <forecast> occurrences.

This brings us to the final declaration of the root <weather> element. As you can see, the <weather> element consists of at least one occurrence of a <location> element with no upper limit. This declaration is nearly identical to that of the <location> element preceding it.

By using the basic XML schema building blocks, you can describe the required vocabulary and structure for any arbitrary XML grammar and document derived from that grammar.

Given an XML document and a schema, an XML parser can validate the document against the schema and report any problems that it finds. This mechanism provides a simple method for determining that a particular document conforms to a specified XML grammar.

Previous to XSD, the Document Type Definition (DTD) language was used to describe the valid syntax of XML documents. Unfortunately, the DTD language had several drawbacks, which makes it unsuitable for use with Web services. Those of you who are familiar with and have used DTDs should be aware that they have been retired in favor of using XSD.

Note

In short, XML is at the heart of Web services and, as you will soon see, is used to describe the data for many of the Web service technologies.

Exchanging Messages

Web services communicate in the form of messages. A request message delivers information about an operation to be executed and any data required to carry out that operation. Request messages flow from clients to Web services. A response message delivers information about the results of the operation execution. Response messages flow from Web services to clients.

Communication via messages is an extremely effective method for insulating Web service consumers from the implementation details of the service. Of course, it is necessary to define, in a standard way, the rules for how these messages should be formatted and what they can contain.

Message exchange with SOAP

The Simple Object Access Protocol (SOAP) is an industry-standard message format that enables message-based communication for Web services. SOAP implements a message format based on XML to exchange function requests and responses. Using XML as the basis for SOAP messages makes it possible for these messages to be understandable and transportable by any system that implements basic Internet communications services.

SOAP simply defines a message format. It does not impose a specific transport protocol for exchanging these messages. Thus, it is possible to transport SOAP messages over any one of many different and widely available transport protocols such as HTTP, SMTP, FTP, and so on. Note, however, that the HTTP POST command is the default method for transporting SOAP requests and responses.

Tip SOAP uses the term "binding" when referring to a specific protocol that is used to transport SOAP messages.

A SOAP request is an HTTP POST request. An HTTP POST request (like all HTTP commands) consists of human-readable text that contains one or more headers followed by the command payload. The payload is separated from the headers by a blank line.

A SOAP request over HTTP uses the payload section of the HTTP POST request to contain the encoded SOAP envelope. The following code shows the structure of a simple SOAP message using HTTP POST as the transport mechanism:

POST /TemperatureConverter/TemperatureConverter.asmx HTTP/1.1

Host: jdc7200cte

Content-Type: text/xml; charset=utf-8

Content-Length: {length}

SOAPAction: "http://tempuri.org/ConvertTemperature"

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

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.

org/soap/envelope/">

<soap:Body>

<ConvertTemperature xmlns="http://tempuri.org/">

<Temperat ure>{decimal}</Temperature>

<FromUnits>{string}</FromUnits>

<ToUnits>{string}</ToUnits>

</ConvertTemperature>

</soap:Body>

</soap:Envelope>

As shown in the sample code, SOAP messages must use the text/xml content type. Note that named placeholders have been substituted (enclosed in { and }) where the SOAP message would normally contain the actual content length and specific argument values associated with (in this case) the request.

The example also illustrates the basic structure of a SOAP message. The outermost element in a SOAP payload is the envelope. The envelope encapsulates the various parts of a SOAP message. Within the envelope are elements that define SOAP headers (not present in this example) and the SOAP body, which defines the specific request or response message.

Because SOAP uses XML to encode commands and data, the SOAP message format can pass any kind of data that can be described in XML! This includes classic scalar and array data types as well as complex document types such as invoices, purchase orders, and so forth.

We will discuss SOAP in more detail in Chapter 24, "Understanding SOAP." To learn more about the SOAP protocol and standard, visit http://www.soap.org or http://www.w3.org/soap.

Message exchange with HTTP-GET and HTTP-POST

In addition to SOAP, Web services can also exchange messages using HTTP -GET and HTTP-POST. These verbs are standard messages of the HTTP protocol that enable the exchange of information as name/value pairs.

HTTP-GET passes name/value pairs as UUencoded text appended to the URL of a request. This method of passing parameters is referred to as a query string.

Figure 22-1 shows an example of a URL with a query string.

Figure 22-1: An HTTP -GET request with a query string

In Figure 22-1, the URL is specified as: http://jdc7200cte/Demo/ TemperatureConverter.asmx/ConvertTemperature?Temperature=98.6&Fro mUnits=F&ToUnits=C. Note that the ? character separates the base URL from the list of name/value pairs. Following the ? delimiter, each name/value pair is encoded as follows:

Name=value

Multiple name/value pairs are separated by the & character. In the example from Figure 22-1, the name/value pairs are the following:

§Temperature=98.6

§FromUnits=F

§ToUnits=C

HTTP-POST also passes name/value pairs as UUencoded text, except that the parameters are passed within the actual HTTP request header rather than as a query string appended to the URL. This is shown below:

POST /TemperatureConverter/TemperatureConverter.asmx HTTP/1.1

Host: jdc7200cte

Content-Type: text; charset=utf-8

Content-Length: {length}

Temperature=98.6

FromUnits=F

ToUnits=C

Describing Web Service Capabilities

Given a standard method to encode data (XML) and a standard method to exchange Web service requests and responses via messages (SOAP), we need a standard way to describe the specific message exchanges (or capabilities) that a Web service supports.

Recall that SOAP defines a message format based on XML to enable exchange of method requests and responses. However, SOAP does not define the specific methods and results that a Web service may offer.

Those of you familiar with COM programming know that COM components use interfaces to describe their capabilities to a potential consumer. This is done using a language called Interface Definition Language (IDL). Compiling an IDL file results in the creation of a Type Library (TLB). A Type Library in COM contains all the information necessary to query the specific capabilities of the COM component (in other words, the objects, methods, attributes, events, and so on that it supports).

Similar to the Type Library concept in COM, Web services must have a method to describe to potential consumers the specific capabilities that the service offers. Without this capability, consumers would not be able to determine how to request some functionality of the Web service or what to expect as a response.

A Web service description is an XML document (surprise!) that defines the capabilities that a Web service offers. This document provides essential information in a structured form that enables a consumer to understand how to interact with a Web service. The Web Service Description Language (WSDL) defines a standard, extensible XML grammar that is used to define these Web service descriptions in the form of an XML document.

The WSDL document defines the message formats and message exchange patterns that a Web service can process. In addition to these definitions, the WSDL document contains the address of each Web service entry point, formatted according to the protocol used to access the service (for example, a URL for HTTP or an e-mail address for SMTP).

A WSDL document defines services as a collection of network endpoints, or ports using the elements listed in Table 22-1.

targetNamespace="http://tempuri.org/"> <s:element name="CTemp">

<s:complexType>

<s:sequence>

<s:element minOccurs="1" maxOccurs="1"name="Temperature" type="s:decimal" />

<s:element minOccurs="1" maxOccurs="1"name="FromUnits" nillable="true" type="s:string" />

<s:element minOccurs="1" maxOccurs="1"name="ToUnits" nillable="true"

type="s:string" /> </s:sequence> </s:complexType> </s:element>

<s:element name="CTempResponse"> <s:complexType>

<s:sequence>

<s:element minOccurs="1" maxOccurs="1"name="CTempResult" type="s:decimal" />

</s:sequence>

</s:complexType>

</s:element>

<s:element name="decimal" type="s:decimal" /> </s:schema>

</types>

<message name="CTempSoapIn">

<part name="parameters" element="s0:CTemp" /> </message>

<message name="CTempSoapOut">

<part name="parameters" element="s0:CTempResponse" /> </message>

<portType name="TempConverterSoap"> <operation name="CTemp">

<input message="s0:CTempSoapIn" /> <output message="s0:CTempSoapOut" /> </operation>

</portType>

<binding name="TempConverterSoap" type="s0:TempConverterSoap"> <soap:binding

transport=http://schemas.xmlsoap.org/soap/httpstyle="document" /> <operation name="CTemp">

<soap:operation soapAction=http://tempuri.org/CTemp style="document" />

<input>

<soap:body use="literal" />

</input>

<output>

<soap:body use="literal" />

</output>

</operation>

</binding>

<service name="TempConverter">

<port name="TempConverterSoap" binding="s0:TempConverterSoap">

<soap:address location="http://jdc7200cte/Services/Ctemp/CTemp.asmx"

/>

</port>

</service>

</definitions>

As shown in this example, the CTemp Web service supports a single method named CTemp that accepts the three input arguments shown in Table 22-2.

Table 22-2: CTemp method arguments and data types

In addition, CTemp returns a result of type Decimal. You can also see that the Web service supports the HTTP-GET, HTTP-POST, and SOAP protocols for transporting the request and response messages.

As of the writing of this book, the WSDL specification had been submitted to the World Wide Web Consortium as a Note for review. For its part, the W3C has created a group called the XML Protocol activity whose mission is to define and formalize standards around using XML for distributed applications to communicate on a peer-to-peer basis. This includes the WSDL specification as well as several others.

Note For more information about the WSDL specification, visit www.w3.org/TR/WSDL.html . For more information about the XML Protocol's activity, visit www.w3.org/2000/xp. Finally, you can read more about SOAP messaging by visiting http://www.w3.org/TR/2001/WD-soap12-part1-20011002/.

Publishing and Finding Web Services

Given a standard means to describe the capabilities of a Web service via the WSDL document, we must now consider how a potential consumer of a Web service will locate a WSDL document on a target Web server. Recall that to consume a service, a client must be able to determine how to interact with that Web service, which means that it must follow the message formats and message exchange patterns described for the Web service in the WSDL document.

Of course, if you are both the author and consumer of the Web service, you probably will not need help in locating the WSDL document. However, if you will be consuming Web services from other authors, you may not know where a particular service is located on a target Web server. Web service authors use a discovery (DISCO) document to publish their Web service. The DISCO document is an XML document that contains pointers to such things as the WSDL file for the Web service.

Web service consumers employ a discovery process to learn that a Web service exists and where to find the Web service's WSDL document. Web service consumers enact this discovery process on a target Web server by providing a URL to a discovery tool. The discovery tool attempts to locate DISCO documents on the target server and informs the consumer of the location of any available WSDL documents.

As mentioned earlier, the DISCO document is encoded as an XML document, which provides the ability to programmatically discover information about Web services. This technique has enabled the creation of tools that can be used by a consumer to locate Web services. The Microsoft .NET Framework provides a tool named disco.exe to enable Web service discovery. In addition, Visual Studio .NET has integrated support for Web service discovery using the concept of Web References. We will learn more about the disco tool and its capabilities in upcoming chapters.

The following sample illustrates the structure of a DISCO document:

<?xml version="1.0" ?>

<disco:discovery xmlns:disco="http://schemas.xmlsoap.org/disco"

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

<wsdl:contractRef ref="http://jdc7200cte/

Services/CTemp/CTemp.asmx?WSDL"/>

</disco:discovery>

In this sample, a pointer to the WSDL document is contained in a contractRef element, which contains the URL that points to the WSDL document.

An interesting feature of the DISCO document is that it need not physically reside alongside the Web service description document or other Web service implementation files, because the DISCO document provides information about resources such as the Web service description via pointers. Thus, it is possible to distribute DISCO documents to centralized Web service directories, which can be used to more easily locate Web services.

Note

While this book was being written, the DISCO technology had been submitted to the W3C XML Protocols activity for consideration. You can find out more about DISCO in the Microsoft .NET Framework documentation and at the W3C Web site.

Finding Web Service Providers

As more and more Web services are created and deployed by numerous organizations on the Internet, it will become increasingly more difficult for consumers to find these services. This is analogous to the difficulty Web users might experience in finding a specific page of information amongst the billions of pages of information currently published on the Web were it not for Web search engines.