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

The following WSDL document demonstrates the use of the http:binding element within the definition of the Calculator Web service:... For example, the parameters would be encoded within

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"/>

<part name="x" element="xsd:string"/>

<part name="y" element="xsd:string"/>

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

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"

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"?>

<definitio ns targetNamespace="http://somedomain/Calculator/wsdl" xmlns:tns="http://somedomain/Calculator/wsdl"

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

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:

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"

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

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: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"

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

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:

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

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"

<element name="x" type="int"/>

<element name="y" type="int"/>

<element name="result" type="int"/>

<element name="x" type="int"/>

<element name="y" type="int"/>

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

<! Messages for SOAP-based Web service >

<part name="x" type="xsd:string"/>

<part name="y" type="xsd:string"/>

<part name="x" element ="xsd:string"/>

<part name="y" element="xsd:string"/>

<operation name="Subtract">

<input message="tns:SubtractMsgIn"/>

<output message="tns:SubtractMsg Out"/>

<fault message="tns:CalculateFaultMsg" name="CalculateFault"/> </operation>

<output>

<mime:mimeXml part="Body"/>

</output>

WSDL provides a flexible and extensible means of documenting network services A WSDL

document is composed of five elements under the root definitions element: types , message, portType, binding, and service These elements are used to define Web services through a

series of associations

The types element contains schema definitions for the data exchanged between the client

and the server The default schema language is XML Schema However, you can specify

another schema language through the use of extensibility elements

The message element identifies a particular message that is exchanged between the client

and the server A message is composed of one or more parts Each part is represented by

the part element and can refer to an element or type definition defined within the types

element

The portTypes element contains one or more operation elements You can think of an

operation as an interface—a contract about how the client and the server will interact with each other to perform an action An operation can be one of four types: request-response, solicit-response, one-way, or notification

The binding element is used to associate a port type with a particular protocol This is

accomplished via extensibility elements Extensibility elements are elements defined outside the WSDL namespace The WSDL specification defines three sets of extensibility elements for specifying binding information: SOAP, HTTP GET/POST, and MIME Because specific technologies such as SOAP and HTTP are represented by extensibility elements, WSDL can

be used to describe prac tically any service

The service element contains one or more port elements A port element is used to define an

address where a Web service that supports a particular binding can be reached

Chapter 6: ASP.NET

Overview

ASP.NET, the next generation of the Microsoft Active Server Pages (ASP) platform, is

known for the ease with which it allows you to develop Web applications It provides a layer

of abstraction that lets you focus on solving business problems instead of developing the

underlying plumbing, which can greatly increase your productivity This model has been

extended beyond Web Forms 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 that expose simple interfaces require little, if any, knowledge of the underlying protocols

Sometimes you need to exercise a high degree of control over the serialization of the SOAP messages and the format of the WSDL document used to describe the Web service

Fortunately, ASP.NET provides the necessary hooks that allow you to control practically

every aspect of the implementation of a Web service In this chapter, I discuss the hooks

ASP.NET provides as well as examples of when 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 a remarkably feature-rich and solid development

platform However, as with any V1 product, ASP.NET has some quirks In this chapter, I talk about many of them and show you how to work through them

Creating an ASP.NET Web Service

Let’s say that an online brokerage firm wants to provide a Web service to its customers It could accomplish this by writing an ASP.NET Web application However, the firm wants to extend the reach of its services so that 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

In this chapter, I build the Securities Web service, which allows the client to perform actions such as obtaining a quote for a particular stock, bond, or mutual fund The individual

methods will contain skeleton implementations that let you focus on the mechanics of

building Web services using ASP.NET

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 can either appear inline within the asmx file or be contained in a separate dynamic link

library (DLL) The asmx page needs to contain information that the runtime can use to

locate the class

Each asmx page contains a directive at the top of the page that specifies where and in what form the implementation of the Web service can be found This directive is used by the

ASP.NET runtime to bind the Web service to a class that contains the implementation

Here is an example in which the implementation of the Web service is contained within the asmx file:

<%@ WebService Language="c#" Class="BrokerageFirm.Securities" %>

namespace BrokerageFirm

{

// Inline definition of the Securities class

public class Securities

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 be executed

as compiled machine code

Out of the box, ASP.NET is configured to dynamically compile code written in C#, Visual

Basic, Visual Basic NET, and JScript NET You can configure additional languages within the web.config file or the machine.config file The following is the compilation section of the

machine.config file found in the C:\WINNT\Microsoft.NET\Framework\version\CONFIG

maxBatchSize="max number of pages per batched compilation"

numRecompilesBeforeAppRestart="max number of recompilations

before appdomain is cycled"

defaultLanguage="name of a language as specified

in a <compiler/> tag below"

The compilation section also includes a list of assemblies that are referenced by code within the asmx file If the Securities Web service were to reference entities from an assembly

other than those listed in the preceding code, I could add a new machine-wide reference to

my machine.config file or an application-wide reference to my web.config file

The last add element specifies a wildcard for the assembly name If an assembly is

referenced within an asmx file that was not previously listed, the ASP.NET runtime will

search for the assembly (See the product documentation for the exact search order.)

The class implementing the Web service can also reside within a compiled assembly By

convention, the assembly is placed in the Web application’s bin directory because this

directory is always included in the search path of the runtime This is the default

configuration for Web services created using Visual Studio NET The following is the

WebService directive that Visual Studio NET creates automatically:

<%@ WebService Language="c#" Codebehind="Service1.asmx.cs"

Class="BrokerageFirm

.Service1" %>

As is typical in the Visual Studio product line, most of the attributes defined in the

WebService directive are used by the editor and are ignored by the runtime As I mentioned, you must specify the Language attribute only if the implementation of the Web service

resides within the asmx file In addition, the code-behind file is always ignored by the

ASP.NET runtime and is used by Visual Studio NET to bring up the appropriate source code file when you select View Code within the IDE

One other potential gotcha is that Visual Studio NET will only partially maintain this file

When you rename the asmx file to something more meaningful, Visual Studio NET will

automatically rename the associated code-behind file and update the WebService directive

accordingly As a common practice, I also rename the class that implements the Web

service to match the name of the asmx file

Unfortunately, Visual Studio NET will not automatically update the Class attribute If you

rename the class, you have to manually update this attribute yourself Furthermore, clicking the asmx file to update this attribute will display the design surface, not the file text Visual Studio NET does not provide the same buttons shown on an aspx file’s design

double-surface that allow you to switch between the design view and the underlying text of the file You have to right-click the file, choose Open With, and then select Source Code (Text)

Editor

Now that I have discussed the two options—placing the implementation for your Web service within the asmx file or within its own assembly—I am sure you are wondering which one you should use Well, as with most design decisions, it depends Placing the code within the

.asmx file provides the simplest means of deployment because ASP.NET will compile the code dynamically for you However, deploying the implementation within an assembly

ensures that your code will not contain compilation errors Also, if you are deploying the Web service outside the confines of your data center, others will not have access to the source code

Another potential advantage of having the implementation of your Web service reside within

an assembly is that it can be directly referenced by other applications hosted on the same machine For example, suppose I provide an HTML-based UI that allows my customers

access to the functionality of the Securities Web service If the class containing the

implementation of the Web service is in its own assembly, the Web application can reference the assembly and directly access the Web service class This avoids the unnecessary

overhead of accessing the functionality remotely

You should take this approach with caution, however Some Web services rely on services provided by the ASP.NET runtime to function correctly For example, a Web method might set an attribute stating that the ASP.NET runtime must create a new transaction on its

behalf Because ASP.NET is responsible for ensuring that a transaction is created, no

transaction will be creat ed if the class implementing the Web service is accessed directly Regardless of which option you choose, the code for implementing the Web service will be the same For starters, I will implement one method within my Securities Web service,

InstantQuote Plenty of services on the Web give quotes on the price of a company’s stock

However, these quotes are often time delayed and can be more than 20 minutes old

InstantQuote will use an extremely complex algorithm to obtain the price a security is trading

at on the floor Following is the implementation