Microsoft White Paper on SOAP in the Microsoft .NET Framework ...

flashypumpkincenterΛογισμικό & κατασκευή λογ/κού

14 Δεκ 2013 (πριν από 3 χρόνια και 8 μήνες)

65 εμφανίσεις


SOAP in the Microsoft .NET Framework and Visual
Studio .NET


Keith Ballinger, Program Manager for ASP .NET Web Services

Jonathan Hawkins, Program Manager for .NET Remoting

Pranish Kumar, Program Manager for ATL Server

Microsoft Corporation

Published:
No
vember 2000




The information contained in this document represents the current
view of Microsoft Corporation on the issues discussed as of the date
of publication. Because Microsoft must respond to changing market
conditions, it should not be interprete
d to be a commitment on the
part of Microsoft, and Microsoft cannot guarantee the accuracy of
any information presented after the date of publication.

This white paper is for informational purposes only. MICROSOFT
MAKES NO WARRANTIES, EXPRESS OR IMPLIED, I
N THIS
DOCUMENT.

Complying with all applicable copyright laws is the responsibility of
the user. Without limiting the rights under copyright, no part of this
document may be reproduced, stored in or introduced into a retrieval
system, or transmitted in any

form or by any means (electronic,
mechanical, photocopying, recording, or otherwise), or for any
purpose, without the express written permission of Microsoft
Corporation.

Microsoft may have patents, patent applications, trademarks,
copyrights, or other in
tellectual property rights covering subject
matter in this document. Except as expressly provided in any written
license agreement from Microsoft, the furnishing of this document
does not give you any license to these patents, trademarks,
copyrights, or ot
her intellectual property.


© 2001 Microsoft Corporation. All rights reserved.
Microsoft,
Windows,
Windows

NT
, ActiveX, Visual C++, and
Visual Studio

are
either registered trademarks or trademarks of Microsoft Corporation
in the United States and/or other
countries.

Other product and company names mentioned herein may be the
trademarks of their respective owners.

Microsoft Corporation • One Microsoft Way • Redmond, WA 98052
-
6399 • USA

Contents

If you bu
ild .ASP applications, ASP .NET Web Services:

...................

2

If you build MTS/COM+ applications, .NET Remoting:

2

If you build ATL/C++ applications, ATL Serv
er:

2

Using SOAP as a Web Developer

................................
..........................

3

Accessing Web Services

4

Using SOAP as a Component

Developer

................................
.............

6

Example: Managed Code Events over SOAP

6

Server Side

6

Client Side

11

Makefile

13

Using SOAP as an ATL Developer

................................
......................

15

Consuming Web Services with ATL Server

18

Conclusion

................................
................................
.............................

19





The information contained in this document represents the current
view of Microsoft Corporation on the issues discussed as of the date
of publication. Because Mi
crosoft must respond to changing market
conditions, it should not be interpreted to be a commitment on the
part of Microsoft, and Microsoft cannot guarantee the accuracy of
any information presented after the date of publication.

This white paper is for in
formational purposes only. MICROSOFT
MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS
DOCUMENT.

Complying with all applicable copyright laws is the responsibility of
the user. Without limiting the rights under copyright, no part of this
document may be rep
roduced, stored in or introduced into a retrieval
system, or transmitted in any form or by any means (electronic,
mechanical, photocopying, recording, or otherwise), or for any
purpose, without the express written permission of Microsoft
Corporation.

Micro
soft may have patents, patent applications, trademarks,
copyrights, or other intellectual property rights covering subject
matter in this document. Except as expressly provided in any written
license agreement from Microsoft, the furnishing of this documen
t
does not give you any license to these patents, trademarks,
copyrights, or other intellectual property.


© 2001 Microsoft Corporation. All rights reserved.
Microsoft,
Windows,
Windows

NT
, ActiveX, Visual C++, and Visual Studio

are
either registered trade
marks or trademarks of Microsoft Corporation
in the United States and/or other countries.

Other product and company names mentioned herein may be the
trademarks of their respective owners.

Microsoft Corporation • One Microsoft Way • Redmond, WA 98052
-
6399
• USA




1

Introduction

The Microsoft® .NET Framework and Microsoft® Visual Studio® .NET take advantage of XML and SOAP
technologies to allow developers to create solutions with reach. SOAP is a simple and lightweight protocol
with wide industry support. It is

useful and usable for a wide variety of applications. SOAP and the .NET
Frameworks are an easy and natural fit.

SOAP was designed from the ground up to be an extremely simple protocol that can be implemented in a
variety of ways for a variety of different

needs. Many other companies have produced implementations,
including IBM, Develop Mentor, and Userland, as well as Microsoft.

There are several key technologies in the framework that use SOAP. Each of these features solves common
problems that developers

encounter when creating SOAP
-
based solutions. These areas are .NET Remoting,
ASP .NET Web Services, and ATL Web Services. These features share a number of common technologies
and characteristics:



XML for message generation and consumption.



SOAP 1.1 comp
liance, including Section 5 SOAP encoding. This enables strong SOAP interoperability
with other SOAP implementations.



XML
-
fidelity (non
-
section 5 SOAP encoding) for a very disconnected model.



WSDL (a form of XML Schema) for Description.



Scaling out usin
g a stateless programming model.



An excellent development environment with Visual Studio .NET.

ASP .NET Web Services and .NET Remoting also share the following:



XCOPY deployment.



System .NET, which works very well in both the server and client environm
ent for network
communication.



Common language runtime is leveraged for managed code and thread pool.



Strong SOAP support for features like SOAP Headers and one
-
way messages.






Potential to be used with C#, Visual Basic .NET, or any CLS
-
compliant language

to write applications
(Cobol, Python, ComponentPascal, and so forth).

In addition to the common characteristics and technologies listed above, ASP .NET Web Services, .NET
Remoting, and ATL Web Services provide a number of distinct capabilities for develo
pers. The following
points help developers to start off in the right direction when building an application.

If you build .ASP applications, ASP .NET Web Services:



Allows strong integration with the ASP .NET HTTP runtime.



Encourages the developer to focus

on exposing the application using XSD data types.



Provides strong designer support in Visual Studio .NET.

If you build MTS/COM+ applications, .NET Remoting:



Provides full managed code type
-
system fidelity over the network.



Provides the capability to pa
ss objects by reference around the network, and return to a particular object
in a particular process.



Provides binary communication.

If you build ATL/C++ applications, ATL Server:



Provides a flexible and controllable native (C++) solution.



Is built on
top of the ATL Server ISAPI Web application architecture (leverages thread pool, cache, and
so on).




Using SOAP as a Web Developer

ASP .NET Web Services offer a RAD way to easily create and consume Web services. These services are
loosely coupled, and offe
r a high degree of integration with ASP .NET. ASP .NET Web Services are the
preferred way for Web developers to expose Web services on the Internet. The goal is quick, easy, and high
-
performing SOAP services.

ASP .NET Web Services offers deep integration w
ith the ASP .NET HTTP engine. This allows developers
who are experienced with Microsoft Web development technologies to build and consume SOAP
-
based Web
services easily.

ASP .NET provides support for Web Services with the .asmx file. An .asmx file is a tex
t file that is similar to an
.aspx file. These files can be part of an ASP .NET application that includes .aspx files. These files are then
URI
-
addressable, just as .aspx files are.

The following is a very simple example of an .asmx file:

<%@ WebService
Language="C#" Class="HelloWorld" %>


using System;

using System.Web.Services;


public class HelloWorld : WebService {



[WebMethod] public String SayHelloWorld() {


return "Hello World";


}





}

This file starts with an ASP .NET directive We
b Service, and sets the language to C# (you could also set the
language to Microsoft Visual Basic®, C, or any of about 30 third
-
party languages). Next, it imports the
namespace System.Web.Services. This namespace is needed, and you must include it. Next, t
he class
HelloWorld

is declared. This class is derived from the base class
WebService
. Finally, any methods that will
be accessible as part of the service have the custom attribute
[WebMethod]

(or <"WebMethod()>" in Visual
Basic) in front of their signatur
es.

To make this service available, we might name the file HelloWorld.asmx and place it on a server called
Foo
inside a virtual directory called
Bar
. With virtually any HTML 3.2 (or later) browser, you could then enter the
URL http://Foo/Bar/HelloWorld.as
mx and the resulting page would show the public methods for this Web
Service (those marked with the
WebMethod

attribute), as well which protocols (such as SOAP, or HTTP
GET) you can use to invoke these methods. Entering http://Foo/Bar/HelloWorld.asmx?SDL i
nto the Internet
Explorer address location produces the same information as an XML file, based on the Service Description
Language (WSDL) grammar. This WSDL file is used by clients that access the service and is very important.

Accessing Web Services

Besid
es technology that allows developers to create Web Services, Microsoft .NET Framework provides a
sophisticated set of tools and code to consume

or access as a client

Web Services. Because Web
Services are based on open protocols such as the Simple Object A
ccess Protocol (SOAP) and HTTP, this
client technology can also be used to consume non
-
ASP .NET Web Services.

With the SDK, there is a tool called WebServiceUtil.exe (this works automatically in the VS IDE using "Add
Web Reference…"). This program can be
used to download the WSDL description of a Web Service and
create a proxy class that addresses this service. For example, you could enter:

WebServiceUtil /c:proxy /pa:http://someDomain.com/someFolder/HelloWorld.asmx?SDL

A Proxy class called
HelloWorld.cs

would then be created.

This class would look very similar to the class created in the previous section. It would contain a method
called
SayHelloWorld

that returns a string. Compiling this proxy class into an application, and then calling its
method, resul
ts in the proxy class packaging a SOAP request across HTTP and receiving the SOAP
-
encoded
response, which is then marshaled as a string.

From the client perspective, the code would be simple:




Dim myHelloWorld As New HelloWorld()

Dim sReturn As String = myH
elloWorld.SayHelloWorld()

And the return would be "Hello World."




Using SOAP as a Component Developer

Microsoft .NET Remoting allows developers who need a high degree of control and want to choose between
tight coupling or loose coupling to create distribut
ed applications.

It also provides deep integration with the common language runtime and offers developers full type
-
system
fidelity across the wire. This includes constructors, delegates, overloaded methods, passing objects by value
and by reference, class

hierarchies, interfaces, methods, properties, fields, Marshal by Value (make a copy)
and Marshal by Ref (pass an ObjRef) objects between applications (Web Services) over the wire using any of
the pluggable channels, distributed identity, activation, lease
-
based lifetime, and CallContext (flow objects in
the SOAP Headers independent of the Parameters).

Using .NET Remoting enables developers to expose Remoting endpoints from any process, including console
app, GUI app, NT Service, and IIS. This happens over
any transport (with pluggable channels) using any
payload encoding (with pluggable serialization formatters with SOAP and Binary formatters provided in the
product). SOAP=HTTP+XML is the sweet spot, with full support for SOAP 1.1 over HTTP and SMTP.

There

is support for WSDL to describe the Web Service and full runtime type
-
system fidelity. .NET Remoting
provides the soapsuds tool in the .NET SDK that generates service descriptions from metadata for managed
classes and COM objects. The soapsuds tool also c
onsumes service descriptions and generates metadata
and proxies. A rich interception model is provided, that allows for developers to plug in their own behavior as
message flow inbound and outbound from the application. A TCP Channel (using sockets) with a

Binary
Encoding is provided for those folks who want to get down to the metal.

.NET Remoting remotes managed components, native COM/COM+ Components, and Serviced Components
(managed components serviced by COM+ Services). All this happens over SOAP, Binary
, and any of the
pluggable channels and formats.

Example: Managed Code Events over SOAP

The following code demonstrates how managed code events can be fired between two applications. The
client has a local object that it registers for event notification w
ith remote object. When the server object is
called, it fires the event. This results in a callback to the client's local object.

Server Side

zap.cs

using System;





namespace Zap

{


// Define the event arguments


public class GreetingEventArgs : EventArgs


{


public GreetingEventArgs(string greeting)


{


this.greeting = greeting;


}



public string greeting;


}



// Define the event


public delegate void GreetingEvent(object sender,

GreetingEventArgs e);






// Define the Service


pub
lic class Waz : MarshalByRefObject


{


// The client will subscribe and


// unsubscribe to this event


public event GreetingEvent Greeting;



// Method called remotely by client


public void HelloMethod(string greeting)


{


Console
.WriteLine("Received String {0}", greeting);



// Package String in GreetingEventArgs


GreetingEventArgs e = new GreetingEventArgs(greeting);



// Fire Event


if (Greeting != null)


{





Greeting(this, e);


}


}


}

}


host.cs


using System;

using System.IO;

using System.Runtime.Remoting;

using System.Runtime.Remoting.Channels.HTTP;


public class Host

{


public static void Main(string[] args)


{


// Manually load the http channel.





// This could also be done in

the remoting configuration file.


ChannelServices.RegisterChannel(new HTTPChannel(999));



// Register the wellknown server type.


// This could also done in the remoting configuration file.


RemotingServices.RegisterWellKnownType(



"Zap", // Assembly


"Zap.Waz", // Full type name


"host/Waz.soap", // URI


WellKnownObjectMode.Singleton); // Object Mode



// We are done, wait unti
l the user wants to exit


Console.WriteLine("Host is ready to process remote messages.");


Console.WriteLine("Press ENTER to exit");


String keyState = Console.ReadLine();


}

}




Client Side

client.cs


using System;

using System.Runtime.Remoting;

u
sing System.Runtime.Remoting.Channels.HTTP;


using Zap;


// Local Marshal by Ref Object onto which

// the event will be fired

public class Baz : MarshalByRefObject

{


public void GreetingHandler(object sender, GreetingEventArgs e)


{


Console.WriteLi
ne("GreetingHandler callback : Greeting : {0}
\
n",


e.greeting);


}




}


public class Client

{


public static void Main(String[] args)


{


Baz baz = new Baz();



// This could also be done with a Remoting configuration file




// Registe the HTTP Channel


ChannelServices.RegisterChannel(new HTTPChannel(0));



// Obtain a Proxy to the SOAP URL


Waz waz = (Waz)Activator.GetObject(


typeof(Waz),


"http://localhos
t:999/host/Waz.soap"


);







// Subscribe to event : occurs over SOAP


waz.Greeting += new GreetingEvent(baz.GreetingHandler);



for (int i = 0; i < 5; i++)


{


// Occurs over SOAP to waz)


waz.HelloMethod(
"Bill" + " " + i);


}



// Unsubscribe to event : occurs over SOAP


waz.Greeting
-
= new GreetingEvent(baz.GreetingHandler);


}

}

Makefile

makefile





all: Host.exe Zap.dll Client.exe


Host.exe: Host.cs


csc /r:System.Runtime.Remoting.dll Host.cs


Z
ap.dll: Zap.cs


csc /t:library
-
out:Zap.dll Zap.cs



Client.exe: Zap.dll Client.cs


csc /r:System.Runtime.Remoting.dll /r:Zap.dll Client.cs

Start host.exe in one window and then start client.exe in another. You will see events being fired back to the
clie
nt.

This is an example of one the many applications of .NET Remoting, which provides the full CLR managed
code type system over the network. .NET Remoting is also an excellent SOAP Server and Client, because it
is fully SOAP 1.1 compliant.




Using SOAP as
an ATL Developer

ATL Server Web Services offer an easy way for C++ developers to create and consume Web Services in
native code. ATL Server is the preferred way for C++ developers to expose and consume Web Services on
the Internet. It has been designed to
be the fast, lightweight, highly flexible library for Web applications
including SOAP services.

ATL Server uses the ATL name because it embodies the ATL goal of high performance and flexibility. For
example, you can easily discard the ATL Server HTTP mode
l and write your own dispatcher, while still
deriving the benefits of the ATL Server marshaling/protocol code.

ATL Server Web Services use a COM
-
like syntax for describing interfaces, making it easy to learn for current
ATL developers. This COM
-
like synta
x allows the developer to easily expose an object as both

a COM object
and a Web Service at the same time.

The introduction of attributes greatly simplifies the code, making it much easier for non
-
ATL developers as
well. ATL Server has been designed to int
eroperate with all the other .NET Web Services, making it easy for a
developer to use many technologies in an application.

The Interface
. The new interface keyword allows developers to easily create interfaces for COM objects or
Web Services.

[


uuid("D
7DAE6FD
-
AEBB
-
4579
-
BD8D
-
866F74139501"),


object

]

__interface IWeb_Service_ExampleService

{


[id(1)] HRESULT HelloWorld([in] BSTR bstrInput, [out, retval] BSTR *bstrOutput);

};




This is how ATL Server allows you to define Web Service interfaces. Through

the use of C++ attributes, inline
IDL attributes and the new __interface keyword, ATL Server Web Service interfaces look much like the new
attributed versions of COM interfaces. Here we have an example of a Web Service interface,
IWeb_Service_ExampleServi
ce, which implements a single method,
HelloWorld
.
HelloWorld

takes a BSTR
as input and returns a BSTR as output.

The Request Handler
. A request handler is a C++ class, which is exposed via a handler map and has
methods which are exposed via a replacement m
ethod map. The handler map is simply a mapping between
text tags and the name of the class, and the method map is just a mapping between text tags and methods in
the class.


[


request_handler(name="Default",sdl="GenWeb_Service_ExampleServiceSDL"),


s
oap_handler(


name="Web_Service_ExampleService",


namespace="urn:Web_Service_ExampleService",


protocol="soap"


)

]

class CWeb_Service_ExampleService:


public IWeb_Service_ExampleService

{

public:







[ soap_method ]


HRESULT Hello
World(BSTR bstrInput, BSTR *bstrOutput)


{


CComBSTR bstrOut(L"Hello ");


bstrOut += bstrInput;


bstrOut += L"!";


*bstrOutput = bstrOut.Detach();




return S_OK;


}

};

The ATL Server request handler model is very similar

for Web applications and Web Services; Figure 1
shows the request
-
handling model:


Figure 1. ATL Server request handler model

The HTTP Request co
mes into IIS, which maps the request (based on the URL and extension) to an
appropriate ISAPI
DLL
. In turn, the ISAPI DLL maps the handler specified in the request (the handler is
specified either in a tag or query parameter) to an appropriate Application
DLL. The Application DLL maps
this handler to a C++ object. The only difference between a Web application and a Web Service in this model
(the ATL Server model) is in this final step. With Web Services the C++ object is capable of



decoding/encoding SOAP (t
he code to do this is inserted by the compiler when it parses the soap_handler
attribute).

You can see that our class inherits from our interface and that we use the [soap_method] attribute to indicate
that the
HelloWorld

method will handle SOAP requests.

We implement this method just as we would any
other C++ method.

The soap_handler attribute also ensures that a valid WSDL describing your service is generated
automatically. This description of your service (with the XML/WSDL format) is used by consumers

of your
Web Service to make sure that they send/receive the correct data in the correct format.

Consuming Web Services with ATL Server

Consuming Web Services with ATL Server is also a relatively simple operation. The developer uses the "Add
Web Reference
" dialog box (and points it to a .disco file, which in turn points to the WSDL), just as they would
to consume any other type of Web reference. Behind the scenes this dialog box runs the sproxy.exe utility on
the Web Service's WSDL (there is a different ut
ility for non
-
native .NET Web Services).

This operation creates the Web Service proxy file, which contains all the C++ code required to utilize the
requested Web Service. Using the information in the WSDL, the proxy generator can work out what the Web
Serv
ice expects to receive and what it will return to the client. This in turn allows the proxy generator to create
the header file that can "talk" with the Web Service.

You only need to create an instance of your
Web Service

class (as found in the generated
header file) and
use the appropriate method or methods. For example:

CWeb_Service_ExampleServiceService MyService;

CComBSTR bstrOut;

CComBSTR bstrIn(L"World");

MyService.HelloWorld ( bstrIn ,&bstrOut,);

wprintf(bstrOut);

And there you have it, a basic ATL
Server Web Service and a basic ATL Server Web Service Consumer.




Conclusion

The primary goal of this article is to provide a broad perspective of the SOAP offerings in the .NET
Frameworks and Visual Studio .NET. The secondary goal is to provide a roadmap fo
r customers about which
path to use when starting to build an application that uses SOAP.