Microsoft Windows Communication Foundation 4.0 Cookbook for Developing SOA Applications

When OperationContract is marked with IsOneWay=true, the runtime will detect this and know that this service operation needs to be handled as one-way style. One-way operation cannot carry a return value but can only pass input parameters to the service. After the client sends out the service request, the client will wait until it gets the response that the request message has reached the service side. However, the response here is not the return value, but the protocol level ACK, which indicates that the request has reached the service (but gives no idea of whether or how the request has been processed).

We can get further understanding on one-way operation via the following question:

What is the difference between a standard void (no return value) operation and a one-way operation?

Suppose you have the following ServiceContract implemented:

[ServiceContract]
 public interface IHelloService
 {
     [OperationContract(IsOneWay=false)]
     void DoWork();

     [OperationContract(IsOneWay = true)]
     void DoWorkAsOneWay();
}

By invoking the two operations from the client and capturing the HTTP message, we can get different response messages as shown in the next two screenshots. The first screenshot shows the response of the DoWork operation, while the next shows the response of the DoWorkAsOneWay operation.

As you can see, the normal void operation will return HTTP 200 status code and the complete SOAP Response in the body, while the one-way operation will only return a HTTP 202 Accepted status header. This indicates that the one-way operation call gets finished as long as the server side received the request, while the normal void operation (standard request/reply) will wait for the server side to execute and return the response data. Understanding this can help us to make better decisions about whether to use one-way operation or not.

In addition to one-way operation, there are two other message exchange patterns that are widely used in WCF services. They are the Request-response pattern and the Duplex pattern.

The Request-response pattern is very similar to the standard function call that has an input parameter and return value. In a Request-response pattern-based WCF service operation call, a message is sent and a reply is received. The pattern consists of request-response pairs, as shown in the next figure.

The Duplex exchange pattern allows an arbitrary number of messages to be sent by a client and received in any order. This pattern is like a phone conversation, where each word being spoken is a message (refer to the following screenshot).

After the DataContract type implements the IExtensibleDataObject interface, an ExtensionDataObject property is added; this property plays an important role in forward-compatible serialization. WCF will use DataContractSerializer for DataContract type serialization/deserialization. When DataContractSerializer finds that a certain type (used for operation parameters or return value) has implemented the IExtensibleDataObject interface, it will store any data (this is obtained from the message stream during deserialization) that doesn't have corresponding property/fields in the type definition into the ExtensionDataObject property so that these data will not get lost. And if the deserialized instance (with some unknown data stored in ExtensionDataObject) is serialized into the message later, DataContractSerializer will write out ExtensionDataObject into the message stream again. This ensures that the data in the new version of DataContract can be consumed by the service/client with the old type definition correctly, instead of raising unexpected type, mismatching, or serialization exceptions.

The following modified data type can be consumed by the service/client that has the old definition, as explained earlier, without synchronizing the DataContract type definition:

[DataContract]
    public class FCQuestion : IExtensibleDataObject
    {
        [DataMember]
        public string Subject { get; set; }
        [DataMember]
        public string Answer { get; set; }
        [DataMember]
        public string Comment { get; set; }

        public ExtensionDataObject ExtensionData
        {            get; set;       }
    }

Currently, using the IExtensibleDataObject interface can make the DataContractSerializer preserve unknown data properties/fields when deserializing/serializing custom data types. However, the ExtensionDataObject property is an opaque object to developers and we do not have means to manually read the data stored in it. In case we want to manually extract the additional unknown property/fields, we can consider directly accessing the underlying SOAP message via MessageInspector or other extension points.

If you are not yet familiar with the contract-first development approach, you can get a quick overview of it from Aaron Skonnard's MSDN article Contract-First Service Development at http://msdn.microsoft.com/en-us/magazine/cc163800.aspx.

The contract-first development approach is contract/schema driven; the developers need to author the metadata/contract of the service/data. For the previous example, TestDataContractSchema.xsd provides the contract definition of two types that will be used in our WCF service.

Svcutil.exe is a very powerful tool provided in the .NET 3.5 SDK. If you're familiar with ASP .NET ASMX Web Service development, you will find it similar to the wsdl.exe tool. You can generate a WCF client proxy and export metadata from service code. Here we just use it to generate serialization code from the given XML Schema. In the previous sample, we specify DataContractSerializer as the serialization type (you can also use XMLSerializer instead, if you prefer XML serialization-oriented code).

By capturing the service operation's underlying SOAP message on wire (refer to the next screenshot), we can find that the return value's XML payload conform to the XML Schema we provided as the generation source (TestDataContractSchema.xsd):

The DataContract we generated here includes two typical class types—a composite type and a simple enum type. In most scenarios, people will define much more complicated data types in their services, and WCF DataContractSerializer does provide enough support for mapping between an XML Schema-based contract and .NET code-based types. You can get more information on type mapping in the MSDN document Data Contract Schema Reference, available at:

http://msdn.microsoft.com/en-us/library/ms733112.aspx.

When we apply the XmlSerializerFormatAttribute on the ServiceContract, the WCF runtime will use XMLSerializer as the default Serializer to serialize data and deserialize SOAP messages. Also, the auto-generated service metadata will output the data type schema based on the class's XML serialization attributes. For the User class mentioned in the previous code example, service metadata will use the schema as shown in the next screenshot to represent its XML format:

By capturing the underlying SOAP message, we can find that the XML content of the serialized User object conforms to the metadata schema defined earlier, which is controlled by those XML serialization attributes applied on the user class (refer to the next screenshot):

Types marked with MessageContractAttribute can be used to represent the entire SOAP envelope body. The serialization of such types still follows the rules for normal DataContract types.

Also, it is important that operations which use MessageContract to control the SOAP envelope only have a single input parameter and return value. This is because only that input parameter will be serialized as the entire SOAP request body, and the return value will be serialized as the entire SOAP response body.

By capturing the SOAP request/response on wire, we can find that the serialized SOAP message content conforms to the MessageContract definition (refer to the next two screenshots):

The MessageHeaderAttribute helps mark the particular type member (of MessageContract type) as the SoapHeader that will be embedded in the resulting SOAP Envelope. Also, since the header is added in MessageContract at design-time, the WCF auto-generated metadata will include the SoapHeader information, as shown in the following screenshot:

If you use Visual Studio or Svcutil.exe to generate the client proxy class, the generated proxy type will automatically map the SoapHeaders to operation parameters. Thus, when invoking the service operation, we can simply pass SoapHeader data as the operation parameter. The following code demonstrates how the auto-generated service proxy invokes the operation with the custom SoapHeader assigned.

private static void CallService()
  {
      TestProxy.TestServiceClient client = new TestProxy.TestServiceClient();

      TestProxy.MyUsernameToken utoken = new TestProxy.MyUsernameToken{ Username="Foo", Password="Bar"};
      string reply = client.SayHello(utoken, "WCF user");

      Console.WriteLine(reply);
  }

By capturing the underlying SOAP message, we can find that the MyUsernameToken header type is serialized as a SoapHeader within the <Header> section.

WCF supports various means to add custom SoapHeader a into service messages. This recipe demonstrates using a custom type and MessageContract to add a custom SoapHeader statically. In addition to this, we can also use code to programmatically add SoapHeaders into service messages.

The FaultContractAttribute applied on the service operation will make the runtime generate corresponding metadata entries in the WSDL document (as shown in the next screenshot). Thus, the generated client proxy knows how to handle this custom error type.

When invoking the operation, we can add code to handle the specific FaultException and get user-friendly error information from the Exception.Detail property.

try
{
     //call the operation with invalid parameter
}
catch (FaultException<UserFriendlyError> fex)
{
     Console.WriteLine("Error: {0}", fex.Detail.Message);
}

If we use Fiddler or message logging to inspect the underlying SOAP message, we can also find the custom error data in XML-serialized format:

Since the custom error type used by FaultContract supports any valid DataContract type, we can define various kinds of custom exception data content (from simple primitive types to complex nested classes).