Message Contract in WCF

The following  is the contents of this article:

  • Message Contract
  • Why Message Contract
  • Source Code Explanation
  • Attachment
  • Summary

Message Contract

As I said in the last article, a Data Contract is all about the structure of the data being exchanged between the client and server, whereas a Message Contract is all about the structure of the message being exchanged. By default WCF takes care of creating SOAP messages according to the data and service contracts, but sometimes we need complete control over the content of SOAP messages (header and body) to provide an additional layer of security. In that case a Message Contract plays a vital role. Ok let's discuss the benefits of a Message Contract with a source code example.

Why a Message Contract

Message Contracts can be used in the following instances.

Session Information

Sometimes your project requires that session information be exchanged between the client and server to provide an extra layer of security, so it can be passed in SOAP headers rather than adding additional parameters to operations or adding this information as fields in the data itself.


Sometimes you like to have a custom security protocol (by passing WS-Security) and pass credentials or tokens in custom SOAP headers. Also, when you need to or like to encrypt the header information a Message Contract can be used. The downside with this technique is that the client and the service must manually add and retrieve the information from the SOAP header, rather than having the serialization classes associated with the data and the operation contracts do it for you

Entity Changes often

In case of MessageContracts modification the data structure just needs to change the Message Contract and there is no need for the regenerating proxies. In case of a change in DataContracts you need to regenerate the proxy. So a MessageContract is the best choice if your entity changes often.

Source Code Explanation

For your quick reference here I am attaching the structure of the SOAP message.

If you want more information on the SOAP topic, please refer to my article Service Oriented Apporach (SOA). Ok, let's discuss how a Message Contract is implemented.

  1. [MessageContract(IsWrapped=false)]  
  2.     public class OrderRequest  
  3.     {  
  4.         private int iOrderID;  
  6.         [MessageHeader]  
  7.         public int OrderID  
  8.         {  
  9.             get { return iOrderID; }  
  10.             set { iOrderID = value; }  
  11.         }  
  12.     } 

As mentioned above, the Message Contract attribute must be added at the top of the class as we do for the Data Contract. OrderRequest is the MessageContract attributed class communicating back and forth with a SOAP message. OrderID is attributed as the SOAP Message header, which holds the order id of a customer.

  1. public OrderResponse GetOrderHistory(OrderRequest OrderReq)  
  2.         {  
  4.             if (OrderReq.OrderID.Equals(OrderID))   
  5.             {                                     
  6.                 OrderResponse response = new OrderResponse();  
  7.                 OrderInfo OI = new OrderInfo();  
  8.                 OI.OrderId = OrderID;  
  9.                 OI.OrderDate = DateTime.Now;  
  10.                 OI.PaidByCard = true;  
  11.                 OI.PurchasedProductName = "Barbie Doll";  
  12.                 OI.Quality = 5;  
  13.                 response.OrderInfoObject = OI;  
  14.                 return response;  
  15.             }  
  16.             else  
  17.             {  
  18.         throw new FaultException<string>("Order Detail Not Found",new  FaultReason("Order Detail Not Found"));  
  19.      }  


In our case the OrderRequest class is used for passing the input parameters to a service method GetOrderHistory. The OrderResponse is also a MessageContract attributed class that returns the SOAP response. The following picture shows you the SOAP request and the response:


Refer to the source code attachment for further details.


Session related implementations can use a Message Contract to get complete control of SOAP messages. Also if your entity is dynamic (keeps changing) you can use a Message Contract.

Similar Articles