You Must Understand This

  • Article

WCF allows you to customize the collection of message headers sent with a request, including defining your own custom headers. Message receivers tend to be very loose about the messages that they accept and they typically will silently ignore any headers that they don't understand. However, this is a bad thing to have happen when your custom message header is intended to change the semantics of an operation.

The solution to this problem in SOAP is the mustUnderstand attribute. The mustUnderstand attribute is a qualifying tag to the message header stating that the receiver must either successfully process the message header or fail the operation. Use of the mustUnderstand attribute can help you when versioning your service. After a version upgrade, there is a potential for miscommunication between clients and servers that have different versions. If you add new headers to your messages, such that calls will still complete for an older version but the meaning of those calls has changed, then marking the relevant message headers as mustUnderstand will change this soft failure to a hard failure. Making the call fail makes it much easier to detect the problem than if the result is silent data corruption.

You can control the mustUnderstand attribute for your messages through the MessageHeader attribute in your MessageContract on the client. The contract shown here is based on one automatically generated by svcutil.exe.

 [DebuggerStepThrough()]
[GeneratedCode("System.ServiceModel", "3.0.0.0")]
[MessageContract(WrapperName = "MyMessageContract")]
public partial class MyMessageContract
{
   [MessageHeader(Namespace = "https://tempuri.org/", MustUnderstand = true)]
   public string importantHeader;

   [MessageBodyMember(Namespace = "https://tempuri.org/", Order = 0)]
   public string body;

   public MyMessageContract()
   {
   }

   public MyMessageContract(string importantHeader, string body)
   {
      this.importantHeader = importantHeader;
      this.body = body;
   }
}

This causes the generated message to have the mustUnderstand attribute be set.

 <s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
 <s:Header>
  <h:importantHeader s:mustUnderstand="1" xmlns:h="https://tempuri.org/">
   header
  </h:importantHeader>
 </s:Header>
 <s:Body>
  <MyMessageContract xmlns="https://tempuri.org/">
   <body>
    body
   </body>
  </MyMessageContract>
 </s:Body>
</s:Envelope>

Next time: Stream Upgrades, Part 1