Building XML Web Services for the Microsoft .NET Platform phần 4 ppsx

116 xmlns="http://www.w3.org/2001/ XMLSchema" targetNamespace="http://somedomain/Calculator/schema"> <! Common result element for HTTP GET/POST binding > <element name="Result" type="int"/> </schema> </types> <! Messages for HTTP GET/POST-based Web service > <! Note: Previously defined messages omitted for clarity > <message name="AddHttpMsgIn"> <part name="x" type="xsd:string"/> <part name="y" type="xsd:string"/> </message> <message name="AddHttpMsgOut"> <part name="result" element="s:Result"/> </message> <message name="SubtractHttpMsgIn"> <part name="x" element="xsd:string"/> <part name="y" element="xsd:string"/> </message> <message name="SubtractHttpMsgOut"> <part name="result" element="s:Result"/> </message> <! More definitions will go here. > </definitions> The preceding WSDL document defines a new element of type int called Result that will be used to contain the result of the Add and Subtract methods returned to the client. This element is referenced by two new outbound messages, one for each method. The document also defines new inbound messages for the Add and Subtract methods. The outbound messages define individual parts for each parameter. Since the name/value pairs containing the parameters are not strongly typed, the type of each part is defined as string. HTTP GET/POST extension elements are contained within the http://schemas.xmlsoap.org/wsdl/http/ namespace. The convention I follow throughout the remainder of this chapter is to associate references to the namespace using the http: moniker. In a few scenarios, HTTP GET/POST bindings leverage the MIME extension elements. They are defined within the http://schemas.xmlsoap.org/wsdl/mime/ namespace and referenced using the mime: moniker. binding Element Binding 117 Extensibility elements added to the binding element provide information about how the parameters are encoded within the HTTP message. Extensibility elements are added to the bind, operation, input, output, and fault messages. The http:binding element specifies whether the parameters are passed within the URL or within the body of the HTTP request: The “verb” of the http:binding attribute is set to either GET or POST. The following WSDL document demonstrates the use of the http:binding element within the definition of the Calculator Web service: <?xml version="1.0" encoding="utf-8"?> <definitions targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <! Type, message, and port type definitions removed for clarity > <binding name="CalculatorHttpGetBinding" type="tns:CalculatorPortType"/> <http:binding verb="GET"/> <! Operation elements removed for clarity > </binding> <! More definitions will go here. > </definitions> The http:operation element specifies the relative address for each operation. Each input and output message is decorated with an extension element that indicates the method used to encode the parameters passed to the Web service. The three upcoming scenarios for encoding the parameters show the URL encoding of parameters on the query string, nonstandard encoding within the URL, and URL encoding of the parameters in the body of the post. Parameters can be passed to a Web service via a URL encoded within the query string. URL encoding specifies appending a ? to the end of the URL and then appending a name/value pair separated with an =. If multiple name/value pairs are appended to the URL, they are separated from each other by an &. For example, the Add method can be called as follows: http://somedomain/Calculator/Add?x=2&y=3 In this case, the input element within the binding for a particular operation would be decorated with an http:urlEncoded element. Here is the resulting HTTP GET binding definition for the Calculator Web service: <?xml version="1.0" encoding="utf-8"?> <definitions targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 118 xmlns="http://schemas.xmlsoap.org/wsdl/"> <! Type, message, and port type definitions removed for clarity > <binding name="CalculatorHttpGetBinding" type="tns:CalculatorPortType"/> <http:binding verb="GET"/> <operation name="Add"> <http:operation location="/Add"/> <input> <http:urlEncoded/> </input> <output> <mime:mimeXml part="Body"/> </output> <fault> <mime:mimeXml part="Fault"/> </fault> </operation> <operation name="Subtract"> <http:operation location="/Subtract"/> <input> <http:urlEncoded/> </input> <output> <mime:mimeXml part="Body"/> </output> <fault> <mime:mimeXml part="Fault"/> </fault> </operation> </binding> <! More definitions will go here. > </definitions> Parameters can also be encoded within the URL in a nonstandard way. In this case, the location attribute of the http:operation element will contain information about how the parameters are encoded. For example, the parameters for the Add method could be encoded within the URL as follows: 119 http://somedomain/Calculator/Add/2plus3 The parameters 2 and 3 were encoded within the path info of the URL where the parameters were delimited by plus. The resulting http:operation element would appear as follows within the binding definitions: <http:operation location="Add/(x)plus(y)"/> The individual message parts enclosed in parentheses are shown in their respective position within the relative URL. In this case, the input element within the binding for a particular operation would be decorated with an http:urlReplacement element. The third and final way of encoding the parameters that I will discuss is embedding the URL encoded parameters within the body of the HTTP request message (HTTP POST). For example, the parameters would be encoded within the body of the HTTP request as follows: Add="x=2&y=3" In this case, the input element can be described using the MIME type application/x-www- form-urlencoded. Therefore, the operation element would be decorated with a mime:content element. Here is the resulting HTTP POST binding definition for the Calculator Web service: <?xml version="1.0" encoding="utf-8"?> <definitions targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <! Type, message, and port type definitions removed for clarity > <binding name="CalculatorHttpPostBinding" type="tns:CalculatorPortType"/> <http:binding verb="POST"/> <operation name="Add"> <http:operation location="/Add"/> <input> <mime:content type="application/x-www-form-urlencoded"/> </input> <output> <mime:mimeXml part="Body"/> </output> <fault> <soap:fault name="CalculateFault" use="literal"/> </fault> </operation> <operation name="Subtract"> <http:operation location="/Subtract"/> 120 <input> <mime:content type="application/x-www-form-urlencoded"/> </input> <output> <mime:mimeXml part="Body"/> </output> <fault> <soap:fault name="CalculateFault" use="literal"/> </fault> </operation> </binding> <! More definitions will go here. > </definitions> The type attribute contains a valid MIME type used to indicate the type of content contained within the body of the HTTP message. The content of the HTTP message can also be labeled as being a member of a family of MIME types by using a wildcard. Here are a couple of examples: <! The content belongs to the MIME family of text types. > <mime:content type="text/*"/> <! Either declaration specifies all MIME types. > <mime:content type="text/*"/> <mime:content/> The mime:content element can also contain a part attribute, which is used to specify which part is contained within the body of the HTTP message. If the message has a MIME type of multipart/related, the message can contain a collection of MIME-formatted parts. For example, a multipart message can contain a SOAP message (text/xml) along with a JPEG image (image/jpeg). A multipart message can be represented within the binding definition using the mime:multipartRelated element. The mime:multipartRelated element contains a collection of mime:part elements. Each mime:part element represents a particular MIME-formatted part where its type is declared using the mime:content element. The following example demonstrates how a multipart message containing a SOAP message and a JPEG image is represented within a WSDL document: <mime:multipartRelated> <mime:part> <soap:body use="literal" part="xyCoordinates"/> </mime:part> <mime:part> 121 <mime:content type="image/jpeg" part="graph"/> </mime:part> </mime:multipartRelated> Notice that you can use the soap:body element to indicate that a particular MIME part contains a SOAP message. The message part is assumed to have a MIME type of text/xml and be contained within a valid SOAP envelope. If the MIME message part contains XML but is not SOAP compliant, you can use the mime:mimeXml element. The associated part element defines the root XML element instead of the body of a SOAP message. This element is used extensively in ASP.NET because the HTTP GET/POST version of a Web service returns the results using non-SOAP-compliant XML. service Element Binding The only HTTP extension element specified within the service element is http:address. Like its SOAP counterpart, it is contained within the port definition and is used to specify the URI where the Web service can be reached. Here is the service definition for the Calculator Web service: <?xml version="1.0" encoding="utf-8"?> <definitions targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <! Type, message, port type, and binding definitions removed for clarity > <service name="CalculatorService"> <port name="CalculatorHttpGetPort" binding="tns:CalculatorHttpGetBinding"> <http:address location="http://somedomain/Calculator"/> </port> <port name="CalculatorHttpPostPort" binding="tns:CalculatorHttpPostBinding"> <http::address location="http://somedomain/Calculator"/> </port> </service> </definitions> The preceding WSDL document defines two ports, one for HTTP GET and the other for HTTP POST. Both ports can be reached at http://somedomain/Calculator. import Element 122 Like XML Schema documents, WSDL documents can import other documents. You can thus achieve the same level of modularity that you can with XML Schema documents. Because a WSDL document can get rather large rather quickly, breaking it up into a number of smaller documents can help make the document easier to understand and possibly easier to maintain. A common way to divide a single service definition into multiple WSDL documents is to place protocol binding information in a separate document. This allows you to write the interface definitions once and then import them into a WSDL document that defines the specific protocols supported by a particular instance of the Web service. Unlike its XML Schema counterpart, the import element must contain both a namespace and a location attribute. Imagine that I took the WSDL document for the Calculator Web service and separated it into three parts. I placed the schema definitions into Calculator.xsd, the interface definitions into i_Calculator.wsdl, and the protocol into Calculator.wsdl. Calculator.wsdl serves as the WSDL document for the Web service by importing the other two documents. Here is Calculator.wsdl: <definitions xmlns="http://schemas.xmlsoap.org/wsdl/"> <! First import the schema definitions. > <import namespace="http://somedomain/myschema/" location="http://somedomain/Calculator.xsd"> <! Next import the port types and message definitions. > <import namespace="http://somedomain/Calculator/" location="http://somedomain/i_Calculator.wsdl"> <! Finally provide the protocol-specific binding definitions. > </definitions> Documentation You can include documentation within a WSDL document by using the definitions element’s name attribute or the document element. The name attribute can contain a short description of the WSDL document, and the document element can contain text as well as other elements. For example, I could use the document element to record metadata about the document. <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" name="The Calculator Web service provides the results of adding and subtracting two numbers."> <document> <author>Scott Short</author> <version>1.0</version> </document> 123 <types> <document>The following are defined using XML Schema.</document> <! Type definitions removed for clarity > </types> <! Additional definitions removed for clarity > </definitions> As you can see, the document element can be used inside any WSDL language element. The Calculator Web Service WSDL Document Here is the WSDL document that I built over the course of this chapter: <?xml version="1.0" encoding="utf-8"?> <definitions targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s="http://somedomain/Calculator/schema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema attributeFormDefault="qualified" elementFormDefault="qualified" xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://somedomain/Calculator/schema"> <! Definitions for both the Add and Subtract SOAP messages - -> <element name="Add"> <complexType> <all> <element name="x" type="int"/> <element name="y" type="int"/> </all> </complexType> </element> <element name="AddResult"> <complexType> <all> 124 <element name="result" type="int"/> </all> </complexType> </element> <element name="Subtract"> <complexType> <all> <element name="x" type="int"/> <element name="y" type="int"/> </all> </complexType> </element> <element name="SubtractResult"> <complexType> <all> <element name="result" type="int"/> </all> </complexType> </element> <! Common SOAP fault detail element used by Add and Subtract > <element name="CalculateFault"> <complexType> <all> <element name="x" type="int"/> <element name="y" type="int"/> <element name="Description" type="string"/> </all> </complexType> </element> <! Common result element for HTTP GET/POST binding > <element name="Result" type="int"/> </schema> </types> 125 <! Messages for SOAP-based Web service > <message name="AddMsgIn"> <part name="parameters" element="s:Add"/> </message> <message name="AddMsgOut"> <part name="parameters" element="s:SubtractResult"/> </message> <message name="SubtractMsgIn"> <part name="parameters" element="s:Add"/> </message> <message name="SubtractMsgOut"> <part name="parameters" element="s:SubtractResult"/> </message> <message name="CalculateFaultMsg"> <part name="fault" element="s:CalculateFault"/> </message> <! Messages for HTTP GET/POST-based Web service > <message name="AddHttpMsgIn"> <part name="x" type="xsd:string"/> <part name="y" type="xsd:string"/> </message> <message name="AddHttpMsgOut"> <part name="result" element="s:Result"/> </message> <message name="SubtractHttpMsgIn"> <part name="x" element="xsd:string"/> <part name="y" element="xsd:string"/> </message> <message name="SubtractHttpMsgOut"> <part name="result" element="s:Result"/> </message> <portType name="CalculatorPortType"> <operation name="Add"> <input message="tns:AddMsgIn"/> <output message="tns:AddMsgOut"/> <fault message="tns:CalculateFaultMsg" name="CalculateFault"/> </operation> [...]... you focus on the mechanics of building Web services using ASP.NET 130 The first thing I need to do is define the endpoint for the Securities Web service A Web service is defined by an asmx file, which serves as the endpoint for the Web service Calls made to asmx files are intercepted and processed by the ASP.NET runtime The implementation of the Web service is encapsulated within a class The class definition... consumed by clients The ASP.NET runtime automatically generates a WSDL document that describes the Web service You can access this by passing the value wsdl to the asmx file within the query string The following is a portion of the WSDL generated for the Securities Web service: The WSDL document describes the Web service and can be used by the ASP.NET platform to create proxies for calling Web methods I... Specifies the value of the description element under each operation element within each type definition within the ASP.NETgenerated WSDL document EnableSession Specifies whether the ASP.NET session state services will be available for the implementation of the method MessageName Specifies the name of the method exposed by the Web service Specifically, it sets the name of the element within the body of the. .. with the Securities Web service using the XML Document Object Model (DOM) To get the current price for Microsoft stock, you load the DOM with the results of the Web method call by passing http://localhost/Calculator.asmx/InstantQuote?symbol=MSFT to the load method The DOM will be initialized with the following XML returned from the Web service: < ?xml version="1.0" encoding="utf-8" ?> 197.75... to include Web services ASP.NET is also popular because it offers a rich set of services that you can leverage when you build applications With the introduction of ASP.NET, the platform facilitates the rapid creation and consumption of Web services ASP.NET abstracts the underlying Web services protocols such as SOAP, WSDL, and HTTP away from the developer As I demonstrated in Chapter 1, Web services. .. they can be leveraged from other applications For example, a portal site such as MSN or Yahoo! might want to provide these services but might lack the expertise or the desire to take on the burden of building the services themselves Instead, the portal site can provide a UI to the customer and use the brokerage firm’s Web service as the back end At worst, the portal will retain the customer within its... can disable it for an individual Web directory by modifying the web. config file The following example disables the documentation support: the configuration file removed for clarity > 141 Unfortunately, there is no way to disable the HTML and... implements the Web service If the code resides within the asmx file, you must set the Language attribute, which specifies the language in which the code was written The first time the Web service is accessed, the ASP.NET runtime will use the Language attribute to compile the code with the appropriate compiler Thus, even if the code implementing the Web service is contained within the asmx file, it will always... the C:\WINNT \Microsoft. NET\Framework\version\CONFIG directory The entry within the machine.config file for the default HTML documentation is as follows: the configuration file removed for clarity > 140 Despite the wsdl prefix, the wsdlHelpGenerator... to use them Web application developers have come to rely on services provided by the ASP platform, such as state management and security These services have been significantly improved in ASP.NET and can be leveraged to create robust Web services Additional services such as automatic generation of documentation have also been introduced specifically for Web services For a version 1 product, ASP.NET is . that let you focus on the mechanics of building Web services using ASP .NET. 131 The first thing I need to do is define the endpoint for the Securities Web service. A Web service is defined. EnableSession Specifies whether the ASP .NET session state services will be available for the implementation of the method. MessageName Specifies the name of the method exposed by the Web service. Specifically,. other applications. For example, a portal site such as MSN or Yahoo! might want to provide these services but might lack the expertise or the desire to take on the burden of building the services