July 25, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

The WCF MessageEncoder Decoded

  • June 1, 2007
  • By Jeffrey Juday
  • Send Email »
  • More Articles »

If you've read my earlier articles, you're now familiar with many fundamental aspects of WCF. My first article, "A Primer to Windows Communication Foundation", presented an overview of WCF. My second article, "Building WCF Channels and Bindings", explored Channel construction. In this article, you're going to look at the role and design of a MessageEncoder.

The MessageEncoder

MessageEncoders typically inhabit Transport Channels, although MessageEncoders can be used elsewhere in the Channel Stack. Often, a MessageEncoder's sole purpose is to turn the bytes coming over the wire into a WCF Message Class representation.

Typically, bytes on the wire are a Multipurpose Internet Mail Extensions (MIME) content type. MIME support is a WCF cornerstone. WCF is also built for SOAP-based interactions. In fact, WCF comes equipped to handle multiple SOAP versions and various forms of XML data. MessageEncoders shipping with WCF can build messages from various content and SOAP protocols.

So, with all this support for content and protocols, why would you build your own MessageEncoder?

Why Build Your Own?

As you may have guessed, not all data coming over the wire can be neatly categorized and packaged. Therefore, creating a Message class representation may require some custom handling. Custom handling may entail data decrypting/encrypting or may be supplemented by an additional source.

Other reasons for building your own MessageEncoder is tht you may want to utilize a custom Message class throughout your Channel Stack or you may want to apply a transformation to the incoming data as you create a Message class.

Whatever the case when writing your own MessageEncoder, you will probably apply the same general formula and toolset. Now, you're going to explore the sample code and I'm going to share the formula and toolset for building your own MessageEncoder.

Sample Overview

The sample opens an XML file using the XmlDocument class, translates the XmlDocument into bytes, creates a Message class from the bytes, and then copies the Message class back into another XmlDocument class.

There are some things to consider before you explore the sample.

Aside from illustrating the steps to take building your own MessageEncoder, the sample provides no real practical solution.

Normally, the MessageEncode is embedded inside of a WCF. As stated earlier, normally a MessageEncoder inhabits a Transport Channel class.

Finally, there are many ways to manipulate the bytes coming over the wire and to coerce the data into a Message class. Covering all tools and options is beyond the scope this article, so I'm going to review some of these tools with you before delving into the code.

Tools of the Trade

Manipulating XML data is the realm of the XmlReader and XmlWriter classes. XmlReaders and XmlWriters support all sorts of functionality including:

  • A separate settings class for checking conformance, including whitespace, and specifying a particular encoding
  • Reading, Writing, and efficiently navigating XML
  • Reading XML from Stream classes

XmlDictionalReader and XmlDictionaryWriter classes serve to generate XmlReaders and XmlWriters specifically supporting new features in WCF.

XslCompiledTransformation is a new .NET 2.0 implementation of the .NET Extensible Stylesheet Language Transformation (XSLT) transformations functionality. XSLT serves to transformation a particular XML document into some other representation.

MessageEncoders can work with large amounts of data. Allocating space for large pieces of data can create a bottleneck in an application. So, WCF utilizes a class called MessageBuffer to control and manage pre-allocated memory pools.

MessageEncoders work with .NET Streams. Streams are classes that manipulate a series of bytes residing inside various places (file system, memory, network). All streams have a common base class along with functions specific to their area of specialization.

For more details, see the .NET Framework documentation and the articles listed under Sources at the end of this article.

It's time to delve into the sample and put the tools above to use.

Class Requirements

Like Channels and other classes in WCF, when you build a MessageEncoder you also build an accompanying MessageEncodingBindingElement and MessageEncoderFactory. Also, as with other WCF classes, the binding class handles configuration and the factory class handles creation. Following is the class declaration for TestEncoderFactory.

public class TestEncoderFactory : MessageEncoderFactory
{

Following is the class declaration for TestEncoderBinding.

public class TestEncoderBindingElement :
   MessageEncodingBindingElement
{

As stated earlier, normally the MessageEncoder resides inside the Transport Channel. My WCF Channels and Binding article illustrates how to incorporate a MessageEncoder in the binding and use a MessageEncoder inside a Transport Channel. Typically, the MessageEncoder is created by using the following function calls and properties.

TestEncoderBindingElement elm = new TestEncoderBindingElement();
TestEncoderFactory factory    = new TestEncoderFactory(elm);
RunProgram prog               = new RunProgram();

   ..

prog.Run(factory.Encoder);

MessageEncoder is the base class for all MessageEncoders. MessageEncoder contains overridable versions of the overloaded ReadMessage and WriteMessage functions. Which functions you invoke depend on which style of Message you wish to create; see the Sources section at the end of the article for more information on Messages. You'll see how to implement a few ReadMessage and WriteMessage functions later in the article.

There are also some important overridable properties and functions dealing with the "body" or data portion of a Message class. ContentType, MediaType, and MessageVersion are the key properties. The importance of other functions depends on your implementation of the class.

As stated earlier, a MessageEncoder turns bytes on the wire to Message class. Look at how this is done.





Page 1 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel