WCF Extensibility – Message Formatters

This post is part of a series about WCF extensibility points. For a list of all previous posts and planned future ones, go to the index page.

Message formatters are the component which do the translation between CLR operations and the WCF Message object – their role is to convert all the operation parameters and return values (possibly via serialization) into a Message on output, and deconstruct the message into parameter and return values on input. Anytime a new format is to be used (be it a new serialization format for currently supported CLR types, or supporting a new CLR type altogether), a message formatter is the interface you’d implement to enable this scenario. For example, even though the type System.IO.Stream is not serializable (it’s even abstract), WCF allows it to be used as the input or return values for methods (for example, in the WCF REST Raw programming model) and a formatter deals with converting it into messages. Like the message inspectors, there are two versions, one for the server side (IDispatchMessageFormatter), and one for the client side (IClientMessageFormatter).

Among the extensibility points listed in this series, the message formatters are the first kind to be required in the WCF pipeline – a service does not need to have any service / endpoint / contract / operation behavior, nor any message / parameter inspector. If the user doesn’t add any of those, the client / service will just work (some behaviors are automatically added to the operations when one adds an endpoint, but that’s an implementation detail for WCF – they aren’t strictly necessary). Formatters, on the other hand, are required (to bridge the gap between the message world and the operations using CLR types). If we don’t add any behaviors to the service / endpoint / contract / operation that sets a formatter, WCF will add one formatter to the operation (usually via the DataContractSerializerOperationBehavior, which is added by default in all operation contracts).

Public implementations in WCF

None. As with most of the runtime extensibility points, there are no public implementations of either the dispatch or the client message formatter. There are a lot of internal implementations, though, such as a formatter which converts operation parameters into a message (both using the DataContractSerializer and the XmlSerializer), formatters which map parameters to the HTTP URI (used in REST operations with UriTemplate), among others.

Interface declaration

  1. public interface IDispatchMessageFormatter
  2. {
  3.     void DeserializeRequest(Message message, object[] parameters);
  4.     Message SerializeReply(MessageVersion messageVersion, object[] parameters, object result);
  5. }
  7. public interface IClientMessageFormatter
  8. {
  9.     Message SerializeRequest(MessageVersion messageVersion, object[] parameters);
  10.     object DeserializeReply(Message message, object[] parameters);
  11. }

The formatter interfaces each have two methods, one to convert between input outgoing CLR objects into the Message object (serialize), and one to take the incoming message object apart and break it down into incoming CLR objects (deserialize).

At the server side, after the the message was decoded, passed through the channel stack and other extensibility points and is about to be dispatched to the service operation, the method DeserializeRequest is called to deserialize the message object into an array of parameters to be passed to the operation. The object argument “parameters” will have been allocated, so the implementation of the formatter only needs to read the message and set the operation parameters in their correct order in the array passed to it. After the operation is invoked (and any parameter inspector has a chance to change the operation outputs), SerializeReply is called, to take the operation return, plus the final value of any out/ref parameters which the operation may have, and package them into a Message object to be sent down the WCF channel stack.

At the client side the mirror happens: when the operation is called (and after the parameter inspector has a chance to change the inputs), SerializeRequest is called to package all the input parameters into the outgoing message object. After the message is sent to the server and the response is decoded by the client’s encoder, DeserializeReply is called to open the message object and populate the return value and any possible out/ref parameters.

One small parenthesis about out/ref parameters: all parameters in WCF calls are passed by value – a copy of the value is sent across the wire. If an operation declares a parameter with a ref modifier (ByRef in Visual Basic), the service will receive a copy (i.e., by value) of that parameter, and then return another copy of the value of the parameter at the end of the method. This second copy will be deserialized at the client into a new instance of that type. So even if you pass an instance of your type by reference to a WCF service, and the service doesn’t change it at all, the value at the end of the call at the client side the reference will point to a different object.

  1. [ServiceContract]
  2. public interface ITest
  3. {
  4.     [OperationContract]
  5.     void UpdatePerson(ref Person person);
  6.     [OperationContract]
  7.     void InOutRef(int x, ref int y, out int z, out int w);
  8. }
  9. public class Client
  10. {
  11.     public static void Main()
  12.     {
  13.         ChannelFactory<ITest> factory = new ChannelFactory<ITest>();
  14.         ITest proxy = factory.CreateChannel();
  15.         Person p1 = new Person();
  16.         Person p2 = p1;
  17.         Console.WriteLine(object.ReferenceEquals(p1, p2)); // true
  18.         proxy.UpdatePerson(ref p2);
  19.         Console.WriteLine(object.ReferenceEquals(p1, p2)); // false, even if service doesn't change reference
  20.     }
  21. }

Going back to the formatters, the list of “input” parameters (those in the *Request) operations are either the input (ByVal) parameters or reference (ByRef without <Out>). The list of “output” parameters are ones marked with ref (ByRef) and out (<Out> ByRef). In the operation InOutRef above, the parameters x and y are considered to be input parameters, so the parameters array in the *Request operations will have two objects). The parameters y, z and w are considered to be output parameters, so the parameters array in the *Reply operations will have three elements.

How to add message formatters

At the server side: the formatter is a property of the operation runtime, so at the server side it’s available at the DispatchOperation object. This object is typically accessed via an operation behavior, or by traversing the operation list from an endpoint behavior. both in the ApplyDispatchBehavior method. Another way is if you’re creating a REST endpoints (i.e., one with a behavior which inherits from WebHttpBehavior). WebHttpBehavior exposes two protected methods, GetRequestDispatchFormatter and GetReplyDispatchFormatter, which can be overridden to to return the formatter to be used by the operation.

  1. public class MyDispatchMessageFormatter : IDispatchMessageFormatter
  2. {
  3.     OperationDescription operation;
  4.     public MyDispatchMessageFormatter(OperationDescription operation) { ... }
  5. }
  6. public class MyRestBehavior : WebHttpBehavior
  7. {
  8.     protected override IDispatchMessageFormatter GetReplyDispatchFormatter(OperationDescription operationDescription, ServiceEndpoint endpoint)
  9.     {
  10.         return new MyDispatchMessageFormatter(operationDescription);
  11.     }
  12. }

At the client side: Similarly, the operation formatter at the client side is available at the ClientOperation object, typically accessed via an operation or endpoint behavior. And for behaviors inheriting from WebHttpBehavior, there are two protected methods, GetRequestClientFormatter and GetReplyClientFormatter, which can be used to return the operation formatter as well.

  1. public class MyClientFormatter : IClientMessageFormatter
  2. {
  3. }
  4. public class MyOperationBehavior : IOperationBehavior
  5. {
  6.     public void ApplyClientBehavior(OperationDescription operationDescription, ClientOperation clientOperation)
  7.     {
  8.         clientOperation.Formatter = new MyClientFormatter();
  9.     }
  10. }

A quick note about wrapping the default WCF formatter. As I mentioned before, the default formatter is usually added by the DataContractSerializerOperationBehavior when it’s executed. If we want to use that default formatter, and wrap it in our own formatter, we need to make sure that the DataContractSerializerOperationBehavior is a position in the operation behavior list which is executed before our own operation behavior is. Take this seemingly problem-free example:

  1. [ServiceContract]
  2. public interface ITest
  3. {
  4.     [OperationContract]
  5.     [MyOperationBehavior]
  6.     int Add(int x, int y);
  7. }
  8. public class Service : ITest
  9. {
  10.     public int Add(int x, int y) { return x + y; }
  11. }
  12. public class MyClientFormatter : IClientMessageFormatter
  13. {
  14.     IClientMessageFormatter inner;
  15.     public MyClientFormatter(IClientMessageFormatter inner)
  16.     {
  17.         if (inner == null) throw new ArgumentNullException("inner");
  18.         this.inner = inner;
  19.     }
  21.     public object DeserializeReply(Message message, object[] parameters)
  22.     {
  23.         return this.inner.DeserializeReply(message, parameters);
  24.     }
  26.     public Message SerializeRequest(MessageVersion messageVersion, object[] parameters)
  27.     {
  28.         return this.inner.SerializeRequest(messageVersion, parameters);
  29.     }
  30. }
  31. public class MyOperationBehaviorAttribute : Attribute, IOperationBehavior
  32. {
  33.     public void AddBindingParameters(OperationDescription operationDescription, BindingParameterCollection bindingParameters)
  34.     {
  35.     }
  37.     public void ApplyClientBehavior(OperationDescription operationDescription, ClientOperation clientOperation)
  38.     {
  39.         clientOperation.Formatter = new MyClientFormatter(clientOperation.Formatter);
  40.     }
  42.     public void ApplyDispatchBehavior(OperationDescription operationDescription, DispatchOperation dispatchOperation)
  43.     {
  44.     }
  46.     public void Validate(OperationDescription operationDescription)
  47.     {
  48.     }
  49. }
  51. class Program
  52. {
  53.     static void Main(string[] args)
  54.     {
  55.         string baseAddress = "http://" + Environment.MachineName + ":8000/Service";
  56.         ServiceHost host = new ServiceHost(typeof(Service), new Uri(baseAddress));
  57.         host.AddServiceEndpoint(typeof(ITest), new BasicHttpBinding(), "");
  58.         host.Open();
  60.         ChannelFactory<ITest> factory = new ChannelFactory<ITest>(new BasicHttpBinding(), new EndpointAddress(baseAddress));
  61.         foreach (var opBehavior in factory.Endpoint.Contract.Operations[0].Behaviors)
  62.         {
  63.             Console.WriteLine(opBehavior);
  64.         }
  66.         ITest proxy = factory.CreateChannel();
  67.         Console.WriteLine(proxy.Add(3, 4));
  68.     }
  69. }

The call to CreateChannel in the channel factory will fail – the constructor of MyClientFormatter will throw. That’s because the order of the operation behaviors (printed in the code) is the following:


I have no idea why attribute-based operation behaviors are added in this position, but the fact is that this doesn’t work. So for this scenario we cannot use attribute-based behaviors, we need to add it “manually”, as shown below.

  1. [ServiceContract]
  2. public interface ITest
  3. {
  4.     [OperationContract]
  5.     //[MyOperationBehavior]
  6.     int Add(int x, int y);
  7. }
  9. class Program
  10. {
  11.     static void Main(string[] args)
  12.     {
  13.         string baseAddress = "http://" + Environment.MachineName + ":8000/Service";
  14.         ServiceHost host = new ServiceHost(typeof(Service), new Uri(baseAddress));
  15.         ServiceEndpoint endpoint = host.AddServiceEndpoint(typeof(ITest), new BasicHttpBinding(), "");
  16.         endpoint.Contract.Operations.Find("Add").Behaviors.Add(new MyOperationBehaviorAttribute());
  17.         host.Open();
  19.         ChannelFactory<ITest> factory = new ChannelFactory<ITest>(new BasicHttpBinding(), new EndpointAddress(baseAddress));
  20.         ITest proxy = factory.CreateChannel();
  21.         Console.WriteLine(proxy.Add(3, 4));
  22.     }
  23. }

After doing that, the code runs and works fine.

Real world scenario: supporting different data and serialization formats

The first version of WCF (.NET Framework 3.0) supported essentially SOAP endpoints – an XML payload following some rules defined in the SOAP specification (you actually could do POX/REST, but it was awfully hard). On the next version (.NET Framework 3.5), the REST programming model was added and that started supporting a whole new set of formats, mostly notably POX (plain-old XML, no SOAP involved), JSON (based on the DataContractJsonSerializer) and a special “raw” mode, where one could declare a single Stream parameter in an operation for receiving arbitrary data, or returning a Stream value for returning arbitrary data. The raw mode can be used to support essentially all data and serialization formats, but that comes at a price that the operation itself has to deal with serializing / deserializing the parameters. Also, there are scenarios (from the forums) where the user needs to expose the same operation in non-REST endpoints (or even non-HTTP, as in the scenario described in the forum post), where the Stream trick won’t work. This example will expand on the answer to the forum question and provide formatters which will use a custom serializer (in this case, the JSON.NET one, available from codeplex at http://json.codeplex.com).

And the usual disclaimer: this is a sample for illustrating the topic of this post, this is not production-ready code. I tested it for a few contracts and it worked, but I cannot guarantee that it will work for all scenarios (please let me know if you find a bug or something missing). Also, for simplicity sake it doesn’t have a lot of error handling which a production-level code would, and it isn’t fully integrated with the WCF REST pipeline (i.e., it doesn’t support UriTemplates, it doesn’t integrate with the REST help page, doesn’t support out/ref parameters,, etc.).

First, some data contracts to set up the scenario. The service will process people and their pets. The data contracts are decorated both with WCF serialization attributes (DataContract, DataMember), and with the JSON.NET serialization attributes (JsonObejct, JsonProperty, JsonConverter) so that it can be mapped according to both formats.

  1. [DataContract]
  2. [Newtonsoft.Json.JsonObject(MemberSerialization = Newtonsoft.Json.MemberSerialization.OptIn)]
  3. public class Person
  4. {
  5.     [DataMember(Order = 1), Newtonsoft.Json.JsonProperty]
  6.     public string FirstName;
  7.     [DataMember(Order = 2), Newtonsoft.Json.JsonProperty]
  8.     public string LastName;
  9.     [DataMember(Order = 3),
  10.         Newtonsoft.Json.JsonProperty,
  11.         Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.IsoDateTimeConverter))]
  12.     public DateTime BirthDate;
  13.     [DataMember(Order = 4), Newtonsoft.Json.JsonProperty]
  14.     public List<Pet> Pets;
  15.     [DataMember(Order = 5), Newtonsoft.Json.JsonProperty]
  16.     public int Id;
  17. }
  19. [DataContract, Newtonsoft.Json.JsonObject(MemberSerialization = Newtonsoft.Json.MemberSerialization.OptIn)]
  20. public class Pet
  21. {
  22.     [DataMember(Order = 1), Newtonsoft.Json.JsonProperty]
  23.     public string Name;
  24.     [DataMember(Order = 2), Newtonsoft.Json.JsonProperty]
  25.     public string Color;
  26.     [DataMember(Order = 3), Newtonsoft.Json.JsonProperty]
  27.     public string Markings;
  28.     [DataMember(Order = 4), Newtonsoft.Json.JsonProperty]
  29.     public int Id;
  30. }

Next the interface definition, and the service implementation. It’s not very interesting, but I added operations using both GET and POST methods, and operations with single and multiple parameters (the goal of this sample is to demonstrate the formatter, not a specific service, so I think I can slack off on the service example a little Smile).

  1. [ServiceContract]
  2. public interface ITestService
  3. {
  4.     [WebGet, OperationContract]
  5.     Person GetPerson();
  6.     [WebInvoke, OperationContract]
  7.     Pet EchoPet(Pet pet);
  8.     [WebInvoke(BodyStyle = WebMessageBodyStyle.WrappedRequest), OperationContract]
  9.     int Add(int x, int y);
  10. }
  12. public class Service : ITestService
  13. {
  14.     public Person GetPerson()
  15.     {
  16.         return new Person
  17.         {
  18.             FirstName = "First",
  19.             LastName = "Last",
  20.             BirthDate = new DateTime(1993, 4, 17, 2, 51, 37, 47, DateTimeKind.Local),
  21.             Id = 0,
  22.             Pets = new List<Pet>
  23.             {
  24.                 new Pet { Name= "Generic Pet 1", Color = "Beige", Id = 0, Markings = "Some markings" },
  25.                 new Pet { Name= "Generic Pet 2", Color = "Gold", Id = 0, Markings = "Other markings" },
  26.             },
  27.         };
  28.     }
  30.     public Pet EchoPet(Pet pet)
  31.     {
  32.         return pet;
  33.     }
  35.     public int Add(int x, int y)
  36.     {
  37.         return x + y;
  38.     }
  39. }

Now the behavior which will set everything together. Since this is a REST endpoint, instead of writing a new endpoint, I’ll simply inherit from WebHttpBehavior, and override the protected methods to return the client and server formatters. Notice that in some cases when there are no parameters or for GET requests (where the parameters are in the query string, not in the request body), so in those cases I’ll simply reuse the default formatter from the base class. Another logic which is implemented at the behavior is validation – we know what our formatter doesn’t support, so we’ll simply throw while the service (or the client channel) is being opened, giving the user a clear message explaining why the behavior failed the validation (some of the validation code is not in the snippet below, but it can be found in the source code for this post).

  1. public class NewtonsoftJsonBehavior : WebHttpBehavior
  2. {
  3.     public override void Validate(ServiceEndpoint endpoint)
  4.     {
  5.         base.Validate(endpoint);
  7.         BindingElementCollection elements = endpoint.Binding.CreateBindingElements();
  8.         WebMessageEncodingBindingElement webEncoder = elements.Find<WebMessageEncodingBindingElement>();
  9.         if (webEncoder == null)
  10.         {
  11.             throw new InvalidOperationException("This behavior must be used in an endpoint with the WebHttpBinding (or a custom binding with the WebMessageEncodingBindingElement).");
  12.         }
  14.         foreach (OperationDescription operation in endpoint.Contract.Operations)
  15.         {
  16.             this.ValidateOperation(operation);
  17.         }
  18.     }
  20.     protected override IDispatchMessageFormatter GetRequestDispatchFormatter(OperationDescription operationDescription, ServiceEndpoint endpoint)
  21.     {
  22.         if (this.IsGetOperation(operationDescription))
  23.         {
  24.             // no change for GET operations
  25.             return base.GetRequestDispatchFormatter(operationDescription, endpoint);
  26.         }
  28.         if (operationDescription.Messages[0].Body.Parts.Count == 0)
  29.         {
  30.             // nothing in the body, still use the default
  31.             return base.GetRequestDispatchFormatter(operationDescription, endpoint);
  32.         }
  34.         return new NewtonsoftJsonDispatchFormatter(operationDescription, true);
  35.     }
  37.     protected override IDispatchMessageFormatter GetReplyDispatchFormatter(OperationDescription operationDescription, ServiceEndpoint endpoint)
  38.     {
  39.         if (operationDescription.Messages.Count == 1 || operationDescription.Messages[1].Body.ReturnValue.Type == typeof(void))
  40.         {
  41.             return base.GetReplyDispatchFormatter(operationDescription, endpoint);
  42.         }
  43.         else
  44.         {
  45.             return new NewtonsoftJsonDispatchFormatter(operationDescription, false);
  46.         }
  47.     }
  49.     protected override IClientMessageFormatter GetRequestClientFormatter(OperationDescription operationDescription, ServiceEndpoint endpoint)
  50.     {
  51.         if (operationDescription.Behaviors.Find<WebGetAttribute>() != null)
  52.         {
  53.             // no change for GET operations
  54.             return base.GetRequestClientFormatter(operationDescription, endpoint);
  55.         }
  56.         else
  57.         {
  58.             WebInvokeAttribute wia = operationDescription.Behaviors.Find<WebInvokeAttribute>();
  59.             if (wia != null)
  60.             {
  61.                 if (wia.Method == "HEAD")
  62.                 {
  63.                     // essentially a GET operation
  64.                     return base.GetRequestClientFormatter(operationDescription, endpoint);
  65.                 }
  66.             }
  67.         }
  69.         if (operationDescription.Messages[0].Body.Parts.Count == 0)
  70.         {
  71.             // nothing in the body, still use the default
  72.             return base.GetRequestClientFormatter(operationDescription, endpoint);
  73.         }
  75.         return new NewtonsoftJsonClientFormatter(operationDescription, endpoint);
  76.     }
  78.     protected override IClientMessageFormatter GetReplyClientFormatter(OperationDescription operationDescription, ServiceEndpoint endpoint)
  79.     {
  80.         if (operationDescription.Messages.Count == 1 || operationDescription.Messages[1].Body.ReturnValue.Type == typeof(void))
  81.         {
  82.             return base.GetReplyClientFormatter(operationDescription, endpoint);
  83.         }
  84.         else
  85.         {
  86.             return new NewtonsoftJsonClientFormatter(operationDescription, endpoint);
  87.         }
  88.     }
  89. }

On to the formatters. I’ll start with the dispatch formatter. As the new formatter was only added for POST operations with at least one parameter, we can safely assume that the messages will not be empty, and the request will be stored in the message body. But the message body is always represented in XML, so in order to support a custom format, we need to either define a mapping between that format and XML (which is what was done internally for supporting JSON in 3.5) – and implement XML readers and writers to support this mapping – or reuse one of the existing formats for which we already have a mapping for. And as in the raw programming model, the raw format (described in the post about message inspectors) is a great candidate for it – we can get the raw bytes from the request (and write raw bytes in the response) and parse them using our custom format. We must ensure, however, that the incoming message actually was read with the raw encoder (by default messages with JSON content type are read with the JSON encoder, we need a custom content type mapper to ensure that they are read as raw messages).

  1. class NewtonsoftJsonDispatchFormatter : IDispatchMessageFormatter
  2. {
  3.     OperationDescription operation;
  4.     Dictionary<string, int> parameterNames;
  5.     public NewtonsoftJsonDispatchFormatter(OperationDescription operation, bool isRequest)
  6.     {
  7.         this.operation = operation;
  8.         if (isRequest)
  9.         {
  10.             int operationParameterCount = operation.Messages[0].Body.Parts.Count;
  11.             if (operationParameterCount > 1)
  12.             {
  13.                 this.parameterNames = new Dictionary<string, int>();
  14.                 for (int i = 0; i < operationParameterCount; i++)
  15.                 {
  16.                     this.parameterNames.Add(operation.Messages[0].Body.Parts[i].Name, i);
  17.                 }
  18.             }
  19.         }
  20.     }
  22.     public void DeserializeRequest(Message message, object[] parameters)
  23.     {
  24.         object bodyFormatProperty;
  25.         if (!message.Properties.TryGetValue(WebBodyFormatMessageProperty.Name, out bodyFormatProperty) ||
  26.             (bodyFormatProperty as WebBodyFormatMessageProperty).Format != WebContentFormat.Raw)
  27.         {
  28.             throw new InvalidOperationException("Incoming messages must have a body format of Raw. Is a ContentTypeMapper set on the WebHttpBinding?");
  29.         }
  31.         XmlDictionaryReader bodyReader = message.GetReaderAtBodyContents();
  32.         bodyReader.ReadStartElement("Binary");
  33.         byte[] rawBody = bodyReader.ReadContentAsBase64();
  34.         MemoryStream ms = new MemoryStream(rawBody);
  36.         StreamReader sr = new StreamReader(ms);
  37.         Newtonsoft.Json.JsonSerializer serializer = new Newtonsoft.Json.JsonSerializer();
  38.         if (parameters.Length == 1)
  39.         {
  40.             // single parameter, assuming bare
  41.             parameters[0] = serializer.Deserialize(sr, operation.Messages[0].Body.Parts[0].Type);
  42.         }
  43.         else
  44.         {
  45.             // multiple parameter, needs to be wrapped
  46.             Newtonsoft.Json.JsonReader reader = new Newtonsoft.Json.JsonTextReader(sr);
  47.             reader.Read();
  48.             if (reader.TokenType != Newtonsoft.Json.JsonToken.StartObject)
  49.             {
  50.                 throw new InvalidOperationException("Input needs to be wrapped in an object");
  51.             }
  53.             reader.Read();
  54.             while (reader.TokenType == Newtonsoft.Json.JsonToken.PropertyName)
  55.             {
  56.                 string parameterName = reader.Value as string;
  57.                 reader.Read();
  58.                 if (this.parameterNames.ContainsKey(parameterName))
  59.                 {
  60.                     int parameterIndex = this.parameterNames[parameterName];
  61.                     parameters[parameterIndex] = serializer.Deserialize(reader, this.operation.Messages[0].Body.Parts[parameterIndex].Type);
  62.                 }
  63.                 else
  64.                 {
  65.                     reader.Skip();
  66.                 }
  68.                 reader.Read();
  69.             }
  71.             reader.Close();
  72.         }
  74.         sr.Close();
  75.         ms.Close();
  76.     }
  78.     public Message SerializeReply(MessageVersion messageVersion, object[] parameters, object result)
  79.     {
  80.         byte[] body;
  81.         Newtonsoft.Json.JsonSerializer serializer = new Newtonsoft.Json.JsonSerializer();
  82.         using (MemoryStream ms = new MemoryStream())
  83.         {
  84.             using (StreamWriter sw = new StreamWriter(ms, Encoding.UTF8))
  85.             {
  86.                 using (Newtonsoft.Json.JsonWriter writer = new Newtonsoft.Json.JsonTextWriter(sw))
  87.                 {
  88.                     writer.Formatting = Newtonsoft.Json.Formatting.Indented;
  89.                     serializer.Serialize(writer, result);
  90.                     sw.Flush();
  91.                     body = ms.ToArray();
  92.                 }
  93.             }
  94.         }
  96.         Message replyMessage = Message.CreateMessage(messageVersion, operation.Messages[1].Action, new RawBodyWriter(body));
  97.         replyMessage.Properties.Add(WebBodyFormatMessageProperty.Name, new WebBodyFormatMessageProperty(WebContentFormat.Raw));
  98.         HttpResponseMessageProperty respProp = new HttpResponseMessageProperty();
  99.         respProp.Headers[HttpResponseHeader.ContentType] = "application/json";
  100.         replyMessage.Properties.Add(HttpResponseMessageProperty.Name, respProp);
  101.         return replyMessage;
  102.     }
  103. }

When the formatter is serializing the reply of the message , it will create a new message using a “raw” body writer, which is a simple implementation of the BodyWriter class. It will then set the body format property to ensure that the raw encoder will be used when converting that message into bytes on the wire.

  1. class RawBodyWriter : BodyWriter
  2. {
  3.     byte[] content;
  4.     public RawBodyWriter(byte[] content)
  5.         : base(true)
  6.     {
  7.         this.content = content;
  8.     }
  10.     protected override void OnWriteBodyContents(XmlDictionaryWriter writer)
  11.     {
  12.         writer.WriteStartElement("Binary");
  13.         writer.WriteBase64(content, 0, content.Length);
  14.         writer.WriteEndElement();
  15.     }
  16. }

The client formatter is similar to the service one. On reply, since it doesn’t support multiple return values (no out/ref support implemented), it simply gets the bytes from the message and feeds them to the JSON.NET deserializer. When serializing the request, the formatter will either simply serialize a single parameter if it’s the only one, or it will wrap it in a JSON object with properties named by the operation parameter name. The last thing it does on serialization is to again set the body format property (to ensure that the raw encoder will be used for that message) and also set the “To” header of the message (which is required for REST messages, since it uses manual addressing on the transport).

  1. class NewtonsoftJsonClientFormatter : IClientMessageFormatter
  2. {
  3.     OperationDescription operation;
  4.     Uri operationUri;
  5.     public NewtonsoftJsonClientFormatter(OperationDescription operation, ServiceEndpoint endpoint)
  6.     {
  7.         this.operation = operation;
  8.         string endpointAddress = endpoint.Address.Uri.ToString();
  9.         if (!endpointAddress.EndsWith("/"))
  10.         {
  11.             endpointAddress = endpointAddress + "/";
  12.         }
  14.         this.operationUri = new Uri(endpointAddress + operation.Name);
  15.     }
  17.     public object DeserializeReply(Message message, object[] parameters)
  18.     {
  19.         object bodyFormatProperty;
  20.         if (!message.Properties.TryGetValue(WebBodyFormatMessageProperty.Name, out bodyFormatProperty) ||
  21.             (bodyFormatProperty as WebBodyFormatMessageProperty).Format != WebContentFormat.Raw)
  22.         {
  23.             throw new InvalidOperationException("Incoming messages must have a body format of Raw. Is a ContentTypeMapper set on the WebHttpBinding?");
  24.         }
  26.         XmlDictionaryReader bodyReader = message.GetReaderAtBodyContents();
  27.         Newtonsoft.Json.JsonSerializer serializer = new Newtonsoft.Json.JsonSerializer();
  28.         bodyReader.ReadStartElement("Binary");
  29.         byte[] body = bodyReader.ReadContentAsBase64();
  30.         using (MemoryStream ms = new MemoryStream(body))
  31.         {
  32.             using (StreamReader sr = new StreamReader(ms))
  33.             {
  34.                 Type returnType = this.operation.Messages[1].Body.ReturnValue.Type;
  35.                 return serializer.Deserialize(sr, returnType);
  36.             }
  37.         }
  38.     }
  40.     public Message SerializeRequest(MessageVersion messageVersion, object[] parameters)
  41.     {
  42.         byte[] body;
  43.         Newtonsoft.Json.JsonSerializer serializer = new Newtonsoft.Json.JsonSerializer();
  44.         using (MemoryStream ms = new MemoryStream())
  45.         {
  46.             using (StreamWriter sw = new StreamWriter(ms, Encoding.UTF8))
  47.             {
  48.                 using (Newtonsoft.Json.JsonWriter writer = new Newtonsoft.Json.JsonTextWriter(sw))
  49.                 {
  50.                     writer.Formatting = Newtonsoft.Json.Formatting.Indented;
  51.                     if (parameters.Length == 1)
  52.                     {
  53.                         // Single parameter, assuming bare
  54.                         serializer.Serialize(sw, parameters[0]);
  55.                     }
  56.                     else
  57.                     {
  58.                         writer.WriteStartObject();
  59.                         for (int i = 0; i < this.operation.Messages[0].Body.Parts.Count; i++)
  60.                         {
  61.                             writer.WritePropertyName(this.operation.Messages[0].Body.Parts[i].Name);
  62.                             serializer.Serialize(writer, parameters[0]);
  63.                         }
  65.                         writer.WriteEndObject();
  66.                     }
  68.                     writer.Flush();
  69.                     sw.Flush();
  70.                     body = ms.ToArray();
  71.                 }
  72.             }
  73.         }
  75.         Message requestMessage = Message.CreateMessage(messageVersion, operation.Messages[0].Action, new RawBodyWriter(body));
  76.         requestMessage.Headers.To = operationUri;
  77.         requestMessage.Properties.Add(WebBodyFormatMessageProperty.Name, new WebBodyFormatMessageProperty(WebContentFormat.Raw));
  78.         HttpRequestMessageProperty reqProp = new HttpRequestMessageProperty();
  79.         reqProp.Headers[HttpRequestHeader.ContentType] = "application/json";
  80.         requestMessage.Properties.Add(HttpRequestMessageProperty.Name, reqProp);
  81.         return requestMessage;
  82.     }
  83. }

Now for testing the formatters. The first thing we need is the content type mapper, to ensure that all incoming requests will be read by the raw encoder. Its implementation is quite simple.

  1. class MyRawMapper : WebContentTypeMapper
  2. {
  3.     public override WebContentFormat GetMessageFormatForContentType(string contentType)
  4.     {
  5.         return WebContentFormat.Raw;
  6.     }
  7. }

Now for the test itself. I’m using a helper method (SendRequest) to send arbitrary HTTP requests to the server, but I’ll skip it here (it’s just setting up HttpWebRequest and displaying the results from HttpWebResponse). The test code sets up a service and adds two endpoints, one “normal” (SOAP) and one JSON.NET enabled

  1. static void Main(string[] args)
  2. {
  3.     string baseAddress = "http://" + Environment.MachineName + ":8000/Service";
  4.     ServiceHost host = new ServiceHost(typeof(Service), new Uri(baseAddress));
  5.     host.AddServiceEndpoint(typeof(ITestService), new BasicHttpBinding(), "soap");
  6.     WebHttpBinding webBinding = new WebHttpBinding();
  7.     webBinding.ContentTypeMapper = new MyRawMapper();
  8.     host.AddServiceEndpoint(typeof(ITestService), webBinding, "json").Behaviors.Add(new NewtonsoftJsonBehavior());
  9.     Console.WriteLine("Opening the host");
  10.     host.Open();
  12.     ChannelFactory<ITestService> factory = new ChannelFactory<ITestService>(new BasicHttpBinding(), new EndpointAddress(baseAddress + "/soap"));
  13.     ITestService proxy = factory.CreateChannel();
  14.     Console.WriteLine(proxy.GetPerson());
  16.     SendRequest(baseAddress + "/json/GetPerson", "GET", null, null);
  17.     SendRequest(baseAddress + "/json/EchoPet", "POST", "application/json", "{\"Name\":\"Fido\",\"Color\":\"Black and white\",\"Markings\":\"None\",\"Id\":1}");
  18.     SendRequest(baseAddress + "/json/Add", "POST", "application/json", "{\"x\":111,\"z\":null,\"w\":[1,2],\"v\":{\"a\":1},\"y\":222}");
  20.     Console.WriteLine("Now using the client formatter");
  21.     ChannelFactory<ITestService> newFactory = new ChannelFactory<ITestService>(webBinding, new EndpointAddress(baseAddress + "/json"));
  22.     newFactory.Endpoint.Behaviors.Add(new NewtonsoftJsonBehavior());
  23.     ITestService newProxy = newFactory.CreateChannel();
  24.     Console.WriteLine(newProxy.Add(444, 555));
  25.     Console.WriteLine(newProxy.EchoPet(new Pet { Color = "gold", Id = 2, Markings = "Collie", Name = "Lassie" }));
  26.     Console.WriteLine(newProxy.GetPerson());
  28.     Console.WriteLine("Press ENTER to close");
  29.     Console.ReadLine();
  30.     host.Close();
  31.     Console.WriteLine("Host closed");
  32. }

And that’s it for the formatter example!


One note that I want to leave here is that it’s not too easy to integrate any new formats in the existing WCF REST pipeline. In the example above I had to deal with formatters, Message objects, take a dependency on a content type mapper, just to be able to use this different serializer. And even after all of this, it’s not completely integrated with the pipeline – UriTemplates aren’t supported, for example. In an upcoming release, however, the WCF team is working hard to make WCF really a great platform for hosting HTTP services, and that includes a new platform (built on top of the current one) for HTTP services specifically. In the new WCF Web API (you can preview the bits on the Codeplex site) implementing such a scenario is a lot simpler, and other features (such as UriTemplate) will just continue to work after the new formatter is plugged in. Glenn Block has posted a formatter that does exactly that on the thread http://wcf.codeplex.com/discussions/255873, you decide which one is easier 🙂

Coming up

Operation selectors.

[Code for this post]

[Back to the index]

Comments (15)

  1. kinjal says:


    I read u r blog ..it’s nice..i think that u r the person who help me to find out the solution about this..

    I have XML files in my one of the project and I have another project in which I have to add the path of that XML Files in web.config file. When we use the path of our local machine its working fine. But for the deployment of the project in the cloud I need to use a relative path.

    What I want to do is add the relative path of the XML files in web.config file of WCF service.and Fetch From there in Class library

    i used


    Which get the Service path bcoz i add the class library refrence into service




    I used All Above..But in o/p i get the relative path of Service not Class..I refer almost post from internet related to relative path but don’t get proper solution.For Last 3 days i m searching about this..

    Will it work in the cloud? How to add the relative path of the file???

    Is there any other way to access those Xml files in cloud ??

    please help me.

    Thanks in advance for your help..

  2. Hi kinjal, the answer for whether it will work "in the cloud" really depends on which provider you have. Some of them will allow you access to the file share, some won't. I'd suggest you to post a question in a general forum (StackOverflow works quite well) with specific details about your problem (language, where you're hosting, ASP.NET version, etc), and likely you'll get some answers.

    Good luck!

  3. Priya says:

    Is there a way to retain the ability to use automatic formatting with the end point  and send either XML or Json in the accept header…and yet, "IF" required format is Json, to encode/decode it using Json.Net? In the example above, it looks like the code won't work if I were to send XML in the "Accept" header to the "Json" specific endpoint (since we've made it Json specific). I know its easier to do with the WebAPI, but am just curious if there's a way to change the default Json serialization in standard WCF.



  4. Hi Priya, that's possible to do – the easiest way would be to wrap the original formatter in your JSON.NET-aware formatter. Then when deserializing the request, first check the content-type. If it's application/json (or text/json), then use the code which does JSON.NET as we have. Otherwise, you can rewrite the message to be read in XML format using the code I have at blogs.msdn.com/…/supporting-raw-requests-for-individual-operations.aspx, then pass it to the original formatter.

  5. Bradley Ward says:

    Why doesn't Microsoft allow us to see any of their implementations of these different extensibility classes? Without seeing how real life, production quality extensions are written, the task of producing your own production quality extensions becomes MUCH harder.

    Being able to see the actual code is one of the HUGE benefits to the open source software movement. You can see the code! And you can get the source code for Java as well. I know that there are a few sections of .Net code where the source can be viewed at least in the debugger. It sure would be nice to be able to see WCF added to the list  of modules for which at least this debugger level of access is provided.

  6. Hi Bradley, I don't work for the WCF team anymore, so I don't know exactly what are their plans regarding open source for the platform. But that's the top (by far) request in the UserVoice page for WCF – aspnet.uservoice.com/…/147206-wcf-web-services – so you can also vote for that request in that page.

    One thing that you can consider using to see the implementation is to use a tool such as Reflector or IL Spy to just open the WCF assemblies and look at their disassembly. I've actually found those tools quite handy exactly to see how some internal features were implemented.

  7. Hi Carlos,

    sorry to bother you about this old post, we've got has a few hundreds services exposed using SOAP with a custom binding.

    Now, a new request was made, to use the current SOAP envelope but with the message body encoded in json, I was under the idea that I could switch the serialization/deserialization process to use json.net maintaining the soap envelope very easily, but I'm having a hard time to make it work.

    I tried to use your example as my basis. We create the end points and set the behaviors and the rest of the configurations programmatically (we don't use any configuration file, we store our settings in a db), we use a a windows service to expose all the services.

    A few questions, is the request feasible? (SOAP envelop with Json body – even in base64 like in your example)

    I tried to use your classes (with minor changes) and include them in our project and create a new end point per service with a different port and a set of behaviors (JsonBehavior – copy of your class, EnableCrossOriginResourceSharingBehavior and JsonEndPointBehavior – just to set a custom message inspector), I used your client with my interfaces and I'm always getting the error:

    Message: The remote server returned an unexpected response: (400) Bad Request

    InnerException.Status: system.net.webexceptionstatus.protocolerror

    InnerException.Response: {System.Net.HttpWebResponse}

    Can you help me? Is there an easier way to do this?

    Thanks for the help a for you posts

  8. Hi Carlos, just to tell that I managed to make everything work, thanks for the example

  9. Vinay Pandey says:

    Hi  – this is a very interesting post, I was wondering if there is anything which be done in the dispatch formatter to deserialise the incoming POST message in case-insensitive manner.

  10. Ron says:

    Hi Carlos,

    Old article, I know, but I hope you are still reading the replies.

    Thanks for your knowledge, it helped me a great deal, but I ran eventually into an issue. I'm using a MessageContract and I can't seem to get the SerializeReply to work.

    I am able to receive incomming JSON requests and deserialize them into my used types, pass them to my service class and 'do my thing', but when I return the response, WCF totally forgets about the JSON.net serializer and keeps using the std serializer for the response. When I decorate my model with [DataContract] instead of [MessageContract], then suddenly the WCF stack get routed through SerializeReply.

    Can you give me a lead?


  11. Jeff says:

    God bless you, Carlos.  =)  Was pullin' my hair out there for a minute.

    I am setting up a WCF service that will be deployed in a Sharepoint application pool, so I don't have any liberties (or ability to tinker) with the web.config.  Using your example here, I was able to setup my own custom WebServiceHostFactory that serializes using JSON.Net, and once I folded in the JSON.Net stuff, all my service methods came straight and I'm able to call them in REST style from my javascript using jQuery.  Essentially, I've rolled my own MVC, but it works under SharePoint without any fancy configuration.

    Thank you.

  12. JeffTheDotNetGuy says:

    ★★★★★  =)

  13. Christopher D. Kissinger says:

    Thanks for this. I needed a wrapped request with 4 parameters, but this code's DeserializeRequest errored with "No token to close. Path ''." at serializer.Deserialize when it Read to the end of the root's first property. Here's my implementation (with some hard-coded serializer settings and obviously not yet prod-ready):

           public void DeserializeRequest(Message message, object[] parameters)


               var jsonSettings = new JsonSerializerSettings()


                   TraceWriter = new Newtonsoft.Json.Serialization.DiagnosticsTraceWriter()


                       LevelFilter = System.Diagnostics.TraceLevel.Verbose


                   DateFormatHandling = this.DateFormatHandling,

                   ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Ignore,

                   NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore



               string messageBody;

               using (MemoryStream mss = new MemoryStream())


                   using (var messageWriter = System.Runtime.Serialization.Json.JsonReaderWriterFactory.CreateJsonWriter(mss))





                       messageBody = Encoding.UTF8.GetString(mss.ToArray());




               var requestJObject = Newtonsoft.Json.Linq.JObject.Parse(messageBody);

               int operationParameterCount = operationDescription.Messages[0].Body.Parts.Count;

               if (operationParameterCount > 0)


                   for (int i = 0; i < operationParameterCount; i++)


                       var parameter = operationDescription.Messages[0].Body.Parts[i];

                       if (requestJObject.Properties().Any(t => t.Name == parameter.Name))


                           var currentParameter = requestJObject[parameter.Name];


                               = JsonConvert.DeserializeObject(









                   parameters[0] = JsonConvert.DeserializeObject(requestJObject.ToString(),





  14. Christopher D. Kissinger says:

    actually, correction: switched the single/multiple parameter count check to match yours, starting at

    1.        if (parameters.Length == 1)

    2.        {

  15. Udeshang Parmar says:

    I am using WCF service default serialization and binding but for one of my call I want to use Jason as my this call is bringing heavy data to client side and want to improve the performance.

    Can I use Jason for operation contract only?

    if yes how ?

Skip to main content