ASP.NET AJAX Programmer’s Reference - Chapter 13 potx

Argument Names, Types, and Order The section of the WSDL document shown in the following excerpt from Listing 13-2 uses an XML schema element with the name attribute value of GetEmpl

Consuming Web Ser vices

V ia Soap Messages The previous chapter discussed the ASP.NET AJAX client-server communication layer and its constituent components You learned how to use WebRequest , WebRequestManager , and

WebRequestExecutor to make asynchronous requests to the server right from within your side code This chapter builds on what you learned in the previous chapter to show you how to consume Web services in your ASP.NET AJAX applications The chapter begins by implementing

client-an ASP.NET Web service It then shows you how to use the techniques that you learned in the previous chapter to consume this Web service in an ASP.NET AJAX application

Building the Web Ser vice

In the previous chapter, a Web page was implemented that uses the WebRequest ,

WebRequestExecutor , and WebRequestManager ASP.NET AJAX client classes to make an chronous page post back to the server to retrieve detailed information about a given employee

asyn-In Listing 12-58 , the Page_Load method is the server-side method responsible for validating an employee’s credentials and returning the detailed employee information back to the requesting browser

This section implements a Web service that does exactly what the Page_Load method does — it validates user credentials and returns the detailed employee information to the requesting browser In other words, instead of asynchronously posting back to itself to validate user creden-tials and retrieve the employee information, the page makes an asynchronous call into this Web service Although the end result is the same — both approaches validate user credentials and retrieve the employee information — the mechanisms are quite different Whereas one uses page post back, the other calls into a Web service

Listing 13-1 presents the implementation of this Web service called EmployeeInfo It exposes a single Web-callable method named GetEmployeeInfo that takes the username and password as its argument, validates user credentials, and returns the employee information As you can see, the

GetEmployeeInfo method does exactly what the Page_Load method did in the previous chapter

Listing 13-1: The EmployeeInfo Web Service

if (password == “password” && username == “username”)

return “Shahram|Khosravi|22223333|Some Department|”;

return “Validation failed”;

}

}

If you run EmployeeInfo in Visual Studio, you should see the page shown in Figure 13-1

If you click the Service Description link shown in Figure 13-1 , it takes you to a page that is known as

the Web Service Description Language (WSDL; pronounced whiz-dull ) document The next section

describes this document

If you click the GetEmployeeInfo link shown in Figure 13-1 , it takes you to a page that displays HTTP

request and response messages, known as SOAP messages These messages are described in subsequent

sections

WSDL Documents

The WSDL document of an XML Web service provides you with the following information about the

method of the XML Web service that you want to invoke:

Figure 13-1

❑ The names, types, and order of the arguments of the method

❑ The types and order of the return values of the method

❑ The name of the method

❑ The communication protocol through which the method must be accessed

❑ The URL of the site from which the method must be accessed

❑ The name of the class to which the method belongs The WSDL document uses the XML constructs of the WSDL markup language to provide all this infor-mation about a given method of the XML Web service Listing 13-2 shows the WSDL document that describes the EmployeeInfo XML Web service The following sections discuss different parts of this WSDL document in detail

Listing 13-2: The WSDL Document that Describes the EmployeeInfo XML Web Service

A WSDL document, like all XML documents, has a single outermost element called the document

ele-ment The document element of a WSDL document is named <definitions> This element contains the

following child elements: <types> , <message> , <portType> , <binding> , and <service> These child

elements are discussed in the following sections

Complete coverage of the WSDL markup language and WSDL documents is beyond the scope of this

book This chapter covers only the aspects of WSDL markup language and WSDL documents that relate

specifically to the chapter topic

Argument Names, Types, and Order

The <types> section of the WSDL document shown in the following excerpt from Listing 13-2 uses an

XML schema <element> element with the name attribute value of GetEmployeeInfo to describe the

names, types, and order of the arguments of the XML Web service’s GetEmployeeInfo method:

This <element> element contains a <sequence> element, which in turn contains two <element>

elements The <sequence> element is used to specify the order of the arguments of the method, and the two <element> elements are used to specify the names and types of the arguments The order of the two

<element> elements within the <sequence> element determines the order of the method’s arguments The name and type attributes of each <element> element determine the name and type of the respective argument of the method

Return Value Types and Order

The <types> section of the WSDL document shown in the following excerpt from Listing 13-2 uses an

<element> element with the name attribute value of GetEmployeeInfoResponse to describe the names, types, and order of the return values of the XML Web service’s GetEmployeeInfo method:

This <element> element contains a <sequence> element, which in turn contains an <element>

element The <sequence> element specifies the order of the return values of the method Because the

GetEmployeeInfo method returns a single value, the order is not an issue The type attribute of the <element> element specifies the GetEmployeeInfo method’s return value type

Describing the Method

In a non-distributed environment, invoking the GetEmployeeInfo method is considered a single action, where the caller passes two string values as the arguments of the method and receives a string value as the return value However, in a distributed environment, invoking the GetEmployeeInfo method is sim-ulated through the exchange of two messages: a request message and a response message The request message contains the two input string values, and the response message is the return string value

The WSDL document shown in Listing 13-2 uses a <message> element with the name attribute value of

GetEmployeeInfoSoapIn to represent the request message, and a <part> element to represent the content of the message As previously discussed, the content of the request message is just the two input string values, and the WSDL document’s <types> section uses an <element> element with the name attribute value of GetEmployeeInfo to describe the names, types, and order of the GetEmployeeInfo

method’s arguments.Therefore, the <part> element simply references this <element> element of the

<types> section This reference is assigned to the element attribute of the <part> element as follows:

<message name=”GetEmployeeInfoSoapIn”>

<part name=”parameters” element=”tns:GetEmployeeInfo” />

</message>

The WSDL document uses a <message> element with the name attribute value of GetEmployeeInfoSoapOut

to represent the response message, and a <part> element to represent the content of the message As

previ-ously discussed, the response message is the return value of the GetEmployeeInfo method, and the <types>

section uses an <element> element with the name attribute value of GetEmployeeInfoResponse to describe

the GetEmployeeInfo method’s return value type Therefore, the <part> element simply references this

<element> element of the <types> section, as follows:

<message name=”GetEmployeeInfoSoapOut”>

<part name=”parameters” element=”tns:GetEmployeeInfoResponse” />

</message>

These two <message> elements define the two messages that simulate the GetEmployeeInfo method

The WSDL document shown in Listing 13-2 uses an <operation> element with the name attribute

value of GetEmployeeInfo to represent the GetEmployeeInfo method itself, and the <input> and

<output> elements to represent the contents of the GetEmployeeInfo method Because the content of

the GetEmployeeInfo method is just the request and response messages that simulate the method, the

<input> and <output> elements simply refer to the respective request and response messages as

Notice that the <operation> element is the child element of the <portType> element The <portType>

element is used to group different methods of the XML Web service when the XML Web service exposes

numerous methods This doesn’t apply to this example because the XML Web service exposes a single method

Describing the Communication Protocol for

Accessing the Method

The WSDL document uses the <binding> element to describe the communication protocol and message

format that clients must use to access the GetEmployeeInfo method, as shown in the following excerpt

The WSDL document uses the <soap12:binding> element to specify that its clients must use SOAP 1.2 messages to access the methods of the respective portType The transport attribute of the <soap12:binding> element specifies that SOAP messages must be exchanged via HTTP protocol The style attribute of the <soap12:binding> element specifies that SOAP messages must use document style instead of RPC style

The <soap12:binding> element specifies the settings that apply to all methods of the respective

portType However, there are some settings that are method-specific For example, XML Web services assign a unique string id to each method for identification purposes The SOAPAction header of the respective HTTP message is normally set to the unique string id of the respective method

The WSDL document uses an <operation> element to represent a method The operation element that represents the GetEmployeeInfo method is reused in the <binding> element to set the appropriate parameters of the method

The <soap12:operation> element is used to set the parameters of a given method of the XML Web service The soapAction attribute of the <soap12:operation> element is set to the unique string id that uniquely identifies the method among other methods of the XML Web service The style attribute overrides the style setting of the <soap12:binding> element

The <soap12:operation> element specifies the settings that apply to the entire method However, the

GetEmployeeInfo method consists of two messages The <soap12:body> element allows you to set the parameters that apply to individual messages The WSDL document uses a <part> element to spec-ify the content of a message The use attribute of the <soap12:body> element is set to “literal” to signal that the content of the message is literally the content of the <part> element, and there is no need for further encoding

Specifying the Site for Method Access

The WSDL document uses the <port> element to specify the URL of the site where clients access the method, as shown in the following excerpt from Listing 13-2 :

<port name=”EmployeeInfoSoap12” binding=”tns:EmployeeInfoSoap12”>

<soap12:address location=”http://localhost/WebServicesViaSoap/EmployeeInfo.asmx” />

</port>

The binding attribute of the <port> element refers to the <binding> element that describes the

communication protocol clients must use to access the method Because the <binding> element defines

the communication protocol for a portType (a group of methods), the <port> element specifies the URL

of the site from which all the methods of a given portType can be accessed It would not make much

sense to force users to access different methods of the same group from different sites The location

attribute of the <soap12:address> element determines the URL of the site where the clients can access

the method The same <port> element may contain more than one <soap12:address> element This

means that the same method may be accessed from different sites

Specifying the Method Class

The WSDL document uses the name attribute of the <service> element to specify the name of the class

(from the client perspective to be exact) that the method belongs to, as shown in the following excerpt

XML Web services and their clients exchange data through messages known as SOAP messages A SOAP

message is an XML document that uses the SOAP XML markup language to describe the data being

exchanged A SOAP message, like any other XML document, has a single element known as the

docu-ment eledocu-ment The docudocu-ment eledocu-ment in a SOAP message is an XML eledocu-ment named <Envelope> This

document element contains an optional child element named <Header> and a mandatory child element

named <Body> The <Envelope> , <Header> , and <Body> elements belong to the http://schemas

.xmlsoap.org/soap/envelope/ namespace

If you click the GetEmployeeInfo link previously shown in Figure 13-1 , it takes you to a page that

contains Listings 13-3 and 13-4 Listing 13-3 shows the HTTP request message, which is the HTTP

message that the client of the EmployeeInfo Web service must send to the Web service to invoke its

GetEmployeeInfo method Listing 13-4 shows the HTTP response message, which is the HTTP message

that the Web service sends to clients in response to the HTTP request message

Listing 13-3: The HTTP Request Message

<soap12:Body>

<GetEmployeeInfo xmlns=”http://www.employees/”>

<username>

String </username>

<password>

String </password>

The answer to all these questions is the WSDL document The page parses the WSDL document to find out what communication protocol must be used and what the format of the request and response message should be Here’s how it works The transport attribute of the <binding> element’s <soap12:binding> child element tells you that the client and Web service must use SOAP over HTTP to communi-cate with one another, as shown in the boldface portion of the following excerpt from Listing 13-2 :

<binding name=”EmployeeInfoSoap12” type=”tns:EmployeeInfoSoap”>

Next, let’s discuss the HTTP request message shown in Listing 13-3 This HTTP request message, like

any other HTTP message, has two main parts: header and body The header of the message consists of

the following four lines:

❑ The first line specifies the virtual path of the Web service on the server:

POST /WebServicesViaSoap/EmployeeInfo.asmx HTTP/1.1

This virtual path information comes from the WSDL document First, you search the WSDL

doc-ument for the <service> element with the same name attribute value as the Web service itself,

which is EmployeeInfo , as shown in the following excerpt from Listing 13-2 :

The location attribute of the <soap12:address> child element specifies the virtual path of

the Web service on the server as you can see in the boldface portion of the code excerpt

❑ The second line specifies the hostname or host IP address of the server where the Web service is

located:

Host: localhost

This hostname information comes from the WSDL document First, you search the WSDL document

for the <service> element with the same name attribute value as the Web service itself, which is

The location attribute of the <soap12:address> child element specifies the server hostname

as you can see in the lower boldface portion of the code excerpt

❑ The third line specifies the content type of the HTTP message body Because the body of this

message contains a SOAP message, the content type is set to application/soap+xml :

Content-Type: application/soap+xml; charset=utf-8

❑ The fourth line specifies the length (in bytes) of the message body:

Content-Length: length

The body of the HTTP request message shown in Listing 13-3 contains a SOAP message This SOAP message is an XML document with the <Envelope> document element that contains a <Body> childelement Note that the <Body> child element contains the following XML fragment:

password The string within the opening and closing tags of the <username> and <password> elements specify the values being passed into the GetEmployeeInfo method

Listing 13-4 contains the HTTP response message that the EmployeeInfo Web service sends back to the client in response to the HTTP request message shown in Listing 13-3 The HTTP response message has two parts: header and body The header consists of the following three lines:

❑ The first line consists of three parts:

❑ The first part specifies the version of the HTTP protocol that the server supports, which is version 1.1 in this case

❑ The second part specifies the HTTP response status code, which is 200 in this case A status code value of 200 signals that no error occurred on the server side

❑ The third part specifies the HTTP response status text, which is OK in this case

❑ The second line specifies the content type of the response message body Because the body of the response message is a SOAP message, the content type is set to application/soap+xml :

Content-Type: application/soap+xml; charset=utf-8

❑ The third line specifies the length (in bytes) of the response message body

The body of the HTTP response message shown in Listing 13-4 contains a SOAP message Note that the

<Body> of this SOAP message contains the following XML fragment:

All the information about the method, its parameters, and return value also comes from the WSDL

document First, you search the WSDL document shown in Listing 13-2 for the <service> element with

the same name attribute value as the Web service itself, which is EmployeeInfo :

Then, you search the WSDL document for the <binding> element whose name is given by the binding

attribute value of the <port> child element:

<binding name=”EmployeeInfoSoap12”

type=”tns:EmployeeInfoSoap”>

</binding>

Next, you retrieve type attribute value of the <binding> element and the name attribute value of its

child <operation> element:

Now that you know the name of the method, you need to get information about this method’s

parame-ters For that, you first search the WSDL document for the <portType> whose name attribute value is

given by the type attribute value of the <binding> element, and then you search for the <operation>