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. }
  6.  
  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.     }
  20.  
  21.     public object DeserializeReply(Message message, object[] parameters)
  22.     {
  23.         return this.inner.DeserializeReply(message, parameters);
  24.     }
  25.  
  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.     }
  36.  
  37.     public void ApplyClientBehavior(OperationDescription operationDescription, ClientOperation clientOperation)
  38.     {
  39.         clientOperation.Formatter = new MyClientFormatter(clientOperation.Formatter);
  40.     }
  41.  
  42.     public void ApplyDispatchBehavior(OperationDescription operationDescription, DispatchOperation dispatchOperation)
  43.     {
  44.     }
  45.  
  46.     public void Validate(OperationDescription operationDescription)
  47.     {
  48.     }
  49. }
  50.  
  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();
  59.  
  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.         }
  65.  
  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:

System.ServiceModel.Dispatcher.OperationInvokerBehavior
MyOperationBehaviorAttribute
System.ServiceModel.OperationBehaviorAttribute
System.ServiceModel.Description.DataContractSerializerOperationBehavior
System.ServiceModel.Description.DataContractSerializerOperationGenerator

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. }
  8.  
  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();
  18.  
  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. }
  18.  
  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. }
  11.  
  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.     }
  29.  
  30.     public Pet EchoPet(Pet pet)
  31.     {
  32.         return pet;
  33.     }
  34.  
  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);
  6.  
  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.         }
  13.  
  14.         foreach (OperationDescription operation in endpoint.Contract.Operations)
  15.         {
  16.             this.ValidateOperation(operation);
  17.         }
  18.     }
  19.  
  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.         }
  27.  
  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.         }
  33.  
  34.         return new NewtonsoftJsonDispatchFormatter(operationDescription, true);
  35.     }
  36.  
  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.     }
  48.  
  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.         }
  68.  
  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.         }
  74.  
  75.         return new NewtonsoftJsonClientFormatter(operationDescription, endpoint);
  76.     }
  77.  
  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.     }
  21.  
  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.         }
  30.  
  31.         XmlDictionaryReader bodyReader = message.GetReaderAtBodyContents();
  32.         bodyReader.ReadStartElement("Binary");
  33.         byte[] rawBody = bodyReader.ReadContentAsBase64();
  34.         MemoryStream ms = new MemoryStream(rawBody);
  35.  
  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.             }
  52.  
  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.                 }
  67.  
  68.                 reader.Read();
  69.             }
  70.  
  71.             reader.Close();
  72.         }
  73.  
  74.         sr.Close();
  75.         ms.Close();
  76.     }
  77.  
  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.         }
  95.  
  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.     }
  9.  
  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.         }
  13.  
  14.         this.operationUri = new Uri(endpointAddress + operation.Name);
  15.     }
  16.  
  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.         }
  25.  
  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.     }
  39.  
  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.                         }
  64.  
  65.                         writer.WriteEndObject();
  66.                     }
  67.  
  68.                     writer.Flush();
  69.                     sw.Flush();
  70.                     body = ms.ToArray();
  71.                 }
  72.             }
  73.         }
  74.  
  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();
  11.  
  12.     ChannelFactory<ITestService> factory = new ChannelFactory<ITestService>(new BasicHttpBinding(), new EndpointAddress(baseAddress + "/soap"));
  13.     ITestService proxy = factory.CreateChannel();
  14.     Console.WriteLine(proxy.GetPerson());
  15.  
  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}");
  19.  
  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());
  27.  
  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!

New WCF Web API

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]

Carlos Figueira
http://blogs.msdn.com/carlosfigueira
Twitter: @carlos_figueira http://twitter.com/carlos_figueira