Consuming Web Services Via 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 client- 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 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 Service In the previous chapter, a Web page was implemented that uses the WebRequest , WebRequestExecutor , and WebRequestManager ASP.NET AJAX client classes to make an asyn- chronous page post back to the server to retrieve detailed information about a given employee. 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. c13.indd 511c13.indd 511 8/20/07 6:11:47 PM8/20/07 6:11:47 PM Chapter 13: Consuming Web Services Via Soap Messages 512 Listing 13-1: The EmployeeInfo Web Service using System; using System.Web; using System.Web.Services; using System.Web.Services.Protocols; [WebService(Namespace = “http://www.employees/”)] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] public class EmployeeInfo : System.Web.Services.WebService { [WebMethod] public string GetEmployeeInfo(string username, string password) { 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 c13.indd 512c13.indd 512 8/20/07 6:11:48 PM8/20/07 6:11:48 PM Chapter 13: Consuming Web Services Via Soap Messages 513 ❑ 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 <?xml version=”1.0” encoding=”utf-8” ?> <wsdl:definitions xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns:tm=”http://microsoft.com/wsdl/mime/textMatching/” xmlns:soapenc=”http://schemas.xmlsoap.org/soap/encoding/” xmlns:mime=”http://schemas.xmlsoap.org/wsdl/mime/” xmlns:tns=”http://www.employees/” xmlns:s=”http://www.w3.org/2001/XMLSchema” xmlns:soap12=”http://schemas.xmlsoap.org/wsdl/soap12/” xmlns:http=”http://schemas.xmlsoap.org/wsdl/http/” targetNamespace=”http://www.employees/” xmlns=”http://schemas.xmlsoap.org/wsdl/”> <types> <s:schema elementFormDefault=”qualified” targetNamespace=”http://www.employees/”> <s:element name=”GetEmployeeInfo”> <s:complexType> <s:sequence> <s:element minOccurs=”0” maxOccurs=”1” name=”username” type=”s:string” /> <s:element minOccurs=”0” maxOccurs=”1” name=”password” type=”s:string” /> </s:sequence> </s:complexType> </s:element> <s:element name=”GetEmployeeInfoResponse”> <s:complexType> <s:sequence> <s:element minOccurs=”0” maxOccurs=”1” name=”GetEmployeeInfoResult” type=”s:string” /> </s:sequence> </s:complexType> </s:element> </s:schema> </types> (continued) c13.indd 513c13.indd 513 8/20/07 6:11:48 PM8/20/07 6:11:48 PM Chapter 13: Consuming Web Services Via Soap Messages 514 Listing 13-2 (continued) <message name=”GetEmployeeInfoSoapIn”> <part name=”parameters” element=”tns:GetEmployeeInfo” /> </message> <message name=”GetEmployeeInfoSoapOut”> <part name=”parameters” element=”tns:GetEmployeeInfoResponse” /> </message> <portType name=”EmployeeInfoSoap”> <operation name=”GetEmployeeInfo”> <input message=”tns:GetEmployeeInfoSoapIn” /> <output message=”tns:GetEmployeeInfoSoapOut” /> </operation> </portType> <binding name=”EmployeeInfoSoap12” type=”tns:EmployeeInfoSoap”> <soap12:binding transport=”http://schemas.xmlsoap.org/soap/http” /> <operation name=”GetEmployeeInfo”> <soap12:operation soapAction=”http://www.employees/GetEmployeeInfo” style=”document” /> <input> <soap12:body use=”literal” /> </input> <output> <soap12:body use=”literal” /> </output> </operation> </binding> <service name=”EmployeeInfo”> <port name=”EmployeeInfoSoap12” binding=”tns:EmployeeInfoSoap12”> <soap12:address location=”http://localhost/WebServicesViaSoap/EmployeeInfo.asmx” /> </port> </service> </definitions> 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: c13.indd 514c13.indd 514 8/20/07 6:11:48 PM8/20/07 6:11:48 PM Chapter 13: Consuming Web Services Via Soap Messages 515 <s:element name=”GetEmployeeInfo”> <s:complexType> <s:sequence> <s:element minOccurs=”0” maxOccurs=”1” name=”username” type=”s:string” /> <s:element minOccurs=”0” maxOccurs=”1” name=”password” type=”s:string” /> </s:sequence> </s:complexType> </s:element> 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: <s:element name=”GetEmployeeInfoResponse”> <s:complexType> <s:sequence> <s:element minOccurs=”0” maxOccurs=”1” name=”GetEmployeeInfoResult” type=”s:string” /> </s:sequence> </s:complexType> </s:element> 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 c13.indd 515c13.indd 515 8/20/07 6:11:49 PM8/20/07 6:11:49 PM Chapter 13: Consuming Web Services Via Soap Messages 516 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 follows: <portType name=”EmployeeInfoSoap”> <operation name=”GetEmployeeInfo”> <input message=”tns:GetEmployeeInfoSoapIn” /> <output message=”tns:GetEmployeeInfoSoapOut” /> </operation> </portType> 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 from Listing 13-2 : <binding name=”EmployeeInfoSoap12” type=”tns:EmployeeInfoSoap”> <soap12:binding transport=”http://schemas.xmlsoap.org/soap/http” /> <operation name=”GetEmployeeInfo”> <soap12:operation soapAction=”http://www.employees/GetEmployeeInfo” style=”document” /> <input> <soap12:body use=”literal” /> </input> c13.indd 516c13.indd 516 8/20/07 6:11:49 PM8/20/07 6:11:49 PM Chapter 13: Consuming Web Services Via Soap Messages 517 <output> <soap12:body use=”literal” /> </output> </operation> </binding> The WSDL document uses the <portType> element to group the related methods of the XML Web ser- vice. Grouping is very useful when it comes to defining the communication protocol. It wouldn’t make sense to force the clients of the XML Web service to use different communication protocols to access different methods of the same group. That’s why the WSDL document defines a single communication protocol to access all methods in the same portType . The type attribute of the <binding> element refers to the <portType> element for which the communication protocol is defined. 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> c13.indd 517c13.indd 517 8/20/07 6:11:49 PM8/20/07 6:11:49 PM Chapter 13: Consuming Web Services Via Soap Messages 518 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 from Listing 13-2 : <service name=”EmployeeInfo”> <port name=”EmployeeInfoSoap12” binding=”tns:EmployeeInfoSoap12”> <soap12:address location=”http://localhost/WebServicesViaSoap/EmployeeInfo.asmx” /> </port> </service> SOAP Messages 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 element. The document element in a SOAP message is an XML element 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 POST /WebServicesViaSoap/EmployeeInfo.asmx HTTP/1.1 Host: localhost Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version=”1.0” encoding=”utf-8”?> <soap12:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:soap12=”http://www.w3.org/2003/05/soap-envelope”> c13.indd 518c13.indd 518 8/20/07 6:11:50 PM8/20/07 6:11:50 PM Chapter 13: Consuming Web Services Via Soap Messages 519 <soap12:Body> <GetEmployeeInfo xmlns=”http://www.employees/”> <username> String </username> <password> String </password> </GetEmployeeInfo> </soap12:Body> </soap12:Envelope> Listing 13-4: The HTTP Response Message HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version=”1.0” encoding=”utf-8”?> <soap12:Envelope xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:soap12=”http://www.w3.org/2003/05/soap-envelope”> <soap12:Body> <GetEmployeeInfoResponse xmlns=”http://www.employees/”> <GetEmployeeInfoResult>string</GetEmployeeInfoResult> </GetEmployeeInfoResponse> </soap12:Body> </soap12:Envelope> Here is a question for you: What is the relationship between the WSDL document shown previously in Listing 13-2 and the HTTP request and response messages shown in Listings 13-3 and 13-4 ? Here is another related question: Does this mean that every time you want to know what type of HTTP request message a Web service expects to receive from its clients and what type of HTTP response mes- sage the clients of a Web service should expect to receive from the Web service, you have to run the Web service in Visual Studio as you did for the EmployeeInfo Web service to access a page similar to the page shown in Figure 13-1 , and from there go to the page that contains the HTTP request and response messages? When you click the GetEmployeeInfo link shown in Figure 13-1 to go to the page that displays the formats of the HTTP request and response messages, how does this page figure out what these formats are? And how did this page know that the client and Web service must use the HTTP protocol to communicate with one another? 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”> <soap12:binding transport=”http://schemas.xmlsoap.org/soap/http” /> <operation name=”GetEmployeeInfo”> <soap12:operation soapAction=”http://www.employees/GetEmployeeInfo” style=”document” /> (continued) c13.indd 519c13.indd 519 8/20/07 6:11:50 PM8/20/07 6:11:50 PM Chapter 13: Consuming Web Services Via Soap Messages 520 (continued) <input> <soap12:body use=”literal” /> </input> <output> <soap12:body use=”literal” /> </output> </operation> </binding> 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 : <service name=”EmployeeInfo”> <port name=”EmployeeInfoSoap12” binding=”tns:EmployeeInfoSoap12”> <soap12:address location=”http://localhost/WebServicesViaSoap/EmployeeInfo.asmx” /> </port> </service> 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 EmployeeInfo , as shown in the following excerpt from Listing 13-2 : <service name=”EmployeeInfo”> <port name=”EmployeeInfoSoap12” binding=”tns:EmployeeInfoSoap12”> <soap12:address location=”http://localhost/WebServicesViaSoap/EmployeeInfo.asmx” /> </port> </service> 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 : c13.indd 520c13.indd 520 8/20/07 6:11:50 PM8/20/07 6:11:50 PM [...]... steps and use Listings 1 3-3 and 1 3-4 to implement the third step In this step, WebRequest, WebRequestExecutor, and WebRequestManager are used to send a SOAP request message over HTTP to the server and receive a SOAP response message over HTTP from the server, as shown in Listing 1 3-5 524 c13.indd 524 8/20/07 6:11:51 PM Chapter 13: Consuming Web Services Via Soap Messages Listing 1 3-5 : A Page that Exchanges... Listing 1 3-4 ): var reply2 = sender.get_xml(); 532 c13.indd 532 8/20/07 6:11:54 PM Chapter 13: Consuming Web Services Via Soap Messages As the following excerpt from Listing 1 3-4 shows, the return value of the GetEmployeeInfo method is encapsulated in an element named : Your Information First Name Last Name... 528 c13.indd 528 8/20/07 6:11:52 PM Chapter 13: Consuming Web Services Via Soap Messages As you can see in the following excerpt from Listing 1 3-3 , the body of the request begins with the xml declaration: As such, this xml declaration is the first line that submitCallback adds to the StringBuilder: requestBodyBuilder.append(‘’);.. .Chapter 13: Consuming Web Services Via Soap Messages 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 1 3-3 contains a SOAP message This SOAP message is an XML document with the ... request.get_headers()[‘Content-Type’] = ‘application/soap+xml; charset=utf-8’; The fourth header line of the HTTP request message in Listing 1 3-3 specifies the value of the Content-Length header This header specifies the length (in bytes) of the body of the message 531 c13.indd 531 8/20/07 6:11:53 PM Chapter 13: Consuming Web Services Via Soap Messages The submitCallback method first calls the get_headers method again on the... (continued) 527 c13.indd 527 8/20/07 6:11:52 PM Chapter 13: Consuming Web Services Via Soap Messages Listing 1 3-5 (continued) Username: . </s:schema> </types> (continued) c13.indd 513c13.indd 513 8/20/07 6:11:48 PM8/20/07 6:11:48 PM Chapter 13: Consuming Web Services Via Soap Messages 514 Listing 1 3-2 (continued) <message name=”GetEmployeeInfoSoapIn”> . click the GetEmployeeInfo link previously shown in Figure 1 3-1 , it takes you to a page that contains Listings 1 3-3 and 1 3-4 . Listing 1 3-3 shows the HTTP request message, which is the HTTP . server, as shown in Listing 1 3-5 . c13.indd 524c13.indd 524 8/20/07 6:11:51 PM8/20/07 6:11:51 PM Chapter 13: Consuming Web Services Via Soap Messages 525 Listing 1 3-5 : A Page that Exchanges SOAP