Interface Inheritance As I mentioned at the beginning of the chapter, the Securities Web service is intended to be consumed by portals such as MSN and Yahoo! Come to find out that other brokerage companies have approached MSN as well. In an effort to accommodate the numerous requests, MSN has defined a standard interface in which it will communicate with the various online brokerage firms. Interface-based programming has been popularized by technologies such as COM, CORBA, and Java. Within the .NET platform, interfaces continue to play an important role. They facilitate treating different objects in a polymorphic fashion without the overhead and complexity of implementation inheritance.

Sample Chapter from the book: Building XML Web Services for the Microsoft® .NET Platform

In the case of MSN, it would not be ideal to write custom client code to interface with every single securities-related Web service. Instead, MSN can define a standard interface that all the securities-related Web services must comply with.

The first task for MSN is to create an abstract interface for the Securities Web service. As you learned in the previous chapter, a Web service interface is defined within a WSDL document. A transport-specific interface definition is represented by a binding definition, while a transport-agnostic interface definition is represented by a port type definition.

The easiest way to generate a WSDL document that describes the interface is to have ASP.NET automatically generate the WSDL for you. The following example creates a Web service that defines an abstract class:

<%@ WebService Language="c#" Class="MSN.Securities" %>
 
using System;
using System.Web.Services;
using System.Web.Services.Protocols;
 
namespace MSN
{
    [WebService(Namespace="http://msn.com/Securities")]
    [SoapRpcService]
    public abstract class Securities : WebService
    {
        [WebMethod]
        public abstract double InstantQuote(string symbol);
    }
}

The preceding code defines an interface for the Securities Web service. Unfortunately, the abstract keyword is not recognized by the ASP.NET platform, so the code will define a full WSDL document, not just the interfaces.

One way to overcome this problem is to save the WSDL that is generated by the ASP.NET runtime with its service definitions removed. Without the service definitions, a client will have no way of locating the endpoints, which makes the interface definitions abstract. Here is the WSDL document with its service definitions removed:

<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns:s="http://www.w3.org/2001/ XMLSchema" 
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/ " 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:tns="http://msn.com/Securities" 
targetNamespace="http://msn.com/Securities" 
xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types />
  <message name="InstantQuoteSoapIn">
    <part name="symbol" type="s:string" />
    <part name="count" type="s:int" />
  </message>
  <message name="InstantQuoteSoapOut">
    <part name="InstantQuoteResult" type="s:double" />
  </message>
  <portType name="SecuritiesSoap">
    <operation name="InstantQuote">
      <input message="tns:InstantQuoteSoapIn" />
      <output message="tns:InstantQuoteSoapOut" />
    </operation>
  </portType>
  <binding name="SecuritiesSoap" type="tns:SecuritiesSo ap">
    <soap:binding 
    transport="http://schemas.xmlsoap.org/soap/ http" style="rpc" />
    <operation name="InstantQuote">
      <soap:operation 
      soapAction="http://msn.com/Securities/ InstantQuote" style="rpc" />
      <input>
        <soap:body use="encoded" namespace="http:// msn.com/Securities" 
        encodingStyle="http://schemas.xmlsoap.org/soap/ encoding/" />
      </input>
      <output>
        <soap:body use="encoded" namespace="http:// msn.com/Securities" 
        encodingStyle="http://schemas.xmlsoap.org/soap/ encoding/" />
      </output>
    </operation>
  </binding>
</definitions>

In addition to removing the service definitions, I also remove any definitions not directly related to the SOAP binding. I will readdress this issue in a moment when I discuss some of the limitations of the ASP.NET support for interface inheritance.

A Web service can inherit an interface by referencing a port type or a binding that is defined by another Web service. ASP.NET does not provide a mechanism for providing protocol-agnostic interface inheritance. For example, you cannot inherit an interface from a Web service that is exposed only via SMTP. To do this, you would have to hand-roll the WSDL used to describe the service so that it references the port type defined within another namespace. You would also need to disable the WSDL document that is automatically generated by ASP.NET. (See the "Web Service Documentation" section earlier in the chapter.)

ASP.NET does provide a mechanism for facilitating transport-specific interface inheritance. You use the WebServiceBinding attribute to reference a binding defined within another namespace. You use the Binding property of the SoapDocumentMethod or SoapRpcMethod attribute to reference the binding definition referenced by the WebServiceBinding attribute.

Next I modify the definition of the Securities Web service to inherit the interface defined within the MSN namespace. I do so by referencing the SecuritiesSoap binding definition. Suppose the preceding WSDL document is located at http:// msn.com/Securities.wsdl. The following code defines the Securities Web service provided by www.woodgrovebank.com:

using System;
using System.Web.Services;
using System.Web.Services.Protocols;
 
namespace BrokerageFirm
{
    [SoapRpcService]
    [WebServiceBinding("SecuritiesSoap", 
    "http://msn.com/Securities", "http://msn.com/Securities.wsdl")]
    public class Securities : WebService
    {

I reference the SecuritiesSoap binding definition using the WebServiceBinding attribute. The three parameters I pass to the attribute’s constructor are the name of the referenced binding definition, the namespace containing the definition, and the location of the WSDL document containing the definition.

If the binding definition is referenced within the Web method, the ASP.NET runtime will add a reference to the WSDL namespace that contains the binding. The ASP.NET runtime will also add an import element to the autogenerated WSDL document. Finally, the ASP.NET runtime will add a port within the service definition that is associated with the referenced binding definition, as shown here:

      [WebMethod]
        [SoapRpcMethod(Binding="SecuritiesSoap")]
        public double InstantQuote(string symbol)
        {
            double price = 0;
 
            // Implementation...
 
            return price;
        }
    }
}

I use the Binding property of SoapRpcMethod to associate the Web method with the binding definition. The value of the binding property must match the name assigned to a WebServiceBinding attribute defined at the class level; otherwise, a run-time exception will occur.

Using the WebServiceBinding attribute to facilitate interface inheritance has some limitations. First, you can reference only SOAP binding definitions. There is also no tool support for referencing external binding definitions. Developers must take it upon themselves to create Web methods that match the referenced binding definition. Finally, there is no validation either at compile time or at run time to ensure that the Web service implements all the methods exposed by the inherited interface.

To ensure that the Web service supports all the methods of the inherited interface, you can use the WSDL.exe tool to generate an abstract class representing the Web service. You can then add the resulting code to your project and derive from the abstract class instead of the WebService class. The following example creates the BaseSecurities.cs file that contains an abstract class definition for the base Web service:

wsdl /server /out:BaseSecurities.cs http://msn.com/ Securities.wsdl

Once BaseSecurities.cs has been created and added to my project, I can derive the Web service as follows:

using System;
using System.Web.Services;
using System.Web.Services.Protocols;
 
namespace BrokerageFirm
{
    [WebService(Description="This Web service provides services related to securities.")]
    [SoapRpcService]
    [WebServiceBinding("SecuritiesSoap", "http://msn.com/ Securities", 
    "http://msn.com/Securities.wsdl")]
    public class Securities : MSN.Securities
    {
 
        // Implementation...
 
    }
}

If the Securities class does not implement all the abstract methods defined within the MSN.Securities class, I will receive a compiler error.

Managing State

Furthermore, state is usually scoped to the application. Application configuration parameters such as database connection strings are an example. Defining a Web application and providing a mechanism to store state that is scoped to the application is an implementation detail of the Web development platform.

The ASP development platform defines a Web application and provides a service for maintaining both session and application state. However, the ASP state management services have some serious limitations. ASP.NET provides a much- improved state management service. The service can be leveraged by Web Forms as well as Web services.

Session State

Maintaining state on behalf of a user involves associating multiple HTTP requests with one user session. ASP.NET uses a unique identifier that is passed by the client to identify the session. This identifier can be saved in a cookie maintained by the client or embedded within the URL of the request. Even though Web Forms supports both, Web services support only cookies.

If the proxy used by the client to access the Web service supports cookies, the session ID will automatically be sent with every request. ASP.NET uses a transient cookie to store the session ID. By definition, the cookie is intended to be maintained only for the life of the proxy used to access the Web service.

Because cookies are HTTP-specific, the session state mechanism is bound to the HTTP protocol. A transport protocol–agnostic way of passing the session ID would be to place the session ID within the header of the SOAP message. But this is not supported by ASP.NET, so you would have to roll your own state management system to support this scenario.

Once the session is identified, you need a repository to store the data associated with the session. The following three scenarios are supported, each with its advantages and disadvantages:

• In Process This is the fastest scenario because calls to read/write session state will be handled in process. However, this is also the least robust configuration. If the ASP.NET worker process (aspnet_wp.exe) is terminated for any reason, all session state being maintained for the application will be lost. This configuration is ideal for Web services hosted on a single machine that need the most performant way of accessing state.
• Out of Process In this configuration, session state is maintained in a separate process that can even reside on another machine. One advantage of this configuration is that if the ASP.NET worker process is terminated, the session state for the application will still be preserved. Because session state is maintained in memory, if the session state server (aspnet_state.exe) is terminated, all session state will be lost. Another advantage of this configuration is that state can be shared across multiple Web servers. All Web servers within the Web farm can be configured to point to the same state management process. This configuration is ideal for Web services hosted in a Web farm where the loss of state information should be avoided but is not critical.
• SQL Server This is the most robust and scalable of the three configurations. Session state is maintained within a SQL Server database. The session state service maintains a set of tables in which the session state data is serialized into a binary blob. This is the ideal configuration for Web services hosted in a Web farm if you can afford to purchase and maintain SQL Server. This configuration is mandatory if you need to ensure that session state is never lost.

Of the three configurations, In Process is the only one available via the .NET Framework. You must purchase either the Professional or Enterprise Edition of ASP.NET to obtain the Out of Process and SQL Server configuration options.

To use the ASP.NET session state service, you must add the module named SessionStateModule to the application. The default machine-wide configuration file (C:\WINNT\Microsoft.NET\Framework\version\CONFIG\machine.config) adds this module.

Once you add SessionStateModule, you can configure the session state service within the sessionState element of the machine.config or web.config configuration file. Table 6-6 lists the attributes that you can set within the sessionState element.

Table 6-6 Attributes of the sessionState Element

Once you have the session state service properly configured, session state is enabled on a per-Web-method basis. You can enable session state for a particular Web method by setting the EnableSession property of the WebMethod attribute to true.

Regardless of which configuration you choose, the API for reading/writing session state is exactly the same. The class that contains the Web method should inherit from the WebService class. The WebService class exposes the Session property, which returns an instance of the HttpSessionState class, otherwise known as the session object.

The session object is used to maintain a collection of information related to the user’s session. Items can be added to and retrieved from the collection via an int or string indexer.

The following example expands the Securities Web service to use session state. The SetCurrency Web method allows the client to select a particular currency. Future calls to InstantQuote will return the price of the security using the selected currency.

using System;
using System.Web.Services;
 
namespace BrokerageFirm
{
    [SoapRpcService]
    public class Securities : WebService
    {
        public Securities()
        {
            //  Set the default value of the target currency.
            if(this.Session["TargetCurrency"] == null)
            {
                this.Session["TargetCurrency"] = CurrencyType.US_DOLLAR;
            }
        }
 
        public enum CurrencyType
        {
            US_DOLLAR,
            UK_POUND,
            GE_DEUTSCHMARK
        }
 
        [WebMethod(true)]
        public void SetCurrency(CurrencyType targetCurrency)
        {
            this.Session["TargetCurrency"] = targetCurrency;
        }
 
        [WebMethod(true)]
        public double InstantQuote(string symbol)
        {
 
            // Implementation...
 
            return Convert(price, 
            (CurrencyType)this.Session["TargetCurrency"]);
        }
 
        private double Convert(double usPrice, Currency Type targetCurrency)
        {
            double targetCurrencyPrice = usPrice;
 
            // Implementation ...
 
            return targetCurrencyPrice;
        }
    }
}

The SetCurrency method persists the client’s currency preference within the session. The InstantQuote method then retrieves the currency preference from the client’s session and converts the price of the security appropriately.

As shown in the preceding example, you can use the string indexer to both set and retrieve values from the session object. However, you can use the int indexer only to retrieve values contained within the session object. You can also use the Add method to add items to the collection managed by the session object.

Because the client might not have selected a target currency, a default value is set within the Securities object constructor. Even with session state enabled, ASP.NET will still create a new instance of the Securities object for every request. The constructor will initialize the value of the target currency only if the value is null.

A potential issue can arise in the preceding example if the client does not support cookies. By default, ASP.NET clients do not support cookies. In the example, a client that does not support cookies will always have the price of a stock returned in U.S. dollars. A better design would be to extend the method signature of InstantQuote to accept the symbol of the security as well as the targeted currency. This would also eliminate a network round-trip because the client would no longer need to call the SetCurrency Web method.

The session object also supports the ICollection and IEnumerable interfaces, which allow polymorphic enumeration through the items within the collection. The following example uses the IEnumerable interface to iterate through the collection:

[WebMethod(true)]
public override string ToString()
{
    StringBuilder sb = new StringBuilder();
    foreach(string index in this.Session)
    {
        sb.AppendFormat("{0} = {1}\n", index, 
        this.Session[index].ToString());
    }
 
    return sb.ToString();
}

This method declaration overrides the Object.ToString method and exposes it as a Web method. The implementation of the Web method enumerates through the session object via the IEnumerable interface by using the foreach keyword. Each name/ value pair stored within the session object is appended to an instance of the StringBuilder class. Finally the resulting string is returned from the Web method.

Application State

Classes that derive from the WebService class expose the Application property. This property retrieves an instance of the HttpApplicationState object containing state that is global to the Web application. The HttpApplicationState class derives from the NameObjectCollectionBase class. Because the implementation of the NameObjectCollectionBase class creates a hash table, retrieving a particular value from the application object is very efficient.

Let’s say I want to implement a counter to record the number of times the Web service has been accessed because the application has been started. I could add the following code to the InstantQuote method just before I return the price to the customer:

// Record the access to the Web service.
this.Application["HitCounter"] = (int)this.Application
["HitCounter"] + 1;

Unfortunately, the code has two problems. First, the HitCounter application variable is never initialized. Every time the above code is executed, it will generate an exception. Second, because multiple clients can potentially increment the HitCounter application variable simultaneously, a potential race condition might occur. Let’s address these issues one at a time.

ASP.NET provides a framework for handling application startup code within a Web service. Every Web application can contain a global.asax file. Within the file, you can implement code that is executed when certain predefined events occur, such as application startup/shutdown and session startup/shutdown. Application startup is an ideal point to initialize application variables. The following code initializes the HitCounter application variable during the application start event within the Global.asax page:

using System;
using System.Web;
 
namespace BrokerageFirm 
{
    public class Global : HttpApplication
    {
        protected void Application_Start(Object sender,  EventArgs e)
        {
            // Initialize the hit counter to 0.
            this.Application["HitCounter"] = (int)0;
        }
    }
}

In the Application_Start method, I initialize the HitCounter application variable to zero. I also explicitly cast it to an int to avoid any ambiguity. Because the ASP.NET runtime executes the Application_Start method once during the life of the application, you do not have to worry about concurrency issues.

However, the InstantQuote method can be called by multiple clients simultaneously. Therefore, you must avoid potential race conditions when you update the data. Even though incrementing the HitCounter application variable is represented by a single line of C# code, the single line will be translated into multiple machine instructions when it is compiled. Here is the resulting IL code:

  IL_0074:  ldarg.0
  IL_0075:  call       instance class 
                       [System.Web]System.Web.HttpApplicationState 
                       [System.Web.Services]System.
                       Web.Services.WebService::get_App lication()
  IL_007a:  ldstr      "HitCounter"
  IL_007f:  ldarg.0
  IL_0080:  call       instance class 
                       [System.Web]System.Web.HttpAppli cationState 
                       [System.Web.Services]System.Web. Services.
                       WebService::get_Application()
  IL_0085:  ldstr      "HitCounter"
  IL_008a:  callvirt   instance object 
                       [System.Web]System.Web.HttpAppli cationState::
                       get_Item(string)
  IL_008f:  unbox      [mscorlib]System.Int32
  IL_0094:  ldind.i4
  IL_0095:  ldc.i4.1
  IL_0096:  add
  IL_0097:  box        [mscorlib]System.Int32
  IL_009c:  callvirt   instance void 
                       [System.Web]System.Web.HttpAppli cationState::
                       set_Item(string,object)
  IL_00a1:  ldarg.0
  IL_00a2:  call       instance class 
                       [System.Web]System.Web.HttpAppli cationState 
                       [System.Web.Services]System.Web. Services.
                       WebService::get_Application()

The single line of C# code translates to 15 lines of IL, and then the IL is compiled to numerous machine codes before it is executed. Because the code can be executed simultaneously by two or more clients, this will lead to unpredictable results.

As an example of the problems that can occur if two clients (A and B) attempt to run the same code simultaneously, suppose that the HitCounter application variable was initially set to 1 and client A executes the above IL to increment the value to 2. IL_008a obtains the initial value of 1 for HitCounter. IL_009c sets HitCounter to a new value of 2. Suppose also that client B updates the value of HitCounter to 2 somewhere between IL_008a and IL_009c. Because client A will be incrementing the previously retrieved value of 1, HitCounter will be incorrectly set to 2 instead of the correct value of 3.

The application object provides a locking mechanism to ensure that writes made to the data are performed serially, thereby avoiding race conditions such as the one described in the preceding paragraph. Operations that require serialized access to the data can be performed between the Lock and Unlock methods provided by the application object. The following example properly updates the HitCounter application variable each time the InstantQuote Web method is invoked:

using System;
using System.Web.Services;
 
namespace BrokerageFirm
{
    [SoapRpcService]
    public class Securities : WebService
    {
        public enum CurrencyType
        {
            US_DOLLARS,
            UK_POUNDS,
            GE_DEUTSCHMARKS
        }
 
        [WebMethod]
        public double InstantQuote(string symbol, 
        CurrencyType targetCurrency)
        {
            double price = 0;
 
            // Implementation...
 
            // Record the access to the Web service.
            this.Application.Lock();
            this.Application["HitCounter"] = 
            (int)this.Application["HitCounter"] + 1;
            this.Application["LastSymbol"] = symbol;
 
            return Convert(price, targetCurrency);
        }
 
        private double Convert(double usPrice, 
        CurrencyType targetCurrency)
        {
            double targetCurrencyPrice = usPrice;
 
            // Implementation...
 
            return targetCurrencyPrice;
        }
    }
}

By locking the application object before attempting to increment it, you ensure that you will have exclusive access to the lock on the application object. Because all calls to Unlock will be blocked, you should call the Unlock method as quickly as possible to avoid hindering throughput. Note, however, that even when you have locked the application object, you do not have exclusive access to the data. Therefore, to avoid race conditions from being introduced into your application, you must ensure that a common locking scheme is used throughout your application.

You should also look for opportunities where application scoped data can be updated without locking the application object. Notice that I also updated the LastSymbol application variable with the last symbol that was successfully processed by the Web method. In this case, I was not concerned about race conditions because by definition the last security quoted would have been processed by the Web method that last updated the LastSymbol application variable.

If both the LastSymbol and the LastPrice application variables needed to be set, I would have updated both of them before unlocking the application object. This would avoid a situation in which client A was the last one to update LastPrice and client B was the last one to update LastSymbol.

Before moving to the next topic, I want to offer a word of caution about the use of the Lock and Unlock methods. You should ensure that every time a Web method calls Lock, Unlock is called as soon as possible; otherwise, you run the risk of blocking other requests that are currently being processed by the Web service. A good design pattern is to call the Unlock method within the finally section of a try/ catch block. Here is an updated example of the Purchase method:

// Record the access to the Web service.
try
{
    this.Application.Lock();
    this.Application["HitCounter"]= 
    (int)this.Application["HitCounter"] + 1;
}
catch(Exception e)
{
    // Handle exception ...
}
finally
{
    this.Application.UnLock();
}
 
// Significant processing to quote the price...
 
this.Application["LastSymbol"] = symbol;

Because the Unlock method call was placed within the finally section of the try/catch block, Unlock will be called even if the code to update the HitCounter application variable fails (for example, when an OverflowException is thrown as a result of the addition). This ensures that other ASP.NET worker threads will not be needlessly blocking on a call to Lock.

What if you forget to unlock the application object before your Web method returns? A mistake such as this could have a detrimental effect on your application. The next time you try to obtain the lock for the application object, the call to Unlock will deadlock. Fortunately, the ASP.NET runtime prevents this from happening. When a Web method returns, the ASP.NET runtime ensures that the lock obtained on the application object is freed.

One of the biggest problems with using the application object to implement a hit counter is that it is the developer’s responsibility to ensure that the application object is locked before the counter is incremented. A better alternative would be to leverage static properties. As with the application object, static properties are scoped to the application. Unlike the application object, you can associate behavior with static properties. For example, consider the following HitCounter class.

public class HitCounter
{
    private static int count = 0;
    private static object countLock = new object();
 
    private HitCounter() {}
 
    public static int Count
    {
        get { return count; }
    }
 
    public static void Increment()
    {
        lock(countLock)
        {
            count++;
        }
    }
}

Instead of storing the hit counter within the application object, I define a class that implements a property and a method for accessing and manipulating the hit counter. Because the field containing the current count is declared as private, developers that use the class cannot increment it directly. Instead, the HitCounter class exposes a public read-only static property to access the current count and a public static method to increment the hit counter. The Increment method uses the lock keyword to ensure that there is no potential for a race condition while incrementing the counter.

Defining and Processing SOAP Headers

You can define a new header by deriving from the SoapHeader class. You can associate the new header with a particular endpoint within the Web service by using the SoapHeader attribute. Table 6-7 lists the properties exposed by the SoapHeader class.

Table 6-7 Properties of the SoapHeader Class

By default, the name of the class derived from SoapHeader will become the name of the root header element, and any public fields or properties exposed by the class will define elements within the header.

As I mentioned earlier in the chapter, price quotes from other services on the Web are often time-delayed and can be more than 20 minutes old. Price quotes obtained using the InstantQuote Web method are not subject to these delays. Because the InstantQuote Web method obtains the price that a particular stock is currently trading at on the exchange’s floor, I feel that I can charge the client $1.50 for each quote. I will therefore require every SOAP request made to the InstantQuote Web method to be accompanied by the Payment SOAP header, which will contain the client’s credit card information. This information will be used to pay the $1.50 transaction fee.

SOAP headers are defined by classes derived from the SoapHeader class. Elements within the header are defined by public fields or read/writable properties. Here is the definition of the Payment header:

[XmlRoot("Payment")]
public class SoapPaymentHeader : SoapHeader
{
    private string nameOnCard;
    private string creditCardNumber;
    private CardType creditCardType;
    private DateTime expirationDate;
 
    public enum CardType
    {
        VISA,
        MC,
        AMX,
        DISCOVER
    }
 
    public string NameOnCard 
    {
        get { return nameOnCard; }
        set { nameOnCard = value; }
    }
 
    public string CreditCardNumber 
    {
        get { return creditCardNumber; }
        set { creditCardNumber = value; }
    }
 
    public CardType CreditCardType 
    {
        get { return creditCardType; }
        set { creditCardType = value; }
    }
 
    public DateTime ExpirationDate 
    {
        get { return expirationDate; }
        set { expirationDate = value; }
    }
}

The preceding class definition defines a SOAP header named Payment with four child elements: nameOnCard, creditCardNumber, creditCardType, and expirationDate. The XmlRoot attribute is used to instruct the XML Serializer to name the header element Payment instead of the class name. I will cover the XML Serializer in Chapter 7.

Once the payment has been received and the Web method has been processed, I want to send a header containing a confirmation of the purchase back to the client. SOAP headers sent from the server to the client are defined in the same manner. The following code defines a header containing the amount that was charged as well as the reference number of the credit card transaction:

[XmlRoot("Receipt")]
public class SoapReceiptHeader : SoapHeader
{
    private double amount;
    private int referenceNumber;
 
    public double Amount 
    {
        get { return amount; }
        set { amount = value; }
    }
 
    public int ReferenceNumber 
    {
        get { return referenceNumber; }
        set { referenceNumber = value; }
    }
}

Once you define the headers, the next step is to associate them with the InstantQuote Web method. The SoapHeader attribute is used to associate a SOAP header with a Web method.

A public member variable is added to the WebService class to hold an instance of the class derived from the SoapHeader class. The name of the member variable is then communicated to the ASP.NET runtime via the SoapHeader attribute. Here is the Securities class definition:

  public class Securities : WebService
    {
 
        public PaymentHeader paymentHeader;
        public ReceiptHeader receiptHeader = new ReceiptHeader();
 
        public enum CurrencyType
        {
            US_DOLLARS,
            UK_POUNDS,
            GE_DEUTSCHMARKS
        }
 
        [WebMethod]
        [SoapHeader("paymentHeader", 
        Direction=SoapHeaderDirection.In, Required=true)]
        [SoapHeader("receiptHeader", 
        Direction=SoapHeaderDirection.Out, Required=true)]
        public double InstantQuote(string symbol, CurrencyType targetCurrency)
        {
            double price = 0;
 
            // Implementation ...
 
            return Convert(price, targetCurrency);
        }
 
        private double Convert(double usPrice, CurrencyType 
        targetCurrency)
        {
            double targetCurrencyPrice = usPrice;
 
            // Implementation...
 
            return targetCurrencyPrice;
        }
    }

I create two member variables to hold the data contained in the Payment and the Receipt SOAP headers. I create an instance of the SoapReceiptHeader class because the Receipt header will be passed to the client. I do not create an instance of the SoapPaymentHeader class because the ASP.NET runtime is responsible for creating this object and populating its properties with the data contained within the Payment header received from the client.

Next I add two SoapHeader attributes to declare that the headers should formally be described as part of the Web method. The constructor of the SoapHeader attribute takes a string that contains the name of the public member variable that should be associated with the SOAP header.

I also set two optional properties, Direction and Required. The Direction property indicates whether the client or the server is supposed to send the header. The Required property indicates whether the property must appear within the SOAP message. Let’s discuss each property in detail.

The Direction property indicates whether the header is received from the client, sent to the client, or both. The Payment header is received from the client, and the Receipt header is sent to the client, so I set the Direction property to SoapHeaderDirection.In and SoapHeaderDirection.Out, respectively. If a SOAP header is received from the client and then sent back to the client, the value of the Direction property should be set to SoapHeaderDirection.InOut.

The Required property indicates whether the header must appear within the SOAP message to be considered valid by the Web service. If the Required property is not set within the attribute tag, the default value is true. Inbound headers marked as required must be included in the request message; otherwise, a SoapException will be thrown by the ASP.NET runtime.

Because a Payment header must be included in every request and a matching Receipt header must be included in every response, I set the Required property to true for both SOAP headers. The Required property has no bearing on whether the header will be processed or even understood by the recipient of the message. For example, the Receipt header must always be passed back to the client, but the client is not required to process the header.

Now that I have associated the Payment and Receipt headers with the Web method, the next task is to process the Payment headers. The following code uses the information within the Payment header to bill the client’s credit card using an arbitrary credit card processing component:

public class Securities : WebService
{
 
    public SoapPaymentHeader paymentHeader;
    public SoapReceiptHeader receiptHeader = new SoapRe ceiptHeader();
 
    public enum CurrencyType
    {
        US_DOLLARS,
        UK_POUNDS,
        GE_DEUTSCHMARKS
    }
 
    [WebMethod]
    [SoapHeader("payment", Direction=SoapHeaderDirection.In, 
    Required=true)]
    [SoapHeader("receipt", Direction=SoapHeaderDirection.Out, 
    Required=true)]
    public double InstantQuote(string symbol, CurrencyType 
    targetCurrency)
    {
        // Declare and initialize variables.
        double    price = 0;
        int       merchantNumber = 123456789;
        double    fee = 1.50;
        int       referenceNumber = 0;
 
        // Apply the fee to the client's credit card.
        CreditCardProcessor creditCardProcessor = 
        new CreditCardProcessor(merchantNumber);
        referenceNumber = 
        creditCardProcessor.Bill(fee, paymentHeader);
 
        // Verify that the credit card was processed.
        if(referenceNumber > 0)
        {
            // Set the return header information.
            receiptHeader.ReferenceNumber = referenceNumber;
            receiptHeader.Amount = fee;
        }
        else
        {
            throw new SoapException("The Payment header was either 
            missing or contained invalid information.", 
            SoapException.ClientFaultCode);
        }
 
        // Implementation...
 
        return Convert(price, targetCurrency);
    }
}

The preceding code uses the information within the Payment header to charge the required fee to the client’s credit card. If the credit card is successfully processed, the Receipt header will be populated with the reference number of the transaction as well as the amount that was charged to the card. If the credit card is not successfully processed, a SoapException will be raised. Because the exception is a result of insufficient information sent from the client, the fault code is set to Client.

The current implementation has one problem related to processing headers. In Chapter 3, I said that the client has the ability to send additional headers other than what was expected. The client can also set the mustUnderstand attribute to true on these additional headers. I will discuss how to process headers you were not expecting shortly. But let’s first discuss setting and analyzing the mustUnderstand attribute for a particular SOAP header.

The MustUnderstand property exposed by the SoapHeader class is fundamentally different from the Required property set by the SoapHeader attribute (which I discussed earlier). The Required property specifies whether a header must be included within a message. If the header resides within a message, the MustUnderstand property is used to specify whether the recipient of the message must understand and process the header. Let’s discuss these two properties in detail.

The Required property specifies whether the header must be included within the message exchanged between the client and the server for a particular Web method. Because this property is specific to the interface of a Web service, changes to it are reflected in the WSDL document. If the Required property is set to true, the required attribute within the header element defined by the SOAP binding extensibility elements will be set to true. Finally, if a Web method defines a SOAP header as required, ASP.NET cannot support the HTTP GET/POST bindings.

The MustUnderstand property specifies whether a specific header within a message must be understood and processed by the client. Because this property is specific to a particular exchange between the client and the server, changes to it are reflected in the SOAP message itself. If the MustUnderstand property is set to true, the mustUnderstand attribute within an instance of the header will be set to true.

The DidUnderstand property of an object derived from SoapHeader notifies the ASP.NET runtime to tell the client which headers were processed by the Web method.

The default value of the DidUnderstand property is true for headers formally defined by the Web method, so make sure that there cannot be a code path in which the method returns without processing a header. The client might have set the mustUnderstand attribute to true. If so, this is considered an error if the Web method does not throw a SoapException.

In the case in which a header might not be processed, you might want to set the DidUnderstand property to false at the beginning of the Web method. Once the header is processed, set the DidUnderstand property back to true.

Another option is to include the value of the MustUnderstand property in the decision about whether to process the header. For example, the InstantQuote method sets the Required property of the Payment header to true. However, the InstantQuote method is responsible for processing the header only if the MustUnderstand property is true. Let’s say that if the administrator invokes the InstantQuote Web method, the Payment header should not be processed unless the MustUnderstand property is true, as shown here:

//  Apply the fee to the client's credit card only if the  user is not 
//  the administrator or if the header must be processed.
if(User.Identity != "Administrator" || paymentHeader.MustUnderstand)
{
    CreditCardProcessor creditCardProcessor = 
    new CreditCardProcessor(merchantNumber);
    referenceNumber = creditCardProcessor.Bill(fee, pay ment);
}

I want to discuss one final point about the MustUnderstand and DidUnderstand properties. After the Web method returns, the ASP.NET runtime will determine whether any headers passed by the client containing a mustUnderstand attribute set to true also have their associated DidUnderstand property set to false. If this is the case, the ASP.NET runtime will automatically throw a SoapException. The Web method might have code that attempts to undo actions done on a client’s behalf before throwing the exception. Because this exception is thrown after the Web method has returned, this code will never execute.

Let’s say a client calls the InstantQuote Web method within the context of a transaction. The client passes a Transaction header along with the Payment header and sets its mustUnderstand attribute to true. Because the previous implementation does not check for the presence of a Transaction header, the Web service processes the request, including billing the client’s credit card. After the method returns, the ASP.NET runtime notices that the Transaction header’s DidUnderstand property is set to false and throws an exception. In this case, the client does not receive the quote but will still be billed the $1.50 transaction fee. This scenario would result in one unhappy customer.

There are at least two ways to avoid this adverse side effect. If the affected resources are all managed by a DTC Resource Manager, you can set the TransactionOption property of the WebMethod attribute to Required. Once the ASP.NET runtime throws an exception, the transaction will be aborted and all changes rolled back. If the CreditCardProcessor component can participate in a DTC-controlled distributed transaction, the fee charged to the card will automatically be rolled back.

Another option is to verify that all headers received by the Web service with a mustUnderstand attribute set to true have been processed before the Web method returns. Catching headers that must be understood but cannot be processed by the Web service early on within the Web method can potentially save unnecessary processing cycles. If the Web method does not know how to process one of the headers passed to it, it can take appropriate action before throwing an exception. In the next section, I discuss how to examine the MustUnderstand property of unknown headers.

Processing Unknown Headers

The SoapUnknownHeader class is derived from SoapHeader and can be used to inspect or process headers not formally defined by the Web method. Because the SoapUnknownHeader class is derived from SoapHeader, it exposes properties such as MustUnderstand and DidUnderstand.

An object of type SoapUnknownHeader is loosely typed because the only additional property defined is Element, which is of type XmlElement. The Element property serves as an entry point to the root element of the header. You can use the XML DOM to interrogate the contents of the header.

You can associate the SoapUnknownHeader class with a Web method using the SoapHeader attribute (just as you can with any other class that derives from SoapHeader). If more than one header can be received by the Web method, as is the case with unknown headers, the property associated with the Web method can be an array.

Recall that the previous implementation of the InstantQuote Web method had a flaw. If an unknown header that must be understood by the Web service is received by the client, credit card users will be charged the fee but will receive a SOAP fault automatically generated by the ASP.NET runtime. To solve this problem, the following example obtains a list of unknown headers, iterates through the list, and then throws a SoapException once the first SoapUnknownHeader is encountered that has its MustUnderstand property set to true:

[WebMethod]
[SoapHeader("paymentHeader", Direction=SoapHeaderDirect ion.In, Required=true)]
[SoapHeader("receiptHeader", Direction=SoapHeaderDirect ion.Out, Required=true)]
[SoapHeader("unknownHeaders", Required=false)]
public double InstantQuote(string symbol, CurrencyType  targetCurrency)
{
    // Declare and initialize variables.
    double  price = 0;
    int     merchantNumber = 123456789;
    double  fee = 1.50;
    int     referenceNumber = 0;
 
    //  Check to see whether any unknown headers must be proce ssed.
    foreach(SoapUnknownHeader header in unknownHeaders)
    {
        if(header.MustUnderstand)
        {
            string message = "The " + header.Element.Name + 
            " header could not be processed.";
            throw new SoapException(message, 
            SoapException.MustUnderstandFaultCode);
        }
    }
 
    // The rest of the implementation...
 
}

The Web method checks for unknown headers that must be understood by the client before the credit card is processed. If a header that must be understood cannot be processed, the client will not be charged the fee for using the Web service.

Using SOAP Extensions

SOAP extensions provide a way of creating encapsulated reusable functionality that you can apply declaratively to your Web service. The SOAP extensions framework allows you to intercept SOAP messages exchanged between the client and the Web service. You can inspect or modify a message at various points during the processing of the message. You can apply a SOAP extension to either the server or the client.

A SOAP extension is composed of a class derived from the SoapExtension class. It contains the implementation details that are generally used to examine or modify the contents of a SOAP message. You can then define an attribute derived from SoapExtensionAttribute that associates the SOAP extension with a particular Web method or a class.

SOAP Extension Attributes

My first SOAP extension example will automatically process the Payment and Receipt headers I created in the last section. Instead of including code within the implementation of the InstantQuote Web method, I will create an attribute called ProcessPayment that can be used to decorate Web methods that require the Payment header to be processed. Later I will create the ProcessPaymentExtension class, which will contain the actual implementation. Here is the implementation of the ProcessPayment attribute:

[AttributeUsage(AttributeTargets.Method)]
public class ProcessPaymentAttribute : SoapExtensionAttribute 
{
    int        merchantNumber = 0;
    double    fee = 0;
    int        priority = 9;
 
    public ProcessPaymentAttribute(int merchantNumber,  double fee)
    {
        this.merchantNumber = merchantNumber;
        this.fee = fee;
    }
 
    public int MerchantNumber 
    {
        get { return merchantNumber; }
        set { merchantNumber = value; }
    }
 
    public double Fee 
    {
        get { return fee; }
        set { fee = value; }
    }
 
    public override Type ExtensionType 
    {
        get { return typeof(ProcessPaymentExtension); }
    }
 
    public override int Priority 
    {
        get { return priority; }
        set { priority = value; }
    }
}

The ProcessPayment attribute is responsible for gathering the information needed by the SOAP extension. The SOAP extension will require the merchant account number and the fee the client should be charged to process the payment. Thus, both the merchant number and the fee must be passed as part of the ProcessPayment attribute’s constructor. I also create associated MerchantNumber and Fee properties because the only mechanism for passing information from the SOAP extension attribute to the SOAP extension is by exposing the information as a public field or a public property.

Attributes that derive from SoapExtensionAttribute must override the ExtensionType property. This property returns an instance of the Type object of the SOAP extension class. The ASP.NET runtime will access this property to locate its associated SOAP extension.

All SOAP extension attributes must override the Priority property. This property specifies the priority in which the SOAP extension will be executed with respect to other SOAP extensions. I gave the Priority property a default value of 9 so that it can be optionally set by the user of the attribute.

The priority of the SOAP extension is used by ASP.NET to determine when it should be called in relation to other SOAP extensions. The higher the priority, the closer the SOAP extension is to the actual message being sent by the client and the response sent by the server. For example, a SOAP extension that compresses the body and the header of a SOAP message should have a high priority. On the other hand, the ProcessPayment SOAP extension does not need to have a high priority because it can function properly after other SOAP extensions have processed.

SOAP Extension Class

Table 6-8 SoapExtension Class Methods

The SOAP extension framework provides two methods of accessing the contents of the message. One way is through a stream object received by the ChainStream method that contains the raw contents of the message. The other way is through the properties and methods exposed by the instance of the SoapMessage object passed to the ProcessMessage method. For the ProcessPaymentExtension class, I will use the SoapMessage class.

The SOAP extension framework also provides a two-step initialization process through the GetInitializer and Initialize methods. The initialization process is designed to reduce the overall initialization cost associated with the extension. I discuss this in more detail later in this section.

The following diagram shows the order of the individual calls the ASP.NET runtime makes to the SOAP extension:

Initialization

A new SOAP extension object is created each time the Web method associated with it is invoked. The SOAP extension often performs initialization that is generic across all invocations of the Web method. The SOAP extension framework provides a means of executing initialization code that should occur once.

The SOAP extension framework supports a two-phase initialization sequence. The GetInitializer method performs the initialization for a particular Web method, in this case the InstantQuote method. GetInitializer will be called only once per Web method for the life of the Web application. The Initialize method will be called each time the Web method is invoked.

To process the Payment header, I need to initialize a credit card processor object. Once it is initialized, it can be used to process any number of Payment headers. Let’s assume that there is a nontrivial cost associated with initializing the object. I can initialize it once within the GetInitializer method and then use it each time the InstantQuote Web method is invoked. Here is the implementation of the GetInitializer method:

public override object GetInitializer(LogicalMethodInfo  methodInfo, SoapExtensionAttribute attribute) 
{
    ProcessPaymentAttribute processPaymentAttribute = 
   (ProcessPaymentAttribute)attribute;
 
    //  Set up connection to credit card authorization service.
    creditCardProcessor = 
    new CreditCardProcessor(processPaymentAttribute.MerchantNumber);
 
    //Return the initialized credit card processor object and the fee.
    return new object [] {creditCardProcessor, 
     processPaymentAttribute.Fee};
}

Notice that when ASP.NET invokes the GetInitializer method, the extension’s associated attribute is passed as a parameter. The attribute is used to obtain the MerchantNumber as well as the Fee properties. The method initializes the credit card processor.

This same credit card processor will then be used each time the InstantQuote Web method is invoked. However, recall that a new instance of the ProcessPaymentExtension object is created each time the Web method is invoked. So how can I use the same instance of the credit card processor object across all invocations of the Web method? The following diagram illustrates the problem.

One of the responsibilities of the Initialize method is to obtain the data returned to the ASP.NET runtime by the GetInitializer method. The Initialize method can also be used to perform any additional initialization that needs to occur for a particular Web method invocation. The following code shows the implementation of the GetInitializer and Initialize methods:

public class ProcessPaymentExtension : SoapExtension 
{
    CreditCardProcessor  creditCardProcessor;
    double               fee = 0;
    int                  referenceNumber = 0;
    SoapPaymentHeader    payment = null;
    SoapReceiptHeader    receipt = new SoapReceiptHeade r();
 
    public override object GetInitializer(Type type)
    {
        return typeof(ProcessPaymentExtension);
    }
 
    public override object GetInitializer(LogicalMethod Info 
    methodInfo, SoapExtensionAttribute attribute) 
    {
        ProcessPaymentAttribute processPaymentAttribute  = 
        (ProcessPaymentAttribute)attribute;
 
        //  Set up connection to credit card authorization service.
        creditCardProcessor = 
      new CreditCardProcessor(processPaymentAttribute.MerchantNumber);
 
        //Return the initialized credit card processor object and the
          fee.
        return new object [] {creditCardProcessor, 
        processPaymentAttribute.Fee};
    }
 
    public override void Initialize(object initializer)  
    {
        //  Retrieve the credit card processor and the fee 
        // from the initializer parameter.
        creditCardProcessor = 
       (CreditCardProcessor)((object[])initializer)[0];
        fee = (double)((object[])initializer)[1];
    }
 
    // The rest of the implementation...
 
}

The Initialize method performs any initialization that is specific to the method invocation. In the case of the ProcessPaymentExtension extension, no initialization needs to be accomplished. The only action is assigning the credit card processor object and the fee to a member variable within the class.

Processing the Message

The ProcessMessage method contains the implementation for processing the request message received from the client and the response message sent by the Web service. ProcessMessage is called by the ASP.NET runtime at four points. It is called twice during the process of deserializing the request message, once before the message is deserialized and once after. The ProcessMessage method is also called twice during the process of serializing the response message, once before serialization and once after.

Each time the ProcessMessage method is called, it is passed an instance of the SoapMessage class. During the BeforeSerialize and AfterSerialize stages, the object is initialized with the data contained within the SOAP message. Here is the implementation of the ProcessMessage method:

public override void ProcessMessage(SoapMessage message ) 
{
    switch (message.Stage) 
    {
        case SoapMessageStage.BeforeDeserialize:
         Trace.WriteLine("ProcessMessage(BeforeDeserialize) called.");
         break;
 
        case SoapMessageStage.AfterDeserialize:
         Trace.WriteLine("ProcessMessage(AfterDeserialize) called.");
 
            // Set the return header information.
            foreach(SoapUnknownHeader h in message.Headers)
            {
                Trace.WriteLine(h.Element.Name);
            }
            if(message.Headers.Contains(payment))
            {
                referenceNumber = 
                this.creditCardProcessor.Bill(fee, payment);
            }
            else
            {
                // Throw exception.
                throw new SoapException
                ("The required Payment header was not found.", 
                    SoapException.ClientFaultCode);
            }
 
            //  Verify that the credit card was processed.
            if(referenceNumber > 0)
            {
                // Set the return header information.
                receipt.ReferenceNumber = referenceNumber;
                receipt.Amount = fee;
            }
            else
            {
                throw new SoapException
                ("The credit card number could not be confirmed.", 
                    SoapException.ClientFaultCode);
            }
 
            break;
 
        case SoapMessageStage.BeforeSerialize:
           Trace.WriteLine("ProcessMessage(BeforeSerialize) called.");
            message.Headers.Add(receipt);
            break;
 
        case SoapMessageStage.AfterSerialize:
            Trace.WriteLine("ProcessMessage(AfterSerialize) called.");
            break;
 
        default:
            throw new SoapException("An invalid stage enumeration was
            passed.",
                SoapException.ServerFaultCode);
    }
}

The SoapMessageStage property determines at which of the four stages the message is called. I use a switch case statement to identify the stage at which ProcessMessage is called.

The code to process the Payment header accesses the header information via the message parameter. The message object is populated with the data contained within the SOAP request message only after the message has been deserialized. Therefore, the code to process the payment information is placed within the SoapMessageStage.AfterDeserialize case block.

Likewise, the code to add the Receipt header to the SOAP response message does so via the message object’s Header property. The message object is populated with the data contained within the SOAP request message only before the request message has been deserialized. Therefore, the code to process the payment information is placed within the SoapMessageStage.BeforeSerialize case block.

The code to process the payment information differs only slightly from the code I implemented in the SOAP Header section. One difference is that I use the preinitialized instance of the ProcessCreditCard object instead of creating a new one. The other difference is that the Payment header is obtained from the message object. The message object exposes the Headers property, which is of type SoapHeaderCollection. I obtain the Payment header by calling the Contains method on the instance of the SoapHeaderCollection object exposed by the Headers property.

The SoapMessage class contains other methods and properties that can be used within the ProcessMessage method. Table 6-9 describes some of them.

Table 6-9 Selected Properties and Methods of the SoapMessage Class

ChainStream Method

Another way to access the data contained within a SOAP message is using the ChainStream method. This method is used by the extension to receive a raw stream containing the contents of the message and to pass the modified version of the stream back to the ASP.NET runtime.

The next example uses a SOAP extension that logs the messages being exchanged between the client and the server. The SoapTrace attribute can be applied to any method. Its associated SoapTrace extension accesses the stream to write the contents of the message to a file.

[AttributeUsage(AttributeTargets.Method)]
public class SoapTraceAttribute : SoapExtensionAttribute 
{
    private string fileName = "c:\\temp\\SoapTrace.log" ;
    private int priority;
 
    public SoapTraceAttribute() {}
 
    public SoapTraceAttribute(string fileName)
    {
        this.fileName = fileName;
    }
 
    public override Type ExtensionType 
    {
        get { return typeof(SoapTraceExtension); }
    }
 
    public override int Priority 
    {
        get {return priority;}
        set {priority = value;}
    }
 
    public string FileName 
    {
        get {return fileName;}
        set {fileName = value;}
    }
}

First I declare the SoapTrace attribute. It contains an optional constructor that can be used to set the name of the trace log. If the filename is not set, it defaults to c:\temp\SoapTrace.log.

public class SoapTraceExtension : SoapExtension 
{
    string fileName;
    Stream inboundStream;
    Stream outboundStream;
    bool postSerializeHandlers = false;

I declare a few private member variables. The fileName variable holds the filename of the log file obtained by the SoapTrace attribute. The inboundStream and outboundStream variables hold references to the inbound and outbound streams, respectively. Finally postSerializeHandlers indicates whether the BeforeSerialize and AfterSerialize methods have been called. This variable will be used by the ChainStream method.

public override object GetInitializer(Type type)
{
    return typeof(SoapTraceExtension);
}
 
public override object GetInitializer(LogicalMethodInfo  methodInfo, 
SoapExtensionAttribute attribute) 
{
    return ((SoapTraceAttribute) attribute).FileName;
}
 
public override void Initialize(object initializer) 
{
    fileName = (string) initializer;
}

During GetInitializer, I retrieve the FileName property from the SoapExtension attribute. As with the previous extension, this value will be passed to the Initialize method.

public override Stream ChainStream( Stream stream )
{
    //  Set the streams based on whether we are about to call
    // the deserialize or serialize handlers.
    if(! postSerializeHandlers)
    {
        inboundStream = stream;
        outboundStream = new MemoryStream();
 
        return outboundStream;
    }
    else
    {
        outboundStream = stream;
        inboundStream = new MemoryStream();
 
        return inboundStream;
    }
}

Recall that ChainStream is called twice by the ASP.NET runtime: before the message received from the client is deserialized, and again before the message that will be sent from the server is serialized.

Each time ChainStream is called, two stream references are passed between the ASP.NET runtime and the SOAP extension. The ChainStream method receives a reference to an inbound stream that contains the original contents of the message. It also returns a reference to an outbound stream that will contain the contents of the new message. This effectively creates a chain of streams between the SOAP extensions associated with the method. The following diagram illustrates the chain that is created:

ChainStream accepts a single parameter of type Stream and returns a parameter of type Stream. The first time ChainStream is called, the inbound stream is passed by the ASP.NET runtime and ChainStream is responsible for returning the outbound stream. The second time ChainStream is called, the outbound stream is passed by the ASP.NET runtime and ChainStream is responsible for returning the inbound stream.

To keep my code as straightforward as possible, I use the postSerializeHandlers member variable to signal whether ChainStream is being called for the first time or the second time. I use an if/else statement to ensure that inboundStream and outboundStream are always set appropriately.

The first time ChainStream is called, it needs to return a readable stream that contains the SOAP message that will be deserialized by the runtime. Because SOAP extensions often modify the contents of the stream, they often return a new instance of the MemoryStream class. If ChainStream creates a new stream, it becomes the outbound stream.

The second time ChainStream is called, it needs to return a read/writable stream to the ASP.NET runtime. The ASP.NET runtime will use this stream to communicate the current contents of the message to the SOAP extension. Before the BeforeSerialization stage of ProcessMessage is called, the ASP.NET runtime will populate the stream with the contents of the SOAP message that was returned by the previously called SOAP extension. When ProcessMessage is finally called, the inbound stream can then be read by the SOAP extension, the message can be modified, and finally the new message can be written to the outbound stream. Therefore, the second time ChainStream is called, it needs to create a new stream for the inbound stream.

There is one more caveat. The ChainStream method cannot modify the stream it receives from the ASP.NET runtime. The received stream can be modified only by the ProcessMessage method. If ChainStream does access any properties or methods of the stream received from ASP.NET, a runtime exception will occur.

public override void ProcessMessage(SoapMessage message ) 
{
    switch (message.Stage) 
    {
        case SoapMessageStage.BeforeDeserialize:
            CopyStream(inboundStream, outboundStream);
            break;
 
        case SoapMessageStage.AfterDeserialize:
            postSerializeHandlers = true;
            break;
 
        case SoapMessageStage.BeforeSerialize:
            break;
 
        case SoapMessageStage.AfterSerialize:
            WriteTraceLogEntry("Response");
            CopyStream(inboundStream, outboundStream);
            break;
 
        default:
            throw new Exception("invalid stage");
    }
}

The ProcessMessage method is responsible for writing the contents of the inbound stream to the log file. This is accomplished by calling the WriteTraceLogEntry helper function. It must also write the contents of the SOAP message to the outbound stream. This is accomplished by calling the CopyStream helper function. Finally ProcessMessage must set the postSerializeHandlers member variable used by the ChainStream method to true before exiting the AfterDeserialize stage.

private void WriteTraceLogEntry(string messageTitle)
{
    // Create a file stream for the log file.
    FileStream fs = new FileStream(fileName, FileMode.Append, 
    FileAccess.Write);
 
    //  Create a new stream writer and write the header of the  trace.
    StreamWriter writer = new StreamWriter(fs);
    writer.WriteLine();
    writer.WriteLine("{0} Message Received at {1}:", messageTitle, 
    DateTime.Now);
    writer.Flush();
 
    // Copy contents of the stream to the file.
    AppendStream(inboundStream, fs);
    fs.Close();
}

The WriteTraceLogEntry method writes an entry in the SOAP trace log. It first writes a header entry, and then it appends the log file with the contents of the inbound stream:

private void CopyStream(Stream sourceStream, Stream destinationStream) 
{
    long sourcePosition = 0;
    long destinationPosition = 0;
 
    //  If seekable, save starting positions of the streams
    // and set them both to the beginning.
    if(sourceStream.CanSeek)
    {
        sourcePosition = sourceStream.Position;
        sourceStream.Position = 0;
    }
    if(destinationStream.CanSeek)
    {
        destinationPosition = destinationStream.Position;
        destinationStream.Position = 0;
    }
 
    //  Copy the contents of the "to" stream into the "from" stream.
    TextReader reader = new StreamReader(sourceStream);
    TextWriter writer = new StreamWriter(destinationStream);
    writer.WriteLine(reader.ReadToEnd());
    writer.Flush();
 
    // Set the streams back to their original position.
    if(sourceStream.CanSeek) sourceStream.Position = sourcePosition;
    if(destinationStream.CanSeek) 
        destinationStream.Position = destinationPosition;
}

The CopyStream method writes the contents of the source stream to the destination stream. Because not all streams received by the ASP.NET runtime are seekable, a check is made before the position of a stream is modified:

private void AppendStream(Stream sourceStream, 
Stream destinationStream) 
{
    long sourcePosition = 0;
 
    //  If seekable, save starting positions of the streams 
    // and set them both to the beginning.
    if(sourceStream.CanSeek)
    {
        sourcePosition = sourceStream.Position;
        sourceStream.Position = 0;
    }
    if(destinationStream.CanSeek)
    {
        destinationStream.Position = destinationStream. Length;
    }
 
    //  Copy the contents of the "to" stream into the "from" stream.
    TextReader reader = new StreamReader(sourceStream);
    TextWriter writer = new StreamWriter(destinationStream);
    writer.WriteLine(reader.ReadToEnd());
    writer.Flush();
 
    //  Set the streams back to their original positions.
    if(sourceStream.CanSeek) sourceStream.Position = sourcePosition;
}

The AppendStream method is used by WriteTraceLogEntry to append the contents of the inbound stream to the end of the log file stream.

Page 3 of 4 Go to page:

Sample Chapter from the book: Building XML Web Services for the Microsoft® .NET Platform