If SOAP message customization becomes necessary for a particular Web service that you wish to implement, the .NET Framework and ASP.NET provide the means to gain access to the SOAP messages so that you can perform the customizations that you need. In this section, we will look at some of the features provided by ASP.NET that you can use to customize the default SOAP message formats and contents.
Using SOAP headers
SOAP headers are the chief extensibility mechanism offered by the SOAP specification. This feature enables you to piggyback metadata along with a method request or response message that can be used by the receiver to control, or add additional context to, the method call.
For example, user credentials are often added as a SOAP header to enable a Web service method to authenticate a user before allowing the method call to be executed. In this example, the SOAP header is added by the consumer application and processed by the Web service method.
The SOAP specification does not define the contents of SOAP headers. The content and semantics associated with a SOAP header are completely defined by the application that adds the header and the recipient that processes it.
ASP.NET Web Services use SOAP as the default protocol for exchanging messages. This makes it possible for applications to add SOAP headers for their own use. Adding SOAP headers to ASP.NET Web Services is as simple as adding a SoapHeader attribute onto a Web service method.
.NET SoapHeader class
The .NET Framework provides a SoapHeader base class (found in the System.Web. Services.Protocols namespace), which we can inherit from to create and use a SOAP header.
.NET SoapHeader attribute
The SoapHeader attribute is used to enable support for SOAP headers on specific Web service methods that are declared with the WebMethod attribute. Specifically, the SoapHeader attribute is supplied with the name of a member variable that is an instance of our custom SoapHeader class. Technically, this syntax is setting a property of the SoapHeader attribute, namely the MemberName property. The SoapHeader attribute supports three properties:
MemberName
Direction
Required
The MemberName property of the SoapHeader attribute identifies the name of the class variable that determines the type of the SOAP header. In our example, the type of the SOAP header is obtained from the AuthSoapHeader member variable within the MyWebService class.
The Direction property of the SoapHeader attribute is used to specify in which direction the header is expected to be supplied. By default, SOAP headers are attached to method requests only and are said to be inbound to the Web service. Using this property, we can change this default behavior.
Using SOAP extensions
One of the more advanced features of SOAP within the .NET Framework is the SOAP extensions technology. Using this technology, you can inspect or modify a SOAP message at specific stages in message processing on either the client (consumer of the Web service) or server (the Web service itself). Of course, this assumes that the client and server are both based on .NET.
SOAP extensions are a powerful feature, because they enable you to implement some very interesting applications that can be leveraged by Web services and/or their clients in a completely transparent manner. For example, you can create extensions that do the following:
These are just a few examples of the many other potentially useful applications of this technology.
The .NET Framework exposes this functionality through the following base classes that you can derive from to create custom SOAP extensions:
System.Web.Services.Protocols.SoapExtension
System.Web.Services.Protocols.SoapExtensionAttribute
The SoapExtension class is the base class for all SOAP extensions. This class defines a method named ProcessMessage that is called several times at various stages of message processing.
To create a SOAP extension, you simply derive a class from the SoapExtension class and implement your extension code in the ProcessMessage method. The SOAP message is supplied to you as an input argument to the method. You can examine the SOAP message to determine which stage of message processing is in effect (using the Stage property) and then perform the appropriate processing for that stage.
For example, a SOAP extension that is applied to a Web service client could gain access to the SOAP request message at the AfterSerialize stage. To gain access to the SOAP response message, the extension would wait for the BeforeDeserialize stage to occur.
In addition to implementing the SoapExtension class, you must also derive a class from the SoapExtensionAttribute base class. You use this class to create and apply a custom SOAP extension attribute to a method. When the custom extension attribute is added to a Web service method or a proxy class method, the associated extension is invoked at the appropriate time.
Handling SOAP exceptions
SOAP defines a mechanism for Web services to return a SOAP exception message in the face of a failed method call.Handling SOAP exceptions within .NET applications (including ASP.NET applications) is a simple, straightforward process.
The .NET Framework implements a class named SoapException (contained within the System.Web.Services.protocols namespace). The ASP.NET runtime converts SOAP exceptions into instances of the .NET SoapException class. This means that you can use try . . . catch blocks within your calls to Web service methods to catch SOAP exceptions.
Microsoft SOAP Toolkit
As you might expect, it is entirely possible to create and consume Web services without the infrastructure and services provided by the .NET Framework and Visual Studio .NET (although it is much easier to do so with their support). Because Web services are based on XML, HTTP, and SOAP, all we need to create or consume Web services are implementations of these technologies. This is precisely what Microsoft has done with the Microsoft SOAP toolkit.
The Microsoft SOAP toolkit supplies the technologies and tools needed to build and deploy Web services using Visual Studio 6.0 as the development environment along with the familiar COM programming model. In addition to building Web services that can run on Windows NT 4.0 SP6 and Windows 2000, you can build Web service consumers that will run on Windows 98, Windows ME, Windows NT 4.0 SP6, or Windows 2000 SP1.
Toolkit features
The toolkit contains both client- and server-side COM components as well as development tools that enable you to build or consume Web services using Visual Studio 6.0 as the development environment. The following are the technologies and tools included in the SOAP toolkit:
A server-side component that maps Web service requests to COM object method calls described by WSDL and Web Service Meta Language (WSML) documents
A client-side component that enables a consumer to call Web services described by a WSDL document
Components that generate, transport, and process SOAP messages § A WSDL/WSML document -generator tool
A Visual Basic Add-in that simplifies the processing of XML documents contained in SOAP messages § Additional APIs, utilities, and sample applications that illustrate how to use the SOAP Toolkit to build Web service and consumer applications It is worth noting here that Web service consumers created with the SOAP toolkit can invoke any Web service, whether it is based on the SOAP toolkit, ASP.NET, or some other Web service implementation. Likewise, Web services created with the SOAP toolkit can be invoked by any Web service client, regardless of implementation.
This illustrates one of the most powerful features of the Web services model that we have discussed previously: implementation independence. The way in which a Web service or Web service consumer is implemented is unimportant so long as they can communicate via XML, HTTP, and SOAP and implement the standards in an equivalent manner.
Creating a Web service
To enable Web service capabilities on the server, you must first and foremost be able to listen for Web service requests (in other words, SOAP messages) that are delivered to the server. This means that the Web server must be configured to listen for and process Web service request messages.
The SOAP Toolkit provides two choices for providing a SOAP listener for the Internet Information Server (IIS) Web server: an Internet Server API (ISAPI) listener and an Active Server Pages (ASP) listener. Your choice of which listener to use depends on the following:
In most cases, you can choose the ISAPI listener. The advantages of the ISAPI listener are that it is faster than the ASP listener and does not require you to implement any code. You simply need to supply the WSDL and WSML files that describe the Web service and the mappings to COM server methods. The disadvantage of the ISAPI listener lies in the fact that you have no control over the invocation of Web service methods (this is done automatically).
If you need to parse or validate input arguments, perform security checks, or execute similar actions on an incoming request, you must use the ASP listener. The advantage of the ASP listener is that you can perform special message processing on the server before invoking the Web service method.
The drawbacks of the ASP listener are that it is slower than the ISAPI listener and you must implement custom code in an ASP page to invoke the Web service methods. After making your choice, you must edit the WSDL document to specify the appropriate URL of the Web service endpoint. For the ASP listener, you should specify the URL to the ASP file. To use the ISAPI listener, you specify the URL to the WSDL file.
If you are using the ISAPI listener, Web service message processing is automatic. When an incoming SOAP request is detected, the ISAPI listener is invoked to handle the message. The ISAPI listener loads the WSDL and WSML files, executes the request, and returns the results in a response message. In this scenario, you only need provide the WSDL and WSML files.
The SOAPServer component enables Web service request messages to call methods on COM components. The component exposes several properties and methods that permit an ASP page to pass a Web service request to the component for execution (via the request stream) and supply the results to the caller (via the response stream). Using this component, the ASP page does not have to understand how to process SOAP messages.
To use the SOAPServer component, you specify the WSDL and WSML documents as input arguments to the initialization method. This allows the component to create the mappings between Web service requests and COM method calls. After you have initialized the SOAPServer object, you can call its invoke method, passing the ASP input stream and output stream as arguments to the method. When you call the invoke method on the SOAPServer object, the following steps occur:
1. The SOAPServer object deserializes the SOAP request message supplied to it via the invoke method.
2. The request is then examined to locate the COM component and method to be called from the WSDL and WSML documents that were loaded when the SOAPServer object was initialized.
3. An instance of the identified COM object is created and the 0appropriate method is called using the arguments obtained from the request message.
4. The result is obtained from the method call and serialized into a SOAP response message.
5. The SOAP response message is returned to the caller via an output argument of the invoke method.
Creating a Web service consumer
The SOAPClient COM component enables Web service consumers to call Web services. This component leverages the features of the SOAP Toolkit to provide properties and methods that a Web service consumer can use to call Web service methods without having to deal with SOAP messages directly. In this way, the SOAPClient component acts as a proxy object for the Web service.
To use the SOAPClient component, you must have access to the WSDL document that describes the Web service. When you call the initialization method on the component, you pass in the location of the WSDL document. This causes all the operations defined in the WSDL document to be dynamically bound to the SOAPClient component. Once this has been completed, you can invoke the methods defined in the WSDL document via the SOAPClient object.
When you invoke a Web service method bound to the SOAPClient object, the following steps occur:
1. The SOAPClient object serializes the method call into a SOAP request message and delivers it to the server.
2. The server deserializes the SOAP request message and processes the request.
3. The server serializes the result into a SOAP response message and delivers it to the client.
4. The SOAPClient object deserializes the SOAP response message and returns the result to the caller.
5. The SOAPClient object also exposes SOAP fault properties so that you can examine error information in case a method call fails for some reason.
To summarize, the SOAPClient object makes it easy to consume Web services in a COM-like manner. The consumer need only supply the WSDL document that describes the Web service to the SOAPClient object in order to call the operations exposed by the Web service.
The SOAPClient object takes care of translating COM method calls into SOAP requests and then translating the SOAP response into a COM method return value. If an error occurs in the method call, the SOAPClient object exposes properties that allow a consumer to gain access to the SOAP fault information that is returned.
WSDL/WSML generator tool
The WSDL/WSML generator tool is used to automatically generate WSDL and WSML documents from COM type libraries. The graphical version of the tool (named Wsdlgen.exe) walks you through the process of generating these documents. It will request the type of listener you wish to use, the location of the COM type library, which methods you wish to expose from the available interfaces in the type library, the folder in which to write the WSDL and WSML documents, and a few other details.
After answering these questions, the tool will generate the files for you. If you wish to script the generation of these files, a command-line version of the tool is also supplied, named Wsdlstb.exe. You can use the /? switch on the command line to get help information on valid command parameters and switches. The bottom line here is that the WSDL/WSML generator tool can be a great timesaver when preparing your COM components for accessibility as Web services.
SOAP trace utility
One final useful utility to point out that ships with the Microsoft SOAP Toolkit is the SOAP trace utility. Using this graphical utility, you can view SOAP request and response messages transported over HTTP between a Web service and Web service consumer. The trace utility can be configured to run either on the client or the server. To run the trace utility on the server, you must make a small modification to the WSDL document that specifies the URL to the SOAP endpoint.
Once this has been done, you can start the trace utility to begin a tracing session. To run the trace utility on the client, you must copy the WSDL document to the client machine, make a similar modification to the WSDL document, and start the trace utility. After starting the utility, you need to specify the name of the host where the actual Web service is running. After doing so, you will be able to begin a tracing session.
RELATED POST
CREATING ASSEMBLIES WITH ASP.NET
BUILDING HANDLERS IN ASP.NET
INTERFACES AND CLASSES CREATION IN ASP.NET
CACHING IN ASP.NET
CACHING IN ASP.NET PART TWO
WIRE LESS APPLICATION WITH ASP.NET
SECURITY IN ASP.NET PART ONE
SECURITY IN ASP.NET PART TWO
LOCALIZING ASP.NET APPLICATIONS
DEPLOYING ASP.NET APPLICATIONS
ASP.NET CONFIGURATION SYSTEM
WEB SERVICES IN ASP.NET
WEB SERVICES PART TWO
WEB SERVICE INFRASTRUCTURE
WEB SERVICE INFRASTRUCTURE PART TWO
EXCHANGING MESSAGES IN ASP.NET
MICROSOFT HAIL STORM
SOAP AND DOT NET PART ONE
SOAP AND DOT NET PART TWO
Using SOAP headers
SOAP headers are the chief extensibility mechanism offered by the SOAP specification. This feature enables you to piggyback metadata along with a method request or response message that can be used by the receiver to control, or add additional context to, the method call.
For example, user credentials are often added as a SOAP header to enable a Web service method to authenticate a user before allowing the method call to be executed. In this example, the SOAP header is added by the consumer application and processed by the Web service method.
The SOAP specification does not define the contents of SOAP headers. The content and semantics associated with a SOAP header are completely defined by the application that adds the header and the recipient that processes it.
ASP.NET Web Services use SOAP as the default protocol for exchanging messages. This makes it possible for applications to add SOAP headers for their own use. Adding SOAP headers to ASP.NET Web Services is as simple as adding a SoapHeader attribute onto a Web service method.
.NET SoapHeader class
The .NET Framework provides a SoapHeader base class (found in the System.Web. Services.Protocols namespace), which we can inherit from to create and use a SOAP header.
.NET SoapHeader attribute
The SoapHeader attribute is used to enable support for SOAP headers on specific Web service methods that are declared with the WebMethod attribute. Specifically, the SoapHeader attribute is supplied with the name of a member variable that is an instance of our custom SoapHeader class. Technically, this syntax is setting a property of the SoapHeader attribute, namely the MemberName property. The SoapHeader attribute supports three properties:
MemberName
Direction
Required
The MemberName property of the SoapHeader attribute identifies the name of the class variable that determines the type of the SOAP header. In our example, the type of the SOAP header is obtained from the AuthSoapHeader member variable within the MyWebService class.
The Direction property of the SoapHeader attribute is used to specify in which direction the header is expected to be supplied. By default, SOAP headers are attached to method requests only and are said to be inbound to the Web service. Using this property, we can change this default behavior.
Using SOAP extensions
One of the more advanced features of SOAP within the .NET Framework is the SOAP extensions technology. Using this technology, you can inspect or modify a SOAP message at specific stages in message processing on either the client (consumer of the Web service) or server (the Web service itself). Of course, this assumes that the client and server are both based on .NET.
SOAP extensions are a powerful feature, because they enable you to implement some very interesting applications that can be leveraged by Web services and/or their clients in a completely transparent manner. For example, you can create extensions that do the following:
- Encrypt messages to protect the contents while in transit
- Compress messages to reduce the size of the transmission stream
- Log messages for auditing or tracing message activity (especially useful in debugging)
- Process SOAP attachments
These are just a few examples of the many other potentially useful applications of this technology.
The .NET Framework exposes this functionality through the following base classes that you can derive from to create custom SOAP extensions:
System.Web.Services.Protocols.SoapExtension
System.Web.Services.Protocols.SoapExtensionAttribute
The SoapExtension class is the base class for all SOAP extensions. This class defines a method named ProcessMessage that is called several times at various stages of message processing.
To create a SOAP extension, you simply derive a class from the SoapExtension class and implement your extension code in the ProcessMessage method. The SOAP message is supplied to you as an input argument to the method. You can examine the SOAP message to determine which stage of message processing is in effect (using the Stage property) and then perform the appropriate processing for that stage.
For example, a SOAP extension that is applied to a Web service client could gain access to the SOAP request message at the AfterSerialize stage. To gain access to the SOAP response message, the extension would wait for the BeforeDeserialize stage to occur.
In addition to implementing the SoapExtension class, you must also derive a class from the SoapExtensionAttribute base class. You use this class to create and apply a custom SOAP extension attribute to a method. When the custom extension attribute is added to a Web service method or a proxy class method, the associated extension is invoked at the appropriate time.
Handling SOAP exceptions
SOAP defines a mechanism for Web services to return a SOAP exception message in the face of a failed method call.Handling SOAP exceptions within .NET applications (including ASP.NET applications) is a simple, straightforward process.
The .NET Framework implements a class named SoapException (contained within the System.Web.Services.protocols namespace). The ASP.NET runtime converts SOAP exceptions into instances of the .NET SoapException class. This means that you can use try . . . catch blocks within your calls to Web service methods to catch SOAP exceptions.
Microsoft SOAP Toolkit
As you might expect, it is entirely possible to create and consume Web services without the infrastructure and services provided by the .NET Framework and Visual Studio .NET (although it is much easier to do so with their support). Because Web services are based on XML, HTTP, and SOAP, all we need to create or consume Web services are implementations of these technologies. This is precisely what Microsoft has done with the Microsoft SOAP toolkit.
The Microsoft SOAP toolkit supplies the technologies and tools needed to build and deploy Web services using Visual Studio 6.0 as the development environment along with the familiar COM programming model. In addition to building Web services that can run on Windows NT 4.0 SP6 and Windows 2000, you can build Web service consumers that will run on Windows 98, Windows ME, Windows NT 4.0 SP6, or Windows 2000 SP1.
Toolkit features
The toolkit contains both client- and server-side COM components as well as development tools that enable you to build or consume Web services using Visual Studio 6.0 as the development environment. The following are the technologies and tools included in the SOAP toolkit:
A server-side component that maps Web service requests to COM object method calls described by WSDL and Web Service Meta Language (WSML) documents
A client-side component that enables a consumer to call Web services described by a WSDL document
Components that generate, transport, and process SOAP messages § A WSDL/WSML document -generator tool
A Visual Basic Add-in that simplifies the processing of XML documents contained in SOAP messages § Additional APIs, utilities, and sample applications that illustrate how to use the SOAP Toolkit to build Web service and consumer applications It is worth noting here that Web service consumers created with the SOAP toolkit can invoke any Web service, whether it is based on the SOAP toolkit, ASP.NET, or some other Web service implementation. Likewise, Web services created with the SOAP toolkit can be invoked by any Web service client, regardless of implementation.
This illustrates one of the most powerful features of the Web services model that we have discussed previously: implementation independence. The way in which a Web service or Web service consumer is implemented is unimportant so long as they can communicate via XML, HTTP, and SOAP and implement the standards in an equivalent manner.
Creating a Web service
To enable Web service capabilities on the server, you must first and foremost be able to listen for Web service requests (in other words, SOAP messages) that are delivered to the server. This means that the Web server must be configured to listen for and process Web service request messages.
The SOAP Toolkit provides two choices for providing a SOAP listener for the Internet Information Server (IIS) Web server: an Internet Server API (ISAPI) listener and an Active Server Pages (ASP) listener. Your choice of which listener to use depends on the following:
In most cases, you can choose the ISAPI listener. The advantages of the ISAPI listener are that it is faster than the ASP listener and does not require you to implement any code. You simply need to supply the WSDL and WSML files that describe the Web service and the mappings to COM server methods. The disadvantage of the ISAPI listener lies in the fact that you have no control over the invocation of Web service methods (this is done automatically).
If you need to parse or validate input arguments, perform security checks, or execute similar actions on an incoming request, you must use the ASP listener. The advantage of the ASP listener is that you can perform special message processing on the server before invoking the Web service method.
The drawbacks of the ASP listener are that it is slower than the ISAPI listener and you must implement custom code in an ASP page to invoke the Web service methods. After making your choice, you must edit the WSDL document to specify the appropriate URL of the Web service endpoint. For the ASP listener, you should specify the URL to the ASP file. To use the ISAPI listener, you specify the URL to the WSDL file.
If you are using the ISAPI listener, Web service message processing is automatic. When an incoming SOAP request is detected, the ISAPI listener is invoked to handle the message. The ISAPI listener loads the WSDL and WSML files, executes the request, and returns the results in a response message. In this scenario, you only need provide the WSDL and WSML files.
The SOAPServer component enables Web service request messages to call methods on COM components. The component exposes several properties and methods that permit an ASP page to pass a Web service request to the component for execution (via the request stream) and supply the results to the caller (via the response stream). Using this component, the ASP page does not have to understand how to process SOAP messages.
To use the SOAPServer component, you specify the WSDL and WSML documents as input arguments to the initialization method. This allows the component to create the mappings between Web service requests and COM method calls. After you have initialized the SOAPServer object, you can call its invoke method, passing the ASP input stream and output stream as arguments to the method. When you call the invoke method on the SOAPServer object, the following steps occur:
1. The SOAPServer object deserializes the SOAP request message supplied to it via the invoke method.
2. The request is then examined to locate the COM component and method to be called from the WSDL and WSML documents that were loaded when the SOAPServer object was initialized.
3. An instance of the identified COM object is created and the 0appropriate method is called using the arguments obtained from the request message.
4. The result is obtained from the method call and serialized into a SOAP response message.
5. The SOAP response message is returned to the caller via an output argument of the invoke method.
Creating a Web service consumer
The SOAPClient COM component enables Web service consumers to call Web services. This component leverages the features of the SOAP Toolkit to provide properties and methods that a Web service consumer can use to call Web service methods without having to deal with SOAP messages directly. In this way, the SOAPClient component acts as a proxy object for the Web service.
To use the SOAPClient component, you must have access to the WSDL document that describes the Web service. When you call the initialization method on the component, you pass in the location of the WSDL document. This causes all the operations defined in the WSDL document to be dynamically bound to the SOAPClient component. Once this has been completed, you can invoke the methods defined in the WSDL document via the SOAPClient object.
When you invoke a Web service method bound to the SOAPClient object, the following steps occur:
1. The SOAPClient object serializes the method call into a SOAP request message and delivers it to the server.
2. The server deserializes the SOAP request message and processes the request.
3. The server serializes the result into a SOAP response message and delivers it to the client.
4. The SOAPClient object deserializes the SOAP response message and returns the result to the caller.
5. The SOAPClient object also exposes SOAP fault properties so that you can examine error information in case a method call fails for some reason.
To summarize, the SOAPClient object makes it easy to consume Web services in a COM-like manner. The consumer need only supply the WSDL document that describes the Web service to the SOAPClient object in order to call the operations exposed by the Web service.
The SOAPClient object takes care of translating COM method calls into SOAP requests and then translating the SOAP response into a COM method return value. If an error occurs in the method call, the SOAPClient object exposes properties that allow a consumer to gain access to the SOAP fault information that is returned.
WSDL/WSML generator tool
The WSDL/WSML generator tool is used to automatically generate WSDL and WSML documents from COM type libraries. The graphical version of the tool (named Wsdlgen.exe) walks you through the process of generating these documents. It will request the type of listener you wish to use, the location of the COM type library, which methods you wish to expose from the available interfaces in the type library, the folder in which to write the WSDL and WSML documents, and a few other details.
After answering these questions, the tool will generate the files for you. If you wish to script the generation of these files, a command-line version of the tool is also supplied, named Wsdlstb.exe. You can use the /? switch on the command line to get help information on valid command parameters and switches. The bottom line here is that the WSDL/WSML generator tool can be a great timesaver when preparing your COM components for accessibility as Web services.
SOAP trace utility
One final useful utility to point out that ships with the Microsoft SOAP Toolkit is the SOAP trace utility. Using this graphical utility, you can view SOAP request and response messages transported over HTTP between a Web service and Web service consumer. The trace utility can be configured to run either on the client or the server. To run the trace utility on the server, you must make a small modification to the WSDL document that specifies the URL to the SOAP endpoint.
Once this has been done, you can start the trace utility to begin a tracing session. To run the trace utility on the client, you must copy the WSDL document to the client machine, make a similar modification to the WSDL document, and start the trace utility. After starting the utility, you need to specify the name of the host where the actual Web service is running. After doing so, you will be able to begin a tracing session.
RELATED POST
CREATING ASSEMBLIES WITH ASP.NET
BUILDING HANDLERS IN ASP.NET
INTERFACES AND CLASSES CREATION IN ASP.NET
CACHING IN ASP.NET
CACHING IN ASP.NET PART TWO
WIRE LESS APPLICATION WITH ASP.NET
SECURITY IN ASP.NET PART ONE
SECURITY IN ASP.NET PART TWO
LOCALIZING ASP.NET APPLICATIONS
DEPLOYING ASP.NET APPLICATIONS
ASP.NET CONFIGURATION SYSTEM
WEB SERVICES IN ASP.NET
WEB SERVICES PART TWO
WEB SERVICE INFRASTRUCTURE
WEB SERVICE INFRASTRUCTURE PART TWO
EXCHANGING MESSAGES IN ASP.NET
MICROSOFT HAIL STORM
SOAP AND DOT NET PART ONE
SOAP AND DOT NET PART TWO
No comments:
Post a Comment