Part 1 , Part 2, Part 3, Part 4, Part 5, Part 6, Part 7, Part 8
If you are in a hurry and all you want is the code, scroll down to the bottom. ;)
And for the few who are still reading: This is the 9^th and final part of this series, which turned out to be a little bigger than planned. And if you read all parts up to here, you have meanwhile figured out that the extensions that I have presented here are not only about REST and POX but primarily a demonstration of how customizable Indigo is for your own needs.  Indigo – Indigo was really a cool code-name. Just like many folks on the Indigo WCF team it’s a bit difficult for me to trade it for a clunky moniker like WCF, and it seems that this somewhat reflects public opinion. Much less am I inclined to really spell out “Windows Communication Foundation” in presentations, because that doesn’t exactly roll off the tongue like a poem, does it? But, hey, there’s always the namespace name and that doesn’t suck. “Service Model” is what everyone will be using in code. We don’t need three-letter acronyms, or do we?
But I digress. I’ve explained a complete set of extensions that outfit the service model with the ability to receive and respond to HTTP requests with arbitrary payloads and without SOAP envelopes and do so by dispatching to request handlers (method) by matching the request URI and the HTTP method against metadata that we stick on the methods using attributes.
And now I’ll show you the “Hello World!” for the extensions and about the simplest thing I can think of is a web server ;-)  In fact, you already have the complete configuration file for this sample; I showed you that in Part 8.
Since things like “Hello World!” are supposed to be simple and it’s ok not to make that a full coverage test case, we start with the following, very plain contract:

[ServiceContract, HttpMethodOperationSelector] interfaceIMyWebServer {     [OperationContract, HttpMethod("GET", UriSuffix = "/*")]     Message Get(Message msg);            [OperationContract(Action = "*")]     Message UnknownMessage(Message msg); }

By now that should not need much explanation. The Get() method receives all HTTP GET requests on the URI suffix “/*” whereby “*” is a wildcard. In other words, all GET requests go to that method.
The implementation of the service is pretty simple.  I am implementing it as a singleton service that is constructed passing a directory name (path).
The Get() implementation gets the URI of the incoming request from the To header of the message’s Headers collection. (Note that the HTTP transport maps the incoming request’s absolute URI to that header once the encoder has constructed the message.)  

[ServiceBehavior(InstanceContextMode=InstanceContextMode.Single)] publicclassMyWebServer : IMyWebServer {     string directory;     public MyWebServer(string directory)     {         this.directory = directory;     }     publicMessage Get(Message msg)     {         string requestPath = msg.Headers.To.AbsolutePath;         // get the path         if (requestPath.Length > 0 && requestPath[0] == '/')         {             // if the path is just the "/", append "default.htm" as the             // default page.             if (requestPath.Substring(1).Length == 0)             {                 requestPath = "/default.htm";             }             // otherwise check whether a file by the requested name exists             string filePath = Path.Combine(directory, requestPath.Substring(1).Replace('/', '\\'));             if (File.Exists(filePath))             {                 // and return a file message                 returnPoxMessages.CreateFileReplyMessage(filePath, PoxMessages.ReplyOptions.None);             }         }         // if all fails, send a 404         returnPoxMessages.CreateErrorMessage(HttpStatusCode.NotFound);     }         publicMessage UnknownMessage(Message msg)     {         returnPoxMessages.CreateErrorMessage(HttpStatusCode.NotImplemented);     } }

Once we’ve done a few checks on the URIs path portion, we construct a file path from the base directory and the URI path, check whether such a file exists, and if it does we create a message for that file and return it. If we can’t find the resulting file name, we construct a 404 “not found” error message. The UnknownMessage() method receives all requests with HTTP methods other than GET and appropriately returns a 501 “not implemented” message. Web server done.
Well, ok. The actual messages are constructed in a helper class PoxMessages that aids in constructing the most common reply messages. The class is part of the extension assembly code you can download and therefore I just quote the relevant methods that are used above. We’ll start with PoxMessages.CreateErrorMessage(), because that its very simple:

public static Message CreateErrorMessage(System.Net.HttpStatusCode code) {    Message reply = Message.CreateMessage("urn:reply");    HttpResponseMessageProperty responseProperty = newHttpResponseMessageProperty();    responseProperty.StatusCode = code;    reply.Properties.Add(HttpResponseMessageProperty.Name, responseProperty);    return reply; }

We create a plain, empty service model Message, create an HttpResponseMessageProperty instance, set the StatusCode to the status code we want and add the property to the message. Return, done.
The PoxMessages.CreateFileReplyMessage() method is a bit more complex, because it, well, involves opening files. I am not showing you the exact overload that’s used in the above example but the one that’s being delegated to:  

public static Message CreateFileReplyMessage(string fileName, long rangeOffset, long rangeLength, ReplyOptions options) {    string contentType = GetContentTypeFromFileName(fileName);    try    {       FileStream fileStream = newFileStream(fileName, FileMode.Open, FileAccess.Read, FileShare.Read);       if (rangeOffset != -1 && rangeLength != -1)       {          SegmentStream segmentStream = newSegmentStream(fileStream, rangeOffset, rangeLength, true);          returnPoxMessages.CreateRawReplyMessage(segmentStream, contentType, rangeOffset, rangeLength, fileStream.Length, Path.GetFileName(fileName), options);       }       else       {          returnPoxMessages.CreateRawReplyMessage(fileStream, contentType, Path.GetFileName(fileName), options);       }    }    catch    {       returnPoxMessages.CreateNotFoundMessage();    } }

The implementation will first make a guess for the file’s content-type based on the file-name, which is a simple registry lookup with a fallback to application/octet-stream.  Then it’ll try to open the file using a FileStream object. If that works –  ignoring the special case with rangeOffset/rangeLength being set – we delegate to the CreateRawReplyMessage() method:

public static Message CreateRawReplyMessage(Stream stm, string contentType, long rangeOffset, long rangeLength, long totalLength, string streamName, ReplyOptions options) {    PoxStreamedMessage reply = newPoxStreamedMessage(stm, 16384);    HttpResponseMessageProperty responseProperty = newHttpResponseMessageProperty();    if ((options & ReplyOptions.ContentDisposition) == ReplyOptions.ContentDisposition)    {       responseProperty.Headers.Add("Content-Disposition", String.Format("Content-Disposition: attachment; filename=\"{0}\"", streamName));    }     responseProperty.Headers.Add("Content-Type", contentType);    if (rangeOffset != -1 && rangeLength != -1)    {       responseProperty.StatusCode = System.Net.HttpStatusCode.PartialContent;       responseProperty.Headers.Add("Content-Range", String.Format("bytes {0}-{1}/{2}",rangeOffset,rangeOffset+rangeLength,totalLength));       responseProperty.Headers.Add("Content-Length", rangeLength.ToString());    }    else    {         if ((options & ReplyOptions.AcceptRange) == ReplyOptions.AcceptRange)         {             responseProperty.Headers.Add("Content-Range", String.Format("bytes {0}-{1}/{2}", 0, totalLength-1, totalLength));         }         responseProperty.Headers.Add("Content-Length", totalLength.ToString());    }    if ((options & ReplyOptions.NoCache) == ReplyOptions.NoCache)    {       responseProperty.Headers.Add("Cache-Control", "no-cache");       responseProperty.Headers.Add("Expires", "-1");    }    if ((options & ReplyOptions.AcceptRange) == ReplyOptions.AcceptRange)    {       responseProperty.Headers.Add("Accept-Ranges", "bytes");    }     reply.Properties.Add(HttpResponseMessageProperty.Name, responseProperty);    reply.Properties.Add(PoxEncoderMessageProperty.Name, newPoxEncoderMessageProperty(true));    return reply; }

That method takes the stream, wraps it in our PoxStreamedMessage, sets all desired HTTP headers on the HttpResponseMessageProperty, adds the property to the message and lastly adds the PoxEncoderMessagePropertyindicating that we want the encoder to operate in raw binary mode. However, all these helper methods are already part of the library and therefore the application code doesn’t really have to deal with all of that anymore. You just construct the fitting message, stick the content into it and return it.
So now we have a service class and what’s left to do is to host it. For that we need a simple service host with a tiny little twist. Since the ServiceMetadataBehavior that typically gives you the WSDL file and the service information page would conflict with our direct interaction with HTTP, we need to switch it off. We do that by removing it from the list of behaviors before the service is initialized.

public class MyWebServerHost : ServiceHost {     public MyWebServerHost(object instance)         : base(instance)     {     }     protectedoverridevoid OnInitialize()     {         Description.Behaviors.Remove<ServiceMetadataBehavior>();         base.OnInitialize();     } } classProgram {     staticvoid Main(string[] args)     {         string directoryName = args[0];         Console.WriteLine("LittleIndigoWebServer");         if (args.Length == 0)         {             Console.WriteLine("Usage: LittleIndigoWebServer.exe [root path]");             return;         }                 if (!Directory.Exists(directoryName))         {             Console.WriteLine("Directory '{0}' does not exist");             return;         }         Console.WriteLine("Web server starting.");         using (MyWebServerHost host = newMyWebServerHost(newMyWebServer(directoryName)))         {             host.Open();             Console.WriteLine("Web Server running. Press ENTER to quit.");             Console.ReadLine();             host.Close();         }     } }

The rest is just normal business for hosting and setting up a service model service in a console application. We read the first argument from the command-line and assume that’s a directory name. We verify that that is indeed so, construct the service host passing the singleton new’ed up with the directory name. We open the service host and we have the web server listening. The details for how the service is exposed on the network is the job of configuration and binding and, again, exhaustively explained in Part 8.

Below is the downloadable archive that contains two C# projects. Newtelligence.ServiceModelExtensions contains the extension set and LittleIndigoWebServer is the above demo app. The code complies and works with the WinFX November and December CTPs.

If you have installed Visual Studio on drive C: you should be able to run the sample immediately with F5, since the LittleIndigoWebServer project’s debugging settings pass the .NET SDK directory to the application on startup. So if you have that, start the server, and then browse http://localhost:8020/StartHere.htm you get this:

Otherwise, you can just start the server using any directory of your choosing, preferably one with HTML content.

And that’s it. I am happy that I’ve got all of the stuff out. This is probably the most documentation I’ve ever written in one stretch for some public giveaway infrastructure, but I am sure it’s worth it. I will follow up with more examples using these extensions. For instance I will show to use this for actual POX apps (the web server is just spitting out raw data, after all) using RSS, OPML and ASX. Stay tuned.

Oh, and … if you like this stuff I’d be happy about comments, questions, blog mentions and, first and foremost, public examples of other people using this stuff. License is BSD: Use as you like, risk is all yours, mention the creators. Enjoy.

Part 1 , Part 2, Part 3, Part 4, Part 5, Part 6, Part 7

We’ve got all the moving pieces and what’s left is a way to configure the PoxEncoder into bindings and use those to hook a service up to the network and run it.

Bindings? Well, all Indigo (WCF) services need to know their ABC to function. ABC? I’ll quote from my WCF Introduction on MSDN:

A binding is a layered combination of a transport, an encoder and of any additional protocol channels (reliable session, transaction flow, etc.) that you’d like to assemble into a transport stack for exposing a service implementation on a specific endpoint address.

For exposing a HTTP-based RESTish service we need:

A.    The HTTP address to host the service at.

B.     Some binding configuration that tells Indigo’s HTTP transport to use our PoxEncoder.

C.     An implementation of a service-contract that’s configured (using the HttpMethodOperationSelectorSection config extension) or marked-up (with the HttpMethodOperationSelectorAttribute) to use our HttpMethodOperationSelectorBehavior for endpoint address filtering and selecting methods.

I’ve shown you quite a few contract variants in the first parts of this series and therefore I don’t really have to explain the C in too much detail anymore; except: While the A is just a plain HTTP address such as http://www.example.com/service, it’s interesting insofar as this address is, unlike as with SOAP services, really just the common address prefix for the dispatch URIs of the particular service and that there is a split between what is A and what is C.

As I’ve explained, the philosophy behind the contract design of my extensions is around the namespaces that are the basis for forming URIs. Because REST services aren’t simply using HTTP as a transport tunnel as SOAP services do, but rather leverage HTTP as the application protocol it is, the URI is a lot more than just a drop-off point for messages. With REST services, the URI is an expression that has both, addressing (transport) and contract (dispatch) aspects to it and we need to separate those out. A clear distinction between global and local namespaces allows us to do that (And I am going into a bit more detail than I usually would, to further address an objection of Mark Baker, 1^st comment, on my choice of the programming model):

There is a global namespace that’s managed by the global DNS system of which anyone can reserve a chunk for themselves by registering a domain-name. The domain-name provides a self-manageable namespace root of which sub-namespaces (subdomains) can be derived and allocated to specific hosts/services or groups of hosts/services by the domain owners. On the particular host, you can put an application behind a specific port, which might either the default port of your particular application protocol or – diverging from the protocol standard – some other port of your choosing. Each Internet application deployment has therefore at least one unique mapping into this global namespace system.

Any further segmentation of the namespace except the host-name and the port-number are private matters of the application listing to that endpoint. With Indigo self-hosted HTTP services, the listening application is Windows (!) – more precisely it’s the HTTP.SYS kernel listener. For IIS/WAS hosted services, the listening application is IIS (for IIS 5.1 and below) or, again, Windows – through that very listener. At the HTTP.SYS listener, handler processes can register their interest in requests sent to certain sub-namespaces of the global namespace mapping (host/port), which are identified by relative URIs. To be clear: The HTTP.SYS API indeed requires the caller to provide an absolute URI like http://hostname:port/service, but the two main parts (scheme/host/port and path) of that URI are used for different purposes:

·         Global mapping: The hostname and port are used to establish a new listener on that particular port (if there is already a listener it is shared) and to populate the hostname-filter table that’s used to disambiguate requests by the Host header in case the IP address is mapped to multiple DNS host entries.

·         Local mapping: The path information of the URI (the remaining relative URI with scheme, hostname and port stripped) is used as a prefix-matching expression to figure out which handler process shall receive the request and, inside that handler process, to further identify and invoke the appropriate endpoint and handler that deals with the resource that the complete URI path represents.

As indicated, mapping URIs to an endpoint needs to distinguish between how we segment and map a local namespace and how we hook that into the global namespace. Hence, the root for any absolute URIs that’s establishing the mapping into the global namespace shall always be separate from the code and reside in configuration for reasons of flexibility as Mark was rightfully pointing out in his objection, while the shape and mapping of the local namespace is typically very application and use-case specific and might well be partially or entirely hardwired.

·         The Indigo A(ddress)of a REST service implemented with my particular programming model is used to hook a given service (or resource representation manager, if you like) into the global namespace: http://myservice.example.com/. Only to be pragmatic and to allow multiple such services to locally share a particular hostname and port and indeed only as an alternative and workaround to creating a separate DNS entry for each service, that mapping might include a path prefix allowing the local low-level infrastructure to demultiplex requests sent to the same global namespace mapping: http://myservices.example.com/serviceA and http://myservices.example.com/serviceB.

·         The Indigo C(ontract) of a REST service implemented with my particular programming model is used to define the shape of the local namespace that the service owns and which is used to provide access to the representations of the resource-types the service is responsible for.

The following configuration snippet for a simple web-server based on my extensions is illustrating that split:

< services >    < service type = "LittleIndigoWebServer.MyWebServer">       <endpointcontract="LittleIndigoWebServer.IMyWebServer"                 address="http://localhost:8020/"                 binding="customBinding"                 bindingConfiguration="poxBinding"/>    </service> </services>

The address http://localhost:8020/ is how I map the service into the global addressing namespace. The local namespace shape for that particular service is a defined by the layout of the file-system directory from which the service grabs files and returns them. What? You can’t see the directory structure and the resulting URLs from the above mapping? Of course not. It’s a private matter of the service implementation what that the local namespace structure is and it’s up to me what parts I am exposing. If I am nice enough I will give you something on a GET/HEAD request on the root of my local namespace (= global address without any suffix), and if I am not nice you get a 404 and will just have to know what to ask for. The “will have to know” part is contract. It’s an assurance that if you come looking at a particular place in my namespace you will have access to a particular thing. My [HttpMethod] attributes manifest that assurance on Indigo contracts.

That leaves B. Before I got carried away by A and C, I wrote [now a bit annotated] “A binding is a layered combination of a transport, an encoder and of any additional protocol channels (reliable session, transaction flow, etc.) that you’d like to assemble into a transport stack for exposing a service implementation [C] on a specific endpoint address [A].”

Putting together such a binding is not much more work than putting a little text between angle brackets and quotation marks in config as shown in the following snippet:

< customBinding >    < binding name = "poxBinding">       <poxEncoder/>       <httpTransportmapAddressingHeadersToHttpHeaders="true"            maxMessageSize="2048000"maxBufferSize="2048000"manualAddressing="true"           authenticationScheme="Anonymous"transferMode="StreamedResponse"  />    </binding> </customBinding>

I am building a custom binding that’s combining the HTTP transport with a custom binding element config extension I built for the PoxEncoder. It’s that simple. And adding the binding element extension does not require black magic, either. It’s just another XML snippet that maps the extension class to an element name (“poxEncoder”) as you can see in the extensions section of the complete config file:

<?xmlversion=”1.0”encoding=”utf-8” ?> <configuration>    <system.serviceModel>       <extensions>          <bindingElementExtensions>             <addname="poxEncoder"type="newtelligence.ServiceModelExtensions.PoxEncoderBindingExtension, newtelligence.ServiceModelExtensions"/>          </bindingElementExtensions>       </extensions>       <bindings>          <customBinding>         <bindingname="poxBinding">                <poxEncoder/>                <httpTransportmapAddressingHeadersToHttpHeaders="true"                            maxMessageSize="2048000"maxBufferSize="2048000"manualAddressing="true"                            authenticationScheme="Anonymous"transferMode="Streamed"  />             </binding>          </customBinding>       </bindings>       <services>          <servicetype="LittleIndigoWebServer.MyWebServer">             <endpointcontract="LittleIndigoWebServer.IMyWebServer"                     address="http://localhost:8020/"                     binding="customBinding"                     bindingConfiguration="poxBinding"/>          </service>       </services>   </system.serviceModel> </configuration>

The PoxEncoderBindingExtension is a class that is based on System.ServiceModel.Configuration.BindingElementExtensionSection. Whenever the configuration is processed by Indigo, the presence of the “poxEncoder” element in a binding triggers the creation of an instance of the class and if we’d require any configuration attributes (which we don’t), those would be stuffed into the Properties collection.    

using System; using System.ServiceModel.Configuration; using System.ServiceModel; using System.Configuration; namespace newtelligence.ServiceModelExtensions {    publicclassPoxEncoderBindingExtension : BindingElementExtensionSection    {         ///<summary>         /// Initializes a new instance of the <see cref="T:PoxEncoderBindingExtension"/> class.         ///</summary>       public PoxEncoderBindingExtension()       {       }         ///<summary>         /// Creates the binding element.         ///</summary>         ///<returns></returns>       protectedoverrideBindingElement CreateBindingElement()       {          PoxEncoderBindingElement pcc = newPoxEncoderBindingElement();          return pcc;       }         ///<summary>         /// Gets the type of the binding element.         ///</summary>         ///<value>The type of the binding element.</value>       publicoverrideType BindingElementType       {          get          {             returntypeof(PoxEncoderBindingElement);          }       }         ///<summary>         /// Gets the name of the configured section.         ///</summary>         ///<value>The name of the configured section.</value>       publicoverridestring ConfiguredSectionName       {          get          {             return"poxEncoder";          }       }       privateConfigurationPropertyCollection properties;         ///<summary>         /// Gets the collection of properties.         ///</summary>         ///<value></value>         ///<returns>The <see cref="T:System.Configuration.ConfigurationPropertyCollection"></see> collection of properties for the element.</returns>       protectedoverrideConfigurationPropertyCollection Properties       {          get          {             if (this.properties == null)             {                ConfigurationPropertyCollection configProperties = newConfigurationPropertyCollection();                this.properties = configProperties;             }             returnthis.properties;          }       }    } }

Once the configuration information has been read, the extension is asked to create a BindingElement from the acquired information. So these extensions are really just factories for binding elements. The binding element, which can also be used to compose such a binding in code by explicitly adding it to a System.ServiceModel.CustomBinding is shown below:

using System; using System.Collections.Generic; using System.Text; using System.ServiceModel; using System.ServiceModel.Design; using System.ServiceModel.Channels; namespace newtelligence.ServiceModelExtensions {     publicclassPoxEncoderBindingElement : BindingElement, IMessageEncodingBindingElement    {         ///<summary>         /// Clones this instance.         ///</summary>         ///<returns></returns>       publicoverrideBindingElement Clone()       {          returnnewPoxEncoderBindingElement();       }         ///<summary>         /// Creates the message encoder factory.         ///</summary>         ///<returns></returns>       publicMessageEncoderFactory CreateMessageEncoderFactory()       {          returnnewPoxEncoderFactory();       }         ///<summary>         /// Gets the addressing version.         ///</summary>         ///<value>The addressing version.</value>       publicAddressingVersion AddressingVersion       {          get          {             returnAddressingVersion.Addressing1;          }       }         ///<summary>         /// Gets the protection requirements.         ///</summary>         ///<returns></returns>       publicoverride System.ServiceModel.Security.Protocols.ChannelProtectionRequirements GetProtectionRequirements()       {          returnnull;       }         ///<summary>         /// Builds the channel factory.         ///</summary>         ///<param name="context">The context.</param>         ///<returns></returns>       publicoverrideIChannelFactory BuildChannelFactory(ChannelBuildContext context)       {          if (context == null)             thrownewArgumentNullException("context");          context.UnhandledBindingElements.Add(this);          return context.BuildInnerChannelFactory();       }         ///<summary>         /// Builds the channel listener.         ///</summary>         ///<param name="context">The context.</param>         ///<returns></returns>         publicoverrideIChannelListener<TChannel> BuildChannelListener<TChannel>(ChannelBuildContext context)         {             if (context == null)             thrownewArgumentNullException("context");          context.UnhandledBindingElements.Add(this);          return context.BuildInnerChannelListener<TChannel>();       }    } }

Binding elements are typically used to put together client-side (channel factory) or service-side (channel listener) transport stacks. At the bottom is the transport and layered on top of it are security, reliable sessions, transaction flow and all other protocol features you need. Each protocol or feature on the channel/listener level has its own binding element and using those you configure yourself a binding combining the features you need and in the order that they should be applied.

The binding elements for message encoders are a bit different, because they are not contributing their own channel factories or channel listeners into the stack, but rather “only” supply the message encoder for the configured transport.

Whenever a binding is instantiated, Indigo creates a ChannelBuildContext which contains the sequence of the binding elements that shall be stacked onto each other into a channel or listener stack and starts stacking them from top to bottom by invoking the topmost binding element’s BuildChannelListener or BuildChannelFactory method. Once the binding element is done creating its channel factory or channel listener, it invokes BuildInnerChannel[Listener/Factory] on the context to have the binding element underneath do its work. (The context is also used to validate whether combination of the elements yields a functional binding stack, but I won’t go into that here).

Our binding element, however, won’t create a channel factory or listener, but rather put itself into the UnhandledBindingElements collection on the build context and will then just have the context complete the construction work. With putting itself into that collection, the binding element makes itself and its most irresistible feature (you’d also think that if you were an Indigo transport) – the IMessageEncodingBindingElement implementation – visible to the transport and waves its hand that it wants to be used. The transport’s binding element, which is at the bottom of the stack and therefore asked to build its channel factory/listener after our binding element has been invoked, will go look in the UnhandledBindingElements  collection whether a message encoding binding element is advertising itself for use. And if that’s so it will forget all of its defaults and happily embrace and use an encoder created by the factory returned by IMessageEncodingBindingElement.CreateMessageEncoderFactory, which is, in our case, this rather simple class:

using System; using System.Collections.Generic; using System.Text; using System.ServiceModel.Channels; using System.ServiceModel; namespace newtelligence.ServiceModelExtensions {     ///<summary>     ///     ///</summary>    publicclassPoxEncoderFactory : MessageEncoderFactory    {       MessageEncoder encoder;         ///<summary>         /// Initializes a new instance of the <see cref="T:PoxEncoderFactory"/> class.         ///</summary>       public PoxEncoderFactory()       {           encoder = newPoxEncoder();       }          ///<summary>         /// Gets the encoder.         ///</summary>         ///<value>The encoder.</value>         publicoverrideMessageEncoder Encoder       {          get          {             return encoder;          }       }         ///<summary>         /// Gets the message version.         ///</summary>         ///<value>The message version.</value>       publicoverrideMessageVersion MessageVersion       {          get          {             return encoder.MessageVersion;          }       }    } }

Soooooooo….!

If you had actually copied all those classes from Parts 1-8 down into local files and compiled them into an assembly, you’d have all my REST/POX plumbing code by now (except, admittedly, an application-level utility class that helps putting messages together).

But wait … don’t do that. In the next part(s) I’ll give you the code all packed up and ready to compile along with the little web server that we’ve configured here and will also share some code snippets from my TV app … maybe the RSS and ASX pieces?

Part 1 , Part 2, Part 3, Part 4, Part 5, Part 6, Part 7, Part 8, Part 9

Where are we?

·         In Parts 1 and 2, I explained contracts in the REST/POX context and the dispatch mechanisms that we need to enable Indigo to accept and handle REST/POX requests. With that I introduced a metadata extension, the [HttpMethod] attribute that can be used to mark up operations on an Indigo contract with HTTP methods and a URI suffixes that we can dispatch on. I also showed how we can employ a parameter inspector to extract URI-embedded arguments and flow them to the operation in a message property.

·         In Parts 3 and 4, I showed how we use the [HttpMethodOperationSelector] attribute to replace Indigo’s default address filtering and operation selection mechanisms, basically the entire message dispatch mechanism, with our own variants. The SuffixFilter is used to find the appropriate endpoint for an incoming request and the HttpMethodOperationSelectorBehavior  find the operation (method) on that endpoint which shall receive the incoming request message.

·         In Parts 5 and 6, you saw how the PoxEncoder puts outbound envelope-less POX documents onto the wire in its WriteMessage methods and accepts incoming non-SOAP XML requests through its ReadMessage methods and wraps them with an in-memory envelope (“message”) for further processing. I also showed the PoxBase64XmlStreamReader, which is an XML Infoset wrapper for arbitrary binary streams that interacts with the PoxEncoder to allow smuggling any sort of raw binary content through the Indigo infrastructure and onto the wire.

We’re pretty far along already. We’ve got the dispatch mechanisms, we know how to hook the dispatch metadata into the services, we’ve got the wire-encoding – we have most of the core pieces together. In fact, the last two key classes we’re missing (configuration hooks aside) are two specialized message classes that we need to handle incoming requests. In Part 6, you could see that the two ReadMessage overloads of the PoxEncoder delegate all work to the PoxBufferedMessage for the “buffered” transfer-mode overload and to PoxStreamedMessage for the “streamed” transfer mode overload.

ReadMessage is called on an encoder whenever a transport has received a complete message buffer (buffered mode) or has accepted and opened a network stream (streamed mode).

Using streamed mode means very concretely that Indigo will start handling the message even though the message might not have completely arrived. A transport in streaming mode will only do as much as it needs to do in order to deal with the transport-level framing protocol. I use “framing protocol” as a general term for what is done at the transport level to know what the nature of the payload is and where the payload starts and ends. For HTTP, the HTTP transport figures out whether an incoming request is indeed an HTTP request, will read/parse the HTTP headers, and will then layer a stream over the request’s content, irrespective of whether the transfer of that byte sequence has already been completed. This stream is immediately handed off to the rest of the Indigo infrastructure and the transport has done its work by doing so.

Pulling the remaining bytes from that stream is someone else’s responsibility in streamed mode. Whenever a piece of the infrastructure pulls data directly or indirectly from the stream and the data chunk requested is still in transfer, the stream will block and wait until the data is there. The transport’s handling of the framing protocol will typically also take care of chunking and thus make a chunked stream appear to be continuous. When I say “indirect pull” I mean that it may very well be an XmlDictionaryReader layered over an XmlReader layered over the incoming network stream.

The streaming mode is of particular interest for very large messages that may, in an extreme case, be virtually limitless in size. There’s no specification that says that you cannot stick 500 Terabyte or 500 Exabyte worth of data (think 365x24 live 1080i video streams) into a single message. As long as you have some reason to believe that the sender will eventually, in 20 years from now, give you “</soap:Body></soap:Envelope>” to terminate the message, the message can be assumed to be well-formed and complete.

No matter whether you use buffered or streamed mode, the configured encoder’s ReadMessage method is the first place where the read data chunk or the stream goes and that delegates, as shown to our two message classes. So let’s look at them.

We’ll primarily look at the PoxBufferedMessage, which is constructed over the read message buffer in the PoxEncoder like this:

public override Message ReadMessage(ArraySegment<byte> buffer, BufferManager bufferManager) {    returnnewPoxBufferedMessage(buffer, bufferManager); }

The class PoxBufferedMessage is derived from the abstract System.ServiceModel.Message class and implements the base-class’s abstract properties Headers, Properties, and Version and overrides the OnClose(), OnGetReaderAtBodyContents(), and OnWriteBodyContents() virtual methods. Internally, Indigo has several such Message implementations that are each customized for certain scenarios. Implementing own variants of Message is simply another extensibility mechanism that Indigo gives us.

Using System; using System.Collections.Generic; using System.Text; using System.ServiceModel; using System.IO; using System.Xml; using System.Runtime.CompilerServices; using System.ServiceModel.Channels; namespace newtelligence.ServiceModelExtensions {     ///<summary>     /// This class is one of the message classes used by the <see cref="T:PoxEncoder"/>     /// It serves to wrap an unencapsulated data buffer with a message structure.     /// The data buffer becomes the body content of the message.     ///</summary>    publicclassPoxBufferedMessage : Message, IPoxRawBodyMessage    {       MessageHeaders headers = newMessageHeaders(MessageVersion.Soap11Addressing1);       MessageProperties properties = newMessageProperties();       byte[] buffer;       int bufferSize;       BufferManager bufferManager;       Stream body;                 ///<summary>         /// Initializes a new instance of the <see cref="T:PoxBufferedMessage"/> class.         ///</summary>         ///<param name="buffer">The buffer.</param>       public PoxBufferedMessage(byte[] buffer)       {             bufferManager = null;             buffer = buffer;             bufferSize = buffer.Length;       }         ///<summary>         /// Initializes a new instance of the <see cref="T:PoxBufferedMessage"/> class.         ///</summary>         ///<param name="buffer">The buffer.</param>         ///<param name="bufferManager">The buffer manager.</param>         public PoxBufferedMessage(ArraySegment<byte> buffer, BufferManager bufferManager)         {             bufferManager = bufferManager;             bufferSize = buffer.Count;             buffer = bufferManager.TakeBuffer( bufferSize);             Array.Copy(buffer.Array, buffer.Offset, buffer, 0, bufferSize);         }

We can construct instances of the class over a raw byte array or an “array segment” layered over such an array. Array segments are preferred over raw arrays, because their use eases memory management. You can keep a pool of buffers with a common size, even though the actual content is shorter than the buffer size and probably even offset from the lower buffer boundary. If we get a raw byte array we simply adopt it, but if we get an array segment alongside a reference to a buffer manager we take a new buffer from the buffer manager and copy the array segment to that acquired buffer.

///<summary>         /// Called when the message is being closed.         ///</summary>         protectedoverridevoid OnClose()         {             base.OnClose();             if ( bufferManager != null)             {                 bufferManager.ReturnBuffer( buffer);             }                    }

When we close the message and we have acquired it using the buffer manager (which is signaled by the presence of the reference) we duly return it once the message is being closed (or disposed or finalized).

The next two methods are an implementation of the IPoxRawBodyMessage interface that is, you guessed it, defined in my extensions. If the handler method wants to get straight at the raw body content knowing that it doesn’t expect XML, it can shortcut by the whole XmlReader and XML serialization story by asking for the BodyContentType and pull out the raw body data as a stream layered over the buffer:

///<summary>         /// Gets the raw body stream.         ///</summary>         ///<returns></returns>       [MethodImpl(MethodImplOptions.Synchronized)]       publicStream GetRawBodyStream()       {          if ( body == null)          {              body = newMemoryStream( buffer,0, bufferSize,false,true);          }          return body;       }         ///<summary>         /// Gets the content type of the raw message body based on the Content-Type HTTP header         /// contained in the HttpRequestMessageProperty or HttpResponseMessageProperty of this         /// message. The value is null if the type is unknown.         ///</summary>         publicstring BodyContentType         {             get             {                 if (Properties.ContainsKey(HttpRequestMessageProperty.Name))                 {                     return ((HttpRequestMessageProperty)Properties[HttpRequestMessageProperty.Name]).Headers["Content-Type"];                 }                 if (Properties.ContainsKey(HttpResponseMessageProperty.Name))                 {                     return ((HttpResponseMessageProperty)Properties[HttpResponseMessageProperty.Name]).Headers["Content-Type"];                 }                 returnnull;             }         }

There is a bit of caution required using this mechanism, though. Because the message State (Created, Written, Read, Copied, Closed) is controlled by the base-class and cannot be set by derived classes, the message should be considered to be in the State==MessageState.Read after calling the GetRawBodyStream() method. That doesn’t seem to be necessary because we have a buffer here, but for the streamed variant that’s a must. And for the sake of consistency we introduce this constraint here.

The BodyContentType property implementation seems, admittedly, a bit strange at first sight. Even though you won’t see the message properties being populated anywhere inside this class, we’re asking for them and base the content-type detection on their values. That only makes sense when we consider the way messages are being populated by Indigo. As I explained, the first thing that gets called once the transport has a raw data chunk or stream in its hands that it believes to be a message, it invokes the encoder. For incoming requests/messages, the encoder is really serving as the message factory constructing Message-derived instances over raw data. Once the encoder has constructed the message in one of the ReadMessage overloads, the message is returned to the transport. If the transport wants, it can then (and the HTTP transport does) stick properties into that newly created message and then hand it off to the rest of the channel infrastructure for processing and dispatching. Because these extensions are built for REST/POX and therefore have HTTP affinity, that’s precisely what we assume to be happening for the BodyContentType property and the CreateBodyReader() method below. As I already explained in Part 1, the HTTP transport will always add a HttpRequestMessageProperty  to the message and that’s consequently from which we can grab the content-type of the incoming request data.

privateXmlDictionaryReader CreateBodyReader()         {             XmlDictionaryReader reader = null;             /*              * Check whether the message properties indicate that this is a raw binary message.              * In that case, we'll wrap the body with a PoxBase64XmlStreamReader              */             bool hasPoxEncoderProperty = Properties.ContainsKey(PoxEncoderMessageProperty.Name);             if (!(hasPoxEncoderProperty && ((PoxEncoderMessageProperty)Properties[PoxEncoderMessageProperty.Name]).RawBinary))             {                 string contentType = null;                 /*                  * Check for whether either the HttpRequestMessageProperty or the HttpResponseMessageProperty                  * are present. If so, extract the HTTP Content-Type header. Otherwise the content-type is                  * assumed to be text/xml ("POX")                  */                 bool hasRequestProperty = Properties.ContainsKey(HttpRequestMessageProperty.Name);                 bool hasResponseProperty = Properties.ContainsKey(HttpResponseMessageProperty.Name);                 if (hasResponseProperty)                 {                     HttpResponseMessageProperty responseProperty =                       Properties[HttpResponseMessageProperty.Name] asHttpResponseMessageProperty;                     contentType = responseProperty.Headers["Content-Type"];                 }                 elseif (hasRequestProperty)                 {                     HttpRequestMessageProperty requestProperty =                        Properties[HttpRequestMessageProperty.Name] asHttpRequestMessageProperty;                     contentType = requestProperty.Headers["Content-Type"];                 }                 if (contentType == null)                 {                     contentType = "text/xml";                 }                 /*                  * If the content type is text/xml (POX) we will create a plain XmlTextReader for the body.                  */                 if (contentType.StartsWith("text/xml", StringComparison.OrdinalIgnoreCase))                 {                    // do we only have a UTF byte-order mark?                    if (_bufferSize <= 4)                    {                        // create a new reader over a fake infoset and place it on the EndElement                        reader = XmlDictionaryReader.CreateDictionaryReader(                           newXmlTextReader(newStringReader("<no-data></no-data>")));                        reader.Read(); reader.Read();                    }                    else                    {                        reader = XmlDictionaryReader.CreateDictionaryReader(newXmlTextReader(GetRawBodyStream()));                    }                 }             }             /*              * If the content wasn't identified to be POX, we'll wrap it as binary.               */             if (reader == null)             {                 reader = XmlDictionaryReader.CreateDictionaryReader(newPoxBase64XmlStreamReader(GetRawBodyStream()));             }             return reader;         }

The private CreateBodyReader() method that constructs XML readers for the both, the OnGetBodyReaderAtBodyContents() and the OnWriteBodyContents() overrides shown below, uses the same strategy to figure out the content-type of the message and therefore to guess what’s hidden inside the byte-array (or array segment) the message was constructed over. To make the message class useful for the request and response direction, we’ll distinguish there two separate cases here:

·         If the message is a response, the handling method in the user code might have indicated that it wants the encoder to serialize the message onto the wire in “raw binary” mode. The indicator for that is the presence of the PoxEncoderMessageProperty having the RawBinary property set to true. If that is the case, the reader we return is always our PoxBase64XmlStreamReader. The property cannot occur in request messages because the Indigo transports simply don’t know about it.

·         If the message is a request or a response with the mentioned property missing, we will try figuring out the message’s content-type using the described strategy of using the HTTP transport’s message properties. If we can’t figure out a content-type for a response (it’s optional for the responding handler code to supply it), we will assume that the content-type is “text/xml”. If the message is a request we can rely of getting a content-type as long as the underlying transport is Indigo’s HTTP transport implementation. If the content-type is indeed “text/xml” we construct an XmlTextReader over the raw data and return it. If the content-type is anything else, we use our PoxBase64XmlStreamReader wrapper, because we have to assume that the encapsulated data we’re dealing with is not XML.

The OnGetBodyReaderAtBodyContents() and the OnWriteBodyContents() overrides are consequently very simple:

///<summary>         /// Called when the client requests a reader for the body contents.         ///</summary>         ///<returns></returns>       protectedoverrideXmlDictionaryReader OnGetReaderAtBodyContents()       {          XmlDictionaryReader reader = CreateBodyReader();          reader.MoveToContent();          return reader;       }         ///<summary>         /// Called when the client requests to write the body contents.         ///</summary>         ///<param name="writer">The writer.</param>       protectedoverridevoid OnWriteBodyContents(XmlDictionaryWriter writer)       {          XmlDictionaryReader reader = CreateBodyReader();          writer.WriteNode(reader, false);       }

What’s left to complete the message implementation are the compulsory overrides of the abstract properties of Message, for which we have backing fields declared at the top of the class:

///<summary>         /// Gets the message version.         ///</summary>         ///<value>The message version.</value>       publicoverrideMessageVersion Version       {          get          {             returnMessageVersion.Soap11Addressing1;          }       }         ///<summary>         /// Gets the SOAP headers.         ///</summary>         ///<value>The headers.</value>       publicoverrideMessageHeaders Headers       {          get          {             return headers;          }       }         ///<summary>         /// Gets the message properties.         ///</summary>         ///<value>The properties.</value>       publicoverrideMessageProperties Properties       {          get          {             return properties;          }       }     } }

The PoxStreamedMessage is only different from this class insofar as that it doesn’t have the buffer management. The GetRawBodyStream() method immediately returns the encapsulated stream and the remaining implementation is largely equivalent, if not identical (yes, I should consolidate that into a base class). Therefore I am not pasting that class here as code but rather just append as a downloadable file, alongside the declaration of IPoxRawBodyMessage and the twice mentioned and not yet shown PoxEncoderMessageProperty class.

With this, we’ve got all the moving pieces we need to build what’s essentially becoming an Indigo-based, message-oriented web-server infrastructure with a REST-oriented programming model. What’s missing is how we get our encoder configured into a binding so that we can put it all together and run it.

Configuration is next; wait for part 8.

Part 1 , Part 2, Part 3, Part 4, Part 5

I threw a lot of unexplained code at you in Part 5 and that wasn’t really fair.

The PoxEncoder class is a replacement for Indigo’s default TextMessageEncoder class that’s used by the HTTP transport unless you explicitly configure something different. Indigo comes with three built-in encoders, namely:

·          The TextMessageEncoder serializes Indigo’s internal Message into SOAP 1.1 or SOAP 1.2 envelopes using (applies only to the latter) the desired character encodings (UTF-8, UTF-16, etc.) and of course it also deserializes incoming SOAP envelopes into the Indigo representation.

·          The MtomMessageEncoder serializes messages into SOAP 1.2 messages as specified by the MTOM specification, which allows for a much more compact transmission of binary-heavy SOAP envelopes than if you were simply using base64Binary encoded element data. MTOM is a good choice whenever the size of binary content in a SOAP envelope far exceeds the size of the rest of the data. Your mileage may vary, so that’s a thing to measure carefully unless it’s blatantly obvious such as in the case of writing a service for a digital imaging library.

·          The BinaryMessageEncoder serializes messages into SOAP 1.2 envelopes, but does so in a very compact binary format that preserves the XML information set, but is not at all like XML text. The gist of the binary encoding is the assumption that if both communicating parties are implemented with Indigo and share the same contract, the metadata existing at both ends reduces the hints that need to go on the wire. In other words: The binary encoding doesn’t need to throw all  these lengthy XML tag names and namespace names explicitly onto the wire, but can refer to them by pointing to a dictionary that’s identically constructed on both ends. The binary encoding in Indigo is a bit like the modern-day, loosely coupled grand-child of NDR and “midl.exe /Oicf” if you like. What’s important to note about this encoding is that its primary design goal is performance and interoperability is in fact a non-goal. The BinaryMessageEncoder assumes Indigo endpoints. If you don’t like that, you can always use the text encoding, which is designed for interoperability.

Our PoxEncoder here differs from all three Indigo encoders in that it does specifically not serialize SOAP messages, but rather just the body contents of a Message.

In order for you to understand what’s happening here, I’ll pick the most relevant methods and explain them in detail. We will start with the Initialize() method that is invoked by all three constructor overloads:

/// <summary> /// Initializes common properties of the encoder. /// </summary> private void Initialize() {   if (this.MessageVersion.Envelope == EnvelopeVersion.Soap12)   {     // set the aprorpiate media type for SOAP 1.2      this. mediaType = "application/soap+xml";   }   elseif (this.MessageVersion.Envelope == EnvelopeVersion.Soap11)   {     // set the appropriate media type for SOAP 1.1      this. mediaType = "text/xml";   }   // compose the content type from charset and media type   this. contentType = string.Format(CultureInfo.InvariantCulture, "{0}; charset={1}", mediaType, textEncoding.WebName); }

It is required for each MessageEncoder-derived class to implement the abstract properties MediaType, ContentType, and MessageVersion, and therefore we have to initialize the backing fields for these properties properly and return meaningful values even though the PoxEncoder is exactly the “anti-SOAP” encoder. The message version specified in the encoder is relevant for Indigo higher up on the stack, because it needs to know what rules and constraints apply to Message instances as they are constructed and processed. The content type and media types are required by the transports so that they know what content and/or media type to specify as metadata in their transport frame (eg. the Content-Type header in HTTP). If we initialize the encoder with the Soap12 message version, it will consequently report the application/soap+xml media type, even though the encoder doesn’t ever write such envelopes to the wire. You might consider that a bug in the PoxEncoder and you might be right, but it doesn’t really matter. Because any methods can return all sorts of payloads, we will override the content-type on the message-level so that this information has really no effect. I do need to clean this up a little. Later.

Now let’s look at the parts that actually do the work. I will start with the two WriteMessage overloads.

The first overload’s signature is
     public override ArraySegment<byte> WriteMessage(Message msg, int maxMessageSize, BufferManager bufferManager, int messageOffset)
and is invoked by the transport whenever a message must be wire-encoded and the output transfer mode is set to TransferMode.Buffered or TransferMode.StreamedRequest (which implies a buffered response). The second overload’s signature is
    public override void WriteMessage(Message msg, System.IO.Stream stream)
and is invoked by the transport whenever a message must be wire-encoded and the output transfer mode is set of TransferMode.Streamed or TransferMode.StreamedResponse (which implies a streamed response).

The transfer-mode property is configurable on all of the pre-built HTTP bindings and on the <httpTransport> binding element. “Buffered” encoding means that the entire message is encoded at once and written into a buffer, which is then given to the the transport for sending. “Streamed” encoding means that the message is pushed into to a stream, whereby the stream is typically immediately layered directly over the transport. That means that whenever our encoder writes data to that stream, it is immediately pushed to the remote communication partner. The “streamed” mode is the optimal choice for sending very large messages that are, for instance, too big to be reasonably handled as a single memory block. The buffered mode is better (and faster) for compact messages. I’ll dissect the buffered variant first:

public override ArraySegment<byte> WriteMessage(Message msg, int maxMessageSize, BufferManager bufferManager, int messageOffset) {    if (msg.IsEmpty)    {       // if the message is empty (no body defined) the result is an empty       // byte array.       byte[] buffer = bufferManager.TakeBuffer(maxMessageSize);       returnnewArraySegment<byte>(buffer, 0, 0);    }

If the message is empty (that means: the body is empty), we request a buffer from the buffer manager and return an empty slice of that buffer, because this encoder’s output is “nothing” if the body is empty.The BufferManager is an Indigo helper class that manages a pool of pre-allocated buffers and serves to optimize memory management by avoiding the allocation and the discarding of buffers for every message. And encoder should therefore use the buffer manager argument and use it to obtain the buffers backing the array segment that is to be returned. Once the message has been handled by the transport, the transport will return the buffer into the pool.

else    {       // check RawBinary bit in the message property           bool rawBinary = false;           if (msg.Properties.ContainsKey(PoxEncoderMessageProperty.Name))       {          rawBinary = ((PoxEncoderMessageProperty)msg.Properties[PoxEncoderMessageProperty.Name]).RawBinary;       }

If the message is not empty (we have a body), we check whether there is a PoxEncoderMessageProperty present in the message. This property is a plain CLR class that is part of my extensions and has two significant properties: Name is a static, constant string value used as the key for the message properties collection and RawBinary is a Boolean instance value that contains and indicator for whether the encoder shall encode the data as XML or as raw binary data. The Message property collection is a simple dictionary of objects keyed by strings. The properties allow application-level code to interact with infrastructure-level code in the way illustrated by this property. Whenever I want the encoder to use its “raw binary” mode, I add this property to the message and the encoder can pick up the information.

ArraySegment<byte> retval = newArraySegment<byte>();       byte[] buffer = bufferManager.TakeBuffer(maxMessageSize);       if (!rawBinary)       {          // If we're rendering XML data, we construct a memory stream          // over the output buffer, layer an XMLDictionaryWriter on top of it          // and have the message write the body content into the buffer as XML.          // The buffer is then wrapped into an array segment and returned.          MemoryStream stream = newMemoryStream(buffer);          XmlWriterSettings settings = newXmlWriterSettings();          settings.OmitXmlDeclaration = true;          settings.Indent = true;          settings.Encoding = this. textEncoding;          XmlWriter innerWriter = XmlWriter.Create(stream, settings);          XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(innerWriter, false);          msg.WriteBodyContents(writer);          writer.Flush();          retval = newArraySegment<byte>(buffer, 0, (int)stream.Position);       }

Next we take a buffer from the buffer manager and if we’re not in “raw binary” mode, we’ll construct a memory stream over the buffer, construct an XmlDictionaryWriter over that stream and ask the message to render its “body contents” into the writer and therefore into the memory stream and into the buffer. The “body contents” of a message is what would be the child nodes of the <soap:Body> element, if we were using that (but we don’t). Once the body contents have been written, we flush the writer to make sure that all buffered data is committed into the underlying stream and then construct the return value as an array segment over the buffer with the length of the bytes written to the stream.

else       {          // If we're rendering raw binary data, we grab at most 'buffer.Length'          // bytes from the binary content of the base64Binary element (if that          // exists) and return the result wrapped into an array segment.          XmlDictionaryReader dictReader = msg.GetReaderAtBodyContents();          if (dictReader.NodeType == XmlNodeType.Element &&             dictReader.LocalName == "base64Binary")          {             if (dictReader.Read() && dictReader.NodeType == XmlNodeType.Text)             {                int size = dictReader.ReadContentAsBase64(buffer, 0, buffer.Length);                retval = newArraySegment<byte>(buffer, 0, size);             }          }       }       return retval;    } }

If the “raw binary” mode is to be used, we are making a bit of an assumption inside the encoder. The assumption is that the body content consists of a single element named “base64Binary” and that its content is just that: base64 binary encoded content. That is of course the other side of the PoxBase64XmlStreamReader trick I explained in Part 5. For binary data we simply assume here that the body reader is our wrapper class and this is how arbitrary binary data is smuggled through the Indigo infrastructure. The array segment to be returned is constructed by reading the binary data into the buffer and setting the array segment length to the number of bytes we could get from the element content.

The streamed version of WriteMessage is quite different:

public override void WriteMessage(Message msg, System.IO.Stream stream) {     try     {         if (!msg.IsEmpty)         {             // check RawBinary bit in the message property             bool rawBinary = false;             if (msg.Properties.ContainsKey(PoxEncoderMessageProperty.Name))             {                 rawBinary = ((PoxEncoderMessageProperty)msg.Properties[PoxEncoderMessageProperty.Name]).RawBinary;             }             if (!rawBinary)             {                 // If we're rendering XML, we layer an XMLDictionaryWriter over the                 // output stream and have the message render its body content into                 // that writer and therefore onto the stream.                 XmlWriterSettings settings = newXmlWriterSettings();                 settings.OmitXmlDeclaration = true;                 settings.Indent = true;                 settings.Encoding = this. textEncoding;                 XmlWriter innerWriter = XmlWriter.Create(stream, settings);                 XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(innerWriter, false);                 msg.WriteBodyContents(writer);                 writer.Flush();             }

The first significant difference is that if we’re using streams, we will simply ignore empty messages and do nothing with them. In streaming mode, the transport will do any setup work required for  sending a message before invoking the encoder and ready the output network stream so that the encoder can write to it. When the encoder returns, the transport considers the write action done. So if we don’t write to the output stream, there’s no payload data hitting the wire and that happens to be what we want.

If we have data and we’re not in “raw binary” mode, the encoder will construct an XmlDictionaryWriter over the supplied stream and have the message write its body contents to it. That’s all.

Else             {                 // If we're rendering raw binary data, we grab chunks of at most 1MByte                 // from the 'base64Binary' content element (if that exists) and write them                 // out as binary data to the output stream. Chunking is done, because we                 // have to assume that the body content is arbitrarily large. To optimize the                 // behavior for large streams, we read and write concurrently and swap buffers.                 XmlDictionaryReader dictReader = msg.GetReaderAtBodyContents();                 if (dictReader.NodeType == XmlNodeType.Element && dictReader.LocalName == "base64Binary")                 {                     if (dictReader.Read() && dictReader.NodeType == XmlNodeType.Text)                     {                         byte[] buffer1 = newbyte[1024*1024], buffer2 = newbyte[1024*1024];                         byte[] readBuffer = buffer1, writeBuffer = buffer2;                                                 int bytesRead = 0;                         // read the first chunk into the read buffer                         bytesRead = dictReader.ReadContentAsBase64(readBuffer, 0, readBuffer.Length);                         do                         {                             // the abort condition for the loop is that we can't read                             // any more bytes from the input because the base64Binary element is                             // exhausted.                             if (bytesRead > 0 )                             {                                 // make the last read buffer the write buffer                                 writeBuffer = readBuffer;                                 // write the write buffer to the output stream asynchronously                                 IAsyncResult result = stream.BeginWrite(writeBuffer, 0, bytesRead,null,null);                                 // swap the read buffer                                 readBuffer = (readBuffer == buffer1) ? buffer2 : buffer1;                                 // read a new chunk into the 'other' buffer synchronously                                 bytesRead = dictReader.ReadContentAsBase64(readBuffer, 0, readBuffer.Length);                                 // wait for the write operation to complete                                 result.AsyncWaitHandle.WaitOne();                                 stream.EndWrite(result);                             }                         }                         while (bytesRead > 0);                     }                 }             }         }     }     catch     {         // the client may disconnect at any time, so that's an expected exception and absorbed.     } }

In streamed “raw binary” mode things get a bit more complicated. Under these circumstances we assume that the output we are sending is HUGE. The use-case I had in mind when I wrote this is the download of multi-GByte video recordings. Therefore I construct two 1MByte buffers that are used in turns to read a chunk of data from the source body reader (for which we make the same content assumption as for the buffered case: This is believed to be a PoxBase64XmlStreamReader compatible infoset) and asynchronously push the read data into the output stream.

Because it may take a while to get a huge data stream to the other side, a lot of things can happen to the network connection during that time. Therefore the encoder fully expects that the network connection terminates unexpectedly. If that happens, we’ll catch and absorb the network exception and happily return to the caller as if we’re done.

Compared to all the complexity of the WriteMessage  overloads, the respective ReadMessage methods look fairly innocent, simple, and similar:

/// <summary> /// Reads an incoming array segment containing a message and /// wraps it with a buffered message. The assumption is that the incoming /// data stream is <i> not </i> a SOAP envelope, but rather an unencapsulated /// data item, may it be some raw binary, an XML document or HTML form /// postback data. This method is called if the inbound transfer mode of the /// transport is "buffered". /// </summary> /// <param name="buffer"> Buffer to wrap </param> /// <param name="bufferManager"> Buffer manager to help with allocating a copy </param> /// <returns> Buffered message </returns> public override Message ReadMessage(ArraySegment<byte> buffer, BufferManager bufferManager) {    returnnewPoxBufferedMessage(buffer, bufferManager); } ///<summary> /// Reads an incoming stream containing a message and /// wraps it with a streamed message. The assumption is that the incoming /// data stream is <i>not</i> a SOAP envelope, but rather an unencapsulated /// data item, may it be some raw binary, an XML document or HTML form /// postback data. This method is called if the inbound transfer mode of the /// transport is "streamed". ///</summary> ///<param name="stream">Input stream</param> ///<param name="maxSizeOfHeaders">Maximum size of headers in bytes</param> ///<returns>Stream message</returns> publicoverrideMessage ReadMessage(System.IO.Stream stream, int maxSizeOfHeaders) {    returnnewPoxStreamedMessage(stream, maxSizeOfHeaders); }

Both variants take the raw incoming data (whatever it is) and hand it to the PoxStreamMessage class or PoxBufferedMessage class that adopt the buffer or stream as their body content, respectively. I’ll explain those in Part 7.

Happy New Year!

Part 1 , Part 2, Part 3, Part 4

POX means “plain old XML” and I’ve also heard a definition saying that “POX is REST without the dogma”, but that’s not really correct. POX is not really well defined, but it’s clear that the “plain” is the focus and that means typically that folks who talk about “POX web services” explicitly mean that those services don’t use SOAP. You could see POX as an antonym for SOAP.

The design of Indigo (WCF) assumes that all messages that go onto the wire and come from the wire have a shape that is aligned with SOAP. That means that they have a “body” containing the user-defined message payload and a “header” section that contains the out-of-band metadata that helps getting the message from one place to the next, possibly through a chain of intermediaries. Most of the Indigo binding elements and their implementations also assume that those metadata elements (headers) conform to their respective WS-* standard that they are dealing with.

However, Indigo isn’t hard-wired to a specific envelope format. The default “encoders” that are responsible for turning a message into data stream (or a data package) that a transport can throw down a TCP socket or into a message queue (or whatever else) and which are likewise responsible for picking up the data from the wire to turn them into Message objects have two envelope formats baked in: SOAP 1.1 and SOAP 1.2. But that doesn’t mean that you have to use those. If your envelope format were different (there seem to be thousands, I’ll name AdsML [spec] as an example) and that’s what you want to use on the wire, you can assemble a binding that will compose an Indigo transport with your encoder. Moving away from SOAP means, though, that you can’t use the standard implementations of capabilities such as message-level security, reliable delivery, and transaction flow, because all of these are built on the assumption that you are exchanging WS-* headers with the other party and all of these specs depend on the SOAP information model. But if there are comparable specifications that come with your envelope format you can of course write Indigo extensions that you can configure into a binding just like you can compose the default binding elements. It’d be a lot of work to do that, but you’d still benefit greatly from the Indigo architecture per-se.

When we want to use a REST/POX model, our envelope format is quite simple: We don’t really have an envelope.

The idea of POX is that there’s only payload and that out-of-band metadata is unnecessary fluff. The idea of REST is that there is already and appropriate place for out-of-band metadata and that’s the HTTP headers.

In order to make REST/POX work, we therefore need to replace the Indigo default encoder with an encoder that fulfills these requirements:

1.      Extract the message body XML content of any outbound message and format it for the wire as-is and without a SOAP envelope around it and

2.      Accept an arbitrary inbound XML data and wrap it into a Message-derived class so that Indigo can handle it.

Since the use-case in whose context I’ve developed these extensions is a bit more far reaching than POX, but I indeed want to support RESTful access to any data including multi-GByte unencapsulated MPEG recordings I make on my Media PC, I’ve broadened these two requirements a bit and left out the “XML” constraint:

1.      Extract the message bodyXML content of any outbound message and format it for the wire as-is and without a SOAP envelope around it and

2.      Accept an arbitrary inboundXML data and wrap it into a Message-derived class so that Indigo can handle it.

XML aka POX is an interesting content-type to throw around, but it’s by no means the only one and therefore let’s not restrict ourselves too much here. Any content is good.

But then again, Indigo is assuming that all messages flowing through its channels contain XML payloads and therefore we’ve got a bit of a nut to crack when we want to use Indigo for arbitrary, non-XML payloads of arbitrary size. Luckily, XML is just an illusion.

The Indigo Message holds the message body content inside an XmlDictionaryReader (which is an optimized derivation of the well-known XmlReader). To construct a message, you can walk up to the static Message.CreateMessage(string action, XmlDictionaryReader reader) factory method and pass the readily formatted body content as a reader object and the message will happily adopt it. But can we use the XmlReader to smuggle arbitrary binary content into the message so that our own encoder can later unwrap it and put it onto the wire in whatever raw binary format we like? Sure we can! The class below may look a bit like an evil hack, but it’s a perfectly legal construct:

using System; using System.Collections.Generic; using System.Text; using System.Xml; using System.IO; using System.Xml.Schema; namespace newtelligence.ServiceModelExtensions {    publicclassPoxBase64XmlStreamReader : XmlTextReader    {       privateconststring xmlEnvelopeString =            "<base64Binary xmlns:xsi=\"" + XmlSchema.InstanceNamespace + "\" " +            "xmlns:xsd=\"" + XmlSchema.Namespace + "\" " +            "xsi:type=\"xsd:base64Binary\">placeholder</base64Binary>";       Stream innerStream;       /// <summary>       /// Initializes a new instance of the <see cref="T:PoxBase64XmlStreamReader"/> class.       /// </summary>       ///<param name="stream">The stream. </param>       public PoxBase64XmlStreamReader(Stream stream)          : base(newStringReader(xmlEnvelopeString))       {          innerStream = stream;       }       /// <summary>       /// Gets The Common Language Runtime (CLR) type for the current node.       /// </summary>       /// <value></value>       ///<returns>The CLR type that corresponds to the typed value of the node. The default is System.String. </returns>       publicoverrideType ValueType       {           get          {             if (NodeType == XmlNodeType.Text && base.Value == "placeholder")             {                returntypeof(Byte[]);             }              else             {                returnbase.ValueType;             }          }       }           /// <summary>       /// Gets the text value of the current node.       /// </summary>       publicoverridestring Value       {           get          {             if (NodeType == XmlNodeType.Text && base.Value == "placeholder")             {                BinaryReader reader = newBinaryReader(innerStream);                returnConvert.ToBase64String(reader.ReadBytes((int)(reader.BaseStream.Length - reader.BaseStream.Position)));             }             returnbase.Value;          }       }       /// <summary>       /// Reads the content and returns the Base64 decoded binary bytes.       /// </summary>       ///<param name="buffer">The buffer into which to copy the resulting text. This value cannot be null. </param>       ///<param name="index">The offset into the buffer where to start copying the result. </param>       ///<param name="count">The maximum number of bytes to copy into the buffer. The actual number of bytes copied is returned from this method. </param>       /// <returns>       /// The number of bytes written to the buffer.       /// </returns>       publicoverrideint ReadContentAsBase64(byte[] buffer, int index, int count)       {          if (NodeType == XmlNodeType.Text && base.Value == "placeholder")          {             return innerStream.Read(buffer, index, count);          }           else          {             returnbase.ReadContentAsBase64(buffer, index, count);          }       }    } }

The PoxBase64XmlStreamReader is a specialized XML reader reading a fixed info-set constructed from a string that has a “placeholder” in whose place the content of a wrapped data stream is returned “as base64 encoded content”. Of course that latter statement is hogwash. The data is never encoded in base64 anywhere. But the consumer of the reader thinks that it is and that’s really good enough for us here. The XmlReader creates the illusion that the wrapped data stream were the “text” node of a base64Binary typed element and if that’s what the client wants to believe, we’re happy.  The implementation trick here is of course very simple. As long as the reader isn’t hitting the text node with the “placeholder” all work is being delegated to the base class. Once we arrive at that particular node, we change tactics and return the data type (byte[]) and the content of the wrapped stream instead of the “placeholder” string. After that we continue delegating to the base class. If the client asks for the Value of the text node, we are returning a base64 encoded string representation of the wrapped stream which might end up being pretty big. However, if the client is a bit less naïve about the content, it will figure that the data type is byte[] and therefore retrieve the data in binary chunks through the ReadContentAsBase64() method. Let’s assume that the client will be that clever.

It doesn’t take too much imagination talent to do so, because I’ve got the client right here. I used Doug Purdy’s PoxEncoder that he showed at PDC05 as a basis for this and extended it (quite) a bit:

using System; using System.IO; using System.Xml; using System.Text; using System.ServiceModel; using System.ServiceModel.Channels; using System.ServiceModel.Design; using System.Runtime.CompilerServices; using System.ServiceModel.Configuration; using System.Configuration; using System.Globalization; using System.Xml.Schema; using System.Diagnostics; namespace newtelligence.ServiceModelExtensions {     ///<summary>     /// This class is a wire-format encoder for System.ServiceModel that renders     /// only the content (body) of a <see cref="T:Message"/> onto the wire, but not     /// the surrounding SOAP message elements such as the enevlope, the headers or     /// the body element. Likewise, the encoder expects input to be in 'raw', unwrapped     /// form and will wrap it into a message for processing by the System.ServiceModel     /// infrastructure.     ///</summary>     publicclassPoxEncoder : MessageEncoder    {       string contentType;       string mediaType;       Encoding textEncoding;       MessageVersion messageVersion;       ///<summary>       /// Creates a new instance of PoxEncoder       ///</summary>       public PoxEncoder()       {           messageVersion = MessageVersion.Soap11Addressing1;           textEncoding = Encoding.UTF8;          Initialize();       }       ///<summary>       /// Creates a new instance of PoxEncoder       ///</summary>       ///<param name="messageVersion"></param>       public PoxEncoder(MessageVersion messageVersion)       {          this. messageVersion = messageVersion;           textEncoding = Encoding.UTF8;          Initialize();       }       ///<summary>       /// Creates a new instance of PoxEncoder       ///</summary>       ///<param name="textEncoding"></param>       ///<param name="messageVersion"></param>       public PoxEncoder(Encoding textEncoding, MessageVersion messageVersion)       {          this. textEncoding = textEncoding;          this. messageVersion = messageVersion;          Initialize();       }         ///<summary>         /// Initializes common properties of the encoder.         ///</summary>       privatevoid Initialize()       {          if (this.MessageVersion.Envelope == EnvelopeVersion.Soap12)          {                 // set the aprorpiate media type for SOAP 1.2             this. mediaType = "application/soap+xml";          }          elseif (this.MessageVersion.Envelope == EnvelopeVersion.Soap11)          {                 // set the appropriate media type for SOAP 1.1             this. mediaType = "text/xml";          }             // compose the content type from charset and media type          this. contentType = string.Format(CultureInfo.InvariantCulture, "{0}; charset={1}", mediaType, textEncoding.WebName);       }         ///<summary>         /// Gets the content type for the encoder instance         ///</summary>       publicoverridestring ContentType       {          get          {             return contentType;          }       }         ///<summary>         /// Gets the media type for the encoder instance         ///</summary>       publicoverridestring MediaType       {          get          {             return mediaType;          }       }         ///<summary>         /// Gets an indicator for whether a given input content type is         /// supported.         ///</summary>         ///<param name="contentType">ContentType</param>         ///<returns>Indicates whether the content type is supported</returns>         ///<remarks>         /// TODO: This currently returns 'true' for all content types because the         /// encoder isn't locked down in features yet and this easier to debug.         /// The plan is to support at least: application/x-www-form-urlencoded,         /// text/xml, application/soap+xml         ///</remarks>       publicoverridebool IsContentTypeSupported(string contentType)       {          returntrue;       }         ///<summary>         /// Gets the supported message version of this instance         ///</summary>       publicoverrideMessageVersion MessageVersion       {          get          {             return messageVersion;          }       }         ///<summary>         /// Reads an incoming array segment containing a message and         /// wraps it with a buffered message. The assumption is that the incoming         /// data stream is <i>not</i> a SOAP envelope, but rather an unencapsulated         /// data item, may it be some raw binary, an XML document or HTML form         /// postback data. This method is called if the inbound transfer mode of the         /// transport is "buffered".         ///</summary>         ///<param name="buffer">Buffer to wrap</param>         ///<param name="bufferManager">Buffer manager to help with allocating a copy</param>         ///<returns>Buffered message</returns>         publicoverrideMessage ReadMessage(ArraySegment<byte> buffer, BufferManager bufferManager)       {          returnnewPoxBufferedMessage(buffer, bufferManager);       }         ///<summary>         /// Transforms an incoming message into a raw byte array that a transport can         /// literally put on the wire as it is returned. This method is called if the outbound         /// transfer mode of the transport is "buffered".         ///</summary>         ///<param name="msg">Input message</param>         ///<param name="maxMessageSize">Maximum message size to be rendered</param>         ///<param name="bufferManager">Buffer manager to optimize buffer allocation</param>         ///<param name="messageOffset">Offset into the message to render.</param>         ///<returns>Array segment containing the binary data to be put onto the wire by the transport.</returns>         ///<remarks>         ///<para>This method is the "secret sauce" of the the PoxEncoder. Instead of encoding the         /// message in its entirety, this encoder will unwrap the message body and toss out         /// the envelope and all headers. The resulting "raw" message body (everything inside         /// and not including soap:Body) will be written out to the transport.</para>         ///<para>The encoder has an optional, "out of band" argument that is flowing into it         /// as part of the message's Properties. By adding a <see cref="T:PoxEncoderMessageProperty"/>         /// to the <see cref="Message.Properties"/> and setting its <see cref="PoxEncoderMessageProperty.RawBinary"/>         /// property to 'true', you can switch the encoder into its 'raw binary' mode.</para>         ///<para> In 'raw binary' mode, the encoder expects that the only child of the message         /// body element is an element with a local name of "base64Binary" containing base64 encoded         /// binary data. If that is the case, the encoder will read the content of that element         /// and return it (not the XML wrapper) to the transport in binary form. If the content does         /// not comply with this requirement, an empty array is returned.         ///</para>         ///</remarks>       publicoverrideArraySegment<byte> WriteMessage(Message msg, int maxMessageSize, BufferManager bufferManager, int messageOffset)       {          if (msg.IsEmpty)          {             // if the message is empty (no body defined) the result is an empty             // byte array.             byte[] buffer = bufferManager.TakeBuffer(maxMessageSize);             returnnewArraySegment<byte>(buffer, 0, 0);          }          else          {             // check RawBinary bit in the message property                 bool rawBinary = false;                 if (msg.Properties.ContainsKey(PoxEncoderMessageProperty.Name))             {                rawBinary = ((PoxEncoderMessageProperty)msg.Properties[PoxEncoderMessageProperty.Name]).RawBinary;             }             ArraySegment<byte> retval = newArraySegment<byte>();             byte[] buffer = bufferManager.TakeBuffer(maxMessageSize);             if (!rawBinary)             {                // If we're rendering XML data, we construct a memory stream                // over the output buffer, layer an XMLDictionaryWriter on top of it                // and have the message write the body content into the buffer as XML.                // The buffer is then wrapped into an array segment and returned.                MemoryStream stream = newMemoryStream(buffer);                XmlWriterSettings settings = newXmlWriterSettings();                settings.OmitXmlDeclaration = true;                settings.Indent = true;                settings.Encoding = this. textEncoding;                XmlWriter innerWriter = XmlWriter.Create(stream, settings);                XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(innerWriter, false);                msg.WriteBodyContents(writer);                writer.Flush();                retval = newArraySegment<byte>(buffer, 0, (int)stream.Position);             }             else             {                // If we're rendering raw binary data, we grab at most 'buffer.Length'                // bytes from the binary content of the base64Binary element (if that                // exists) and return the result wrapped into an array segment.                XmlDictionaryReader dictReader = msg.GetReaderAtBodyContents();                if (dictReader.NodeType == XmlNodeType.Element &&                   dictReader.LocalName == "base64Binary")                {                   if (dictReader.Read() && dictReader.NodeType == XmlNodeType.Text)                   {                      int size = dictReader.ReadContentAsBase64(buffer, 0, buffer.Length);                      retval = newArraySegment<byte>(buffer, 0, size);                   }                }             }             return retval;          }       }         ///<summary>         /// Reads an incoming stream containing a message and         /// wraps it with a streamed message. The assumption is that the incoming         /// data stream is <i>not</i> a SOAP envelope, but rather an unencapsulated         /// data item, may it be some raw binary, an XML document or HTML form         /// postback data. This method is called if the inbound transfer mode of the         /// transport is "streamed".         ///</summary>         ///<param name="stream">Input stream</param>         ///<param name="maxSizeOfHeaders">Maximum size of headers in bytes</param>         ///<returns>Stream message</returns>       publicoverrideMessage ReadMessage(System.IO.Stream stream, int maxSizeOfHeaders)       {          returnnewPoxStreamedMessage(stream, maxSizeOfHeaders);       }         ///<summary>         /// Transforms an incoming message into a stream that a transport can         /// literally put on the wire as it is filled. This method is called if the outbound         /// transfer mode of the transport is "streamed".         ///</summary>         ///<param name="msg">Input message</param>         ///<param name="stream">Stream to write to</param>         /// /// <remarks>         ///<para>This method is the "secret sauce" of the the PoxEncoder. Instead of encoding the         /// message in its entirety, this encoder will unwrap the message body and toss out         /// the envelope and all headers. The resulting "raw" message body (everything inside         /// and not including soap:Body) will be written out to the transport.</para>         ///<para>The encoder has an optional, "out of band" argument that is flowing into it         /// as part of the message's Properties. By adding a <see cref="PoxEncoderMessageProperty"/>         /// to the <see cref="Message.Properties"/> and setting its <see cref="PoxEncoderMessageProperty.RawBinary"/>         /// property to 'true', you can switch the encoder into its 'raw binary' mode.</para>         ///<para> In 'raw binary' mode, the encoder expects that the only child of the message         /// body element is an element with a local name of "base64Binary" containing base64 encoded         /// binary data. If that is the case, the encoder will read the content of that element         /// and write it (not the XML wrapper) onto the stream in binary form and in at most         /// 1MByte large chunks. If the content does not comply with this requirement, nothing is written.         ///</para>         ///</remarks>         publicoverridevoid WriteMessage(Message msg, System.IO.Stream stream)         {             try             {                 if (!msg.IsEmpty)                 {                     // check RawBinary bit in the message property                     bool rawBinary = false;                     if (msg.Properties.ContainsKey(PoxEncoderMessageProperty.Name))                     {                         rawBinary = ((PoxEncoderMessageProperty)msg.Properties[PoxEncoderMessageProperty.Name]).RawBinary;                     }                     if (!rawBinary)                     {                         // If we're rendering XML, we layer an XMLDictionaryWriter over the                         // output stream and have the message render its body content into                         // that writer and therefore onto the stream.                         XmlWriterSettings settings = newXmlWriterSettings();                         settings.OmitXmlDeclaration = true;                         settings.Indent = true;                         settings.Encoding = this. textEncoding;                         XmlWriter innerWriter = XmlWriter.Create(stream, settings);                         XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(innerWriter, false);                         msg.WriteBodyContents(writer);                         writer.Flush();                     }                     else                     {                         // If we're rendering raw binary data, we grab chunks of at most 1MByte                         // from the 'base64Binary' content element (if that exists) and write them                         // out as binary data to the output stream. Chunking is done, because we                         // have to assume that the body content is arbitrarily large. To optimize the                         // behavior for large streams, we read and write concurrently and swap buffers.                         XmlDictionaryReader dictReader = msg.GetReaderAtBodyContents();                         if (dictReader.NodeType == XmlNodeType.Element && dictReader.LocalName == "base64Binary")                         {                             if (dictReader.Read() && dictReader.NodeType == XmlNodeType.Text)                             {                                 byte[] buffer1 = newbyte[1024*1024], buffer2 = newbyte[1024*1024];                                 byte[] readBuffer = buffer1, writeBuffer = buffer2;                                                                 int bytesRead = 0;                                 // read the first chunk into the read buffer                                 bytesRead = dictReader.ReadContentAsBase64(readBuffer, 0, readBuffer.Length);                                 do                                 {                                     // the abort condition for the loop is that we can't read                                     // any more bytes from the input because the base64Binary element is                                     // exhausted.                                     if (bytesRead > 0 )                                     {                                         // make the last read buffer the write buffer                                         writeBuffer = readBuffer;                                         // write the write buffer to the output stream asynchronously                                         IAsyncResult result = stream.BeginWrite(writeBuffer, 0, bytesRead,null,null);                                         // swap the read buffer                                         readBuffer = (readBuffer == buffer1) ? buffer2 : buffer1;                                         // read a new chunk into the 'other' buffer synchronously                                         bytesRead = dictReader.ReadContentAsBase64(readBuffer, 0, readBuffer.Length);                                         // wait for the write operation to complete                                         result.AsyncWaitHandle.WaitOne();                                         stream.EndWrite(result);                                     }                                 }                                 while (bytesRead > 0);                             }                         }                     }                 }             }             catch             {                 // the client may disconnect at any time, so that's an expected exception and absorbed.             }         }    } }

The encoder shown above fulfills my two requirements and it is aware of the PoxBase64XmlReader trickery. It renders unencapsulated data onto the wire and accepts and wraps unencapsulated data from the wire. Furthernore, it supports buffered messages and it supports Indigo’s streaming mode, which allows sending messages of arbitrary size. What’s still missing in the picture is how we hook the encoder into the binding and how we can control whether the encoder works in “POX mode” rending XML or in “Raw Binary” mode rendering arbitrary data content. I might also have to explain what a PoxStreamedMessage is. I might also have to explain a bit better what the encoder does to begin with ;-)

Well, at least you have the code already, Part 6 comes with the prose. 

Part 1, Part 2, Part 3

The SuffixFilter that I have shown in Part 3 of this little series interacts with the Indigo dispatch internals to figure out which endpoint shall receive an incoming request. If the filter reports true from it’s Match() method, the service endpoint that owns the particular filter is being picked and its channel gets the message. But at that point we still don’t know which of the operations on the endpoint’s contract shall be selected to handle the request.

We’ll take a step back and recap what we have by citing one of the contract declarations from Part 1:

[ServiceContract, HttpMethodOperationSelector] interfaceIMyApp {     [OperationContract, HttpMethod("GET",UriSuffix="/customers/*")]     CustomerInfo GetCustomerInfo();     [OperationContract, HttpMethod("PUT", UriSuffix = "/customers/*")]     void UpdateCustomerInfo(CustomerInfo info);     [OperationContract, HttpMethod("DELETE", UriSuffix = "/customers/*")]     void DeleteCustomerInfo(); }

If we implement this contract on a class and host the service endpoint for it at, say, http://www.example.com/myappthis particular endpoint will only accept requests on http://www.example.com/myapp/customers/*(whereby ‘*’ can really be any string) because our suffix filter that’s being hooked in my the HttpMethodOperationSelectorAttribute and populated with “/customers/*” suffix won’t let any other request pass. Only those requests for which a pattern match can be found when combining an operation’s suffix pattern with the endpoint URI are positively matched by the suffix filter. For a more complex example I’ll let you peek at a (shortened) snippet of one the contracts of the TV server I am working on:

/// <summary> /// Contract for the channel service /// </summary> [ServiceContract(Namespace = Runtime.ChannelServiceNamespaceURI), HttpMethodOperationSelector] publicinterfaceIChannelService {     ///<summary>     /// Gets the default RSS for this channel.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'text/xml' RSS content</returns>     [OperationContract, HttpMethod("GET")]     Message GetRss(Message message);     ///<summary>     /// Gets the channel logo as a raw binary image with appropriate     /// media type, typically image/gif, image/jpeg or image/png     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'image/*' binary content</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/logo")]     Message GetLogo(Message message);     ///<summary>     /// Gets the RSS for "now", which is typically including     /// the next 12 hours of guide data from the current time     /// onward and including currently running shows.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'text/xml' <a href="http://blogs.law.harvard.edu/tech/rss">     /// RSS 2.0</a> content</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/now")]     Message GetRssForNow(Message message);         ...     ///<summary>     /// Gets an ASX media metadata document containing a reference to     /// the live TV stream for this channel and a reference to the     /// HTMLView that provides the UI inside Windows Media Player.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'video/x-ms-asf' <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmplay10/mmp_sdk/asxelement.asp">     /// ASX 3.0</a> content.</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/media")]     Message GetMedia(Message message);     ///<summary>     /// Gets information about the current media session hosted by the provider.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'text/xml' content</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/media/session")]     Message GetMediaSession(Message message);     ///<summary>     /// Gets the "media display envelope". This is an HTML stream that is loaded     /// by Windows Media Player to render an AJAX UI for accessing this service.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with 'text/html' content</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/media/envelope")]     Message GetMediaDisplayEnvelope(Message message);     ///<summary>     /// Gets a media display envelope collateral data element. This method     /// acts as a web-server and serves up binary files or text files referenced     /// by the media display envelope. Requests to this endpoint are HTTP GET     /// requests to the service base URL with the suffix '/media/envelope' with an     /// appended '/' and the file name of the file that is being requested from the     /// service runtime's 'envelope' directory.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message containing a raw binary file with appropriate media type</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/media/envelope/*")]     Message GetMediaDisplayEnvelopeCollateral(Message message);     ///<summary>     /// Gets the detail information for a particular episode     /// in the EPG guide data (linked from RSS) or for a given     /// recording.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message containing 'text/xml' with detail information.</returns>     [OperationContract, HttpMethod("GET", UriSuffix = "/item/?")]     Message GetItemDetail(Message message);     ///<summary>     /// Adds detail information for a particular episode. Concretely this     /// allows adding a recoding job to the episode data that will cause this     /// show to be recorded.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with HTTP 200 OK status code</returns>     [OperationContract, HttpMethod("POST", UriSuffix = "/item/?")]     Message PostItemDetail(Message message);     ///<summary>     /// Deletes some of the item detail information for a particular episode.     /// This is used to cacnel a recording for the episode.     ///</summary>     ///<param name="message">Input message.</param>     ///<returns>Reply message with HTTP 200 OK status code.</returns>     [OperationContract, HttpMethod("DELETE", UriSuffix = "/item/?")]     Message DeleteItemDetail(Message message);     ///<summary>     /// Method receiving all unknown messages sent to this endpoint     ///</summary>     ///<param name="message">The message</param>     ///<returns></returns>     [OperationContract(Action = "*")]     Message HandleUnknownMessage(Message message); }

If you look at the individual operations in the above contract, you’ll see that the suffix filter would – given a base address of http://www.example.com/TV – match requests made on the URIs  http://www.example.com/TV/logo,  http://www.example.com/TV/now, and http://www.example.com/TV/media to name just a few. A special case is the GetRss() operation, which does not have an explicit suffix defined and therefore causes the suffix filter to match on the base address. An important aspect of the suffix filter is that it does not consider the HTTP method (GET, POST). Matching the HTTP method to an operation is the job of the HttpMethodOperationSelectorBehavior, which acts higher up on the endpoint level and picks out the exact method that the call is being dispatched to. The filter is only deciding whether the message is “ours” with respect to the namespace it is targeting.

The HttpMethodOperationSelectorBehavior is hooked into the service endpoint by the HttpMethodOperationSelectorAttribute’s implementation of IContractBehavior that you can look up in Part 3. In BindDispatch(), the dispatcher’s OperationSelector property is set to a new instance of our specialized operation selector. An “operation selector” is a class that takes an incoing request on an endpoint and figures out the proper operation to dispatch to. The default operation selector in Indigo acts according to the SOAP dispatch rules that I explained in Part 1 (see “Figuring out a programming model”).

However, in our REST/POX world that we’re building here we do not have a concept of “SOAP action”, but rather URIs and HTTP methods and therefore the default dispatch mechanism doesn’t take us very far. Hence, we need to replace the operation selection algorithm with our own and we do that by implementing IDispatchOperationSelector:

using System; using System.Collections.Generic; using System.Text; using System.Text.RegularExpressions; using System.ServiceModel; using System.ServiceModel.Configuration; using System.ServiceModel.Channels; namespace newtelligence.ServiceModelExtensions {     ///<summary>     ///     ///</summary>    publicclassHttpMethodOperationSelectorBehavior : IDispatchOperationSelector    {       ContractDescription description;       IDispatchOperationSelector defaultSelector;         ///<summary>         /// Initializes a new instance of the <see cref="T:HttpMethodOperationSelectorBehavior"/> class.         ///</summary>         ///<param name="description">The description.</param>         ///<param name="defaultSelector">The default selector.</param>       public HttpMethodOperationSelectorBehavior(ContractDescription description, IDispatchOperationSelector defaultSelector)       {          this.description = description;          this.defaultSelector = defaultSelector;       }         ///<summary>         /// Selects the operation.         ///</summary>         ///<param name="message">The message.</param>         ///<returns></returns>       publicstring SelectOperation(refMessage message)       {          if (message.Properties.ContainsKey(HttpRequestMessageProperty.Name))          {              HttpRequestMessageProperty msgProp =                  message.Properties[HttpRequestMessageProperty.Name] asHttpRequestMessageProperty;              string baseUriPath = message.Headers.To.AbsolutePath;              List<OperationDescription> operationsWithSuffix = newList<OperationDescription>();              /* Check methods with UriSuffix first. For that we first add               * operation descriptions that have the correct http method into               * a list and then sort that list by the processing order */              foreach (OperationDescription opDesc in description.Operations)              {                  HttpMethodAttribute methodAttribute = opDesc.Behaviors.Find<HttpMethodAttribute>();                  if (methodAttribute != null &&                       String.Compare(methodAttribute.Method, msgProp.Method, true) == 0 &&                       methodAttribute.UriSuffix != null)                  {                      operationsWithSuffix.Add(opDesc);                  }              }              /*               * We are sorting the list based on two criteria:               * a) ProcessingPriority value, and if that's equal:               * b) Length of the UriSuffix expression               */              operationsWithSuffix.Sort(                  delegate(OperationDescription descA, OperationDescription descB)                  {                      HttpMethodAttribute descAAttr = descA.Behaviors.Find<HttpMethodAttribute>();                      HttpMethodAttribute descBAttr = descB.Behaviors.Find<HttpMethodAttribute>();                      int result = descAAttr.Priority.CompareTo(descBAttr.Priority);                      if (result == 0)                      {                          result = Math.Sign(descAAttr.UriSuffix.Length - descBAttr.UriSuffix.Length);                      }                      return result;                  }              );              for (int i = operationsWithSuffix.Count-1; i >= 0; i--)              {                  OperationDescription opDesc = operationsWithSuffix[i];                  HttpMethodAttribute methodAttribute = opDesc.Behaviors.Find<HttpMethodAttribute>();                  // we have a method attribute, the attribute's method value matches                  // the incoming http request and we do have a regex.                  Match match = methodAttribute.UriSuffixRegex.Match(baseUriPath);                  if (match != null && match.Success)                  {                      return opDesc.Name;                  }              }                           /* now check the rest */              foreach (OperationDescription opDesc in description.Operations)              {                  HttpMethodAttribute methodAttribute = opDesc.Behaviors.Find<HttpMethodAttribute>();                  if (methodAttribute != null && methodAttribute.UriSuffixRegex == null)                  {                      // we have a http method attribute and the method macthes the request                      // method: match                      if (String.Compare(methodAttribute.Method, msgProp.Method, true) == 0)                      {                          return opDesc.Name;                      }                  }                  elseif (String.Compare(opDesc.Name, msgProp.Method, true) == 0)                  {                      // we do not have a http method attribute, but the method name                      // equals the http method.                      return opDesc.Name;                  }              }              // No match so far. Now lets find a wildcard method.              foreach (OperationDescription opDesc in description.Operations)              {                  if (opDesc.Messages.Count > 0 &&                      opDesc.Messages[0].Action == "*" &&                      opDesc.Messages[0].Direction == TransferDirection.Incoming)                  {                      return opDesc.Name;                  }              }          }             // No match so far, delegate to the default selector if one is present          if (defaultSelector != null)          {             return defaultSelector.SelectOperation(ref message);          }          return"";       }    } }

As you can see, there is only one method: SelectOperation. The method will only do work on its own if the incoming request is an HTTP request received by Indigo’s HTTP transport. We can figure this out by looking into the message properties and looking for the presence of a property with the name HttpRequestMessageProperty.Name. The presence of this property is required, because that’s the vehicle through which Indigo gives us access to the HTTP method that was used for the request. What we’re looking for sits as an instance string property on HttpRequestMessageProperty.Method.

The algorithm itself is fairly straightforward:

1.      We grab all operations whose HttpMethodAttribute.Method property matches (case-insensitively) the incoming HTTP method string and which have a suffix expression and throw them into a list.

2.      We sort the list by the priority of the attributes amongst each other. I introduced the priorities, because I am allowing wildcards here and I want to allow the suffixes /item/detail and /item/* (read: “anything except detail”) to coexist on the same endpoint, but I need a something other than method order to specify that the match on the concrete expression should be done before the wildcard expression. In absence of priorities and/or in the case of collisions, longer suffixes always trump shorter expressions for matching priority.

3.      We match the sorted list in reverse order (higher priority is better) and return the first operation in the list whose suffix expression matches the incoming messages “To” header (which is the same as the HTTP request URI).

4.      If we don’t have a match, we proceed to iterate over all operations that do not have a suffix and see whether we can find a match solely based on the  HttpMethodAttribute.Method value or, if the HttpMethodAttribute is absent, on the plain method name. (So if the method just named “Get” and there is no attribute, an HTTP GET request will still match).

5.      If we still don’t have a match, we look for the common “all messages without a proper home” method with an OperationContract.Action value of “*”.

6.      And as the very last resort we fall back to the default selector if we have been given one and else we fail out by returning an empty string, which means that there is no match at at all.

If we find a match, we return a string that’s the same as the name of the method we want to dispatch to and Indigo will them promptly do the right thing and call the respective method, either by passing the raw message outright (as in my TV app) or by breaking up the message body using the XmlFormatter or the XmlSerializer and passing a typed message or a set of parameters.

Step 4 is noteworthy insofar as that the [HttpMethod] attributes aren’t strictly necessary. If you name your methods exactly like the HTTP methods they should handle, the operation selector will figure this out. If that’s what you want, you don’t even need the [HttpMethodOperationSelector] attribute, if you choose to add that information in the configuration file instead. To enable that. I’ve built the required configuration class that you can register in the <behaviorExtensions> and map to the <behaviors> section of an endpoint’s configuration. The class is very, very simple:

using System; using System.Collections.Generic; using System.Text; using System.ServiceModel.Configuration; namespace newtelligence.ServiceModelExtensions {    publicclassHttpMethodOperationSelectorSection : BehaviorExtensionSection    {       public HttpMethodOperationSelectorSection()       {       }       protectedoverrideobject CreateBehavior()       {          returnnewHttpMethodOperationSelectorAttribute();       }       publicoverridestring ConfiguredSectionName       {          get          {             return"httpMethodOperationSelector";          }       }    } }

Alright, so where are we? We’ve got dispatch metadata, we’ve got an endpoint dispatch mechanism and we’ve got an operation dispatch mechanism. Furthermore we have a tool that conveniently grabs “parameter segments” from the URI and maps them to an out-of-band collection on the UriArgumentsMessageProperty from where we can conveniently fetch them inside the service implementation.

What we don’t have is POX. We’re still dealing with SOAP messages here. So the next step is to modify the wire encoding in a way that we unwrap the content and throw away the envelope on the way out and that we wrap incoming “raw” data into an envelope to make Indigo happy with incoming requests.

That’s plenty of material for Part 5 and beyond. Stay tuned.

Go to Part 5

Part 1 , Part 2

If you’ve read the first two parts of this series, you should know by now (if I’ve done a reasonable job explaining) about the fundamental concepts of how incoming web service messages (requests) are typically dispatched to their handler code and also understand how my Indigo REST/POX extensions are helping to associate the metadata required for dispatching plain, envelope-less HTTP requests with Indigo service operations using the HttpMethod attribute and how the HttpMethodParameterInspector breaks up the URI components into easily consumable, out-of-band parameters that flow into the service code the UriArgumentsMessageProperty.

What I have not explained is how the dispatching is actually done. There are two parts to that story: Dispatching to services on the listener level (which I will cover here) and dispatching to operations at the endpoint level (which I’ll cover in part 4).

When an HTTP request is received on a namespace that Indigo has registered with HTTP.SYS, the request is matched against a collection of “address filters”. “Registering a namespace” means that if you configure a service-endpoint to listen at the endpoint http://www.example.com/foo, the service-endpoint “owns” that URI.

What’s noteworthy is that if you have an Indigo/WCF application listening to endpoints at http://www.example.com/baz, http://www.example.com/foo and http://www.example.com/foo/bar, the demultiplexing (“demuxing” in short) of the requests is done by Indigo and not by the network stack. HTTP.SYS will push requests from any registered URI namespace of the particular application into the “shared” Indigo HTTP transport and leave it up to Indigo to figure out the right endpoint to dispatch to. And that turns out to be perfect for our purposes.

Whenever an incoming message needs to be dispatched to an endpoint, the message is matched against an address filter table. [For the very nosy: The place where it all happens is in the internal EndpointListenerTable class’s Lookup method, which you could probably look at if you had the right tools, but I didn’t say that.]

By default, the address filter that is used for any “regular” service is the EndpointAddressFilter, which reports a match if the incoming message’s “To” addressing header (which is constructed from the HTTP header information if it’s not immediately contained in the incoming message) is a match for the registered URI. Whether a match is found is dependent on the URI’s port and host-name (controllable by the HostNameComparisonMode in the HTTP binding configuration) and the URIs remaining path, which must be an exact match for the registered service endpoint URI. Since we want to introduce a slightly different dispatch scheme that is based on matching not only on the exact endpoint URI’s path but also on suffixes appended to that URI, we must put a hook into the dispatch mechanism and extend the default behavior. If a method marked up with [HttpMethod(“GET”,UriSuffix=”/bar”)] and the endpoint is hosted at http://www.example.com/foo, we want any HTTP GET request to http://www.example.com/foo/bar to be dispatched to that endpoint and, subsequently, to that exact method.

To infuse that behavior into Indigo, we need to tell it so. If you take a look at Part 2 and at the service contract declarations that I posted there, you will notice the HttpMethodOperationSelector attribute alongside the ServiceContract attribute. That attribute class does the trick:

using System; using System.Collections.Generic; using System.Text; using System.ServiceModel; namespace newtelligence.ServiceModelExtensions {    publicclassHttpMethodOperationSelectorAttribute :                   Attribute, IContractBehavior, IEndpointBehavior    {       publicvoid BindDispatch(                 ContractDescription description,                 IEnumerable<ServiceEndpoint> endpoints,                 DispatchBehavior dispatch,                 BindingParameterCollection parameters)       {          dispatch.OperationSelector =               newHttpMethodOperationSelectorBehavior(description, dispatch.OperationSelector);          foreach (ServiceEndpoint se in endpoints)          {             if (se.Behaviors.Find<HttpMethodOperationSelectorAttribute>() == null)             {                se.Behaviors.Add(this);             }          }                   }       publicvoid BindProxy(                      ContractDescription description,                      ServiceEndpoint endpoint,                      ProxyBehavior proxy,                      BindingParameterCollection parameters)       {       }       publicbool IsApplicableToContract(Type contractType)       {          returntrue;       }       publicvoid BindServiceEndpoint(                      ServiceEndpoint serviceEndpoint,                      EndpointListener endpointListener,                      BindingParameterCollection parameters)       {             SuffixFilter suffixFilter = null;             if (endpointListener.AddressFilter == null ||                 !(endpointListener.AddressFilter isSuffixFilter))             {                 suffixFilter = newSuffixFilter(endpointListener, endpointListener.AddressFilter);                 endpointListener.AddressFilter = suffixFilter;                 ((Dispatcher)endpointListener.Dispatcher).Filter = suffixFilter;             }             else             {                 suffixFilter = endpointListener.AddressFilter asSuffixFilter;             }          foreach (OperationDescription opDesc in serviceEndpoint.Contract.Operations)          {             HttpMethodAttribute methodAttribute = opDesc.Behaviors.Find<HttpMethodAttribute>();             if (methodAttribute != null)             {                if (methodAttribute.UriSuffixRegex != null)                {                   suffixFilter.AddSuffix(methodAttribute.UriSuffixRegex);                }             }          }       }    } }

In the attribute’s implementation of IEndpointBehavior.BindServiceEndpoint, which is invoked by Indigo as the endpoint is initialized (in response to ServiceHost.Open() ), we replace the service’s default endpoint filter with our own SuffixFilter class. Once we’ve done that, we iterate over the HttpMethodAttribute metadata elements that sit on the individual operations/methods in the contract description (this is the actual reason we put them there, see Part 2) and add any suffix we find to the filter’s suffix table. We’ll get back to this class in the next part while to investigate how the “operation selector” is hooked in; let’s investigate the suffix filter first.

using System; using System.Collections.Generic; using System.Text; using System.Text.RegularExpressions; using System.ServiceModel; using System.ServiceModel.Configuration; using System.ServiceModel.Channels; namespace newtelligence.ServiceModelExtensions {     ///<summary>     /// This class implements a specialized ServiceModel address filter     /// that allows matching URL suffixes.     ///</summary>     ///<remarks>     /// The class aggregates an EndpointAddressFilter to helpi with the matching logic.     ///</remarks>     publicclassSuffixFilter : Filter     {         ///<summary>         /// List for the suffixes.         ///</summary>         List<Regex> suffixes;         ///<summary>         /// Original filter that we delegate to if we can't match with this         /// one.         ///</summary>         Filter originalFilter;         ///<summary>         /// The endpoint listener that this filter is applied to         ///</summary>         EndpointListener endpointListener;         ///<summary>         /// The aggregated endpoint address filter         ///</summary>         EndpointAddressFilter addressFilter;         ///<summary>         /// Creates a new instance of SuffixFilter         ///</summary>         ///<param name="endpointListener">EndpointListener this filter is attached to</param>         ///<param name="originalFilter">Original AddressFilter of the EndpointListener</param>         public SuffixFilter(EndpointListener endpointListener, Filter originalFilter)         {             this. suffixes = newList<Regex>();             this. originalFilter = originalFilter;             this. endpointListener = endpointListener;         }         ///<summary>         /// Implements the matching logic         ///</summary>         ///<param name="message">Message that shall be matched</param>         ///<returns>Returns an indicator for whether the message is considered a match</returns>         publicoverridebool Match(Message message)         {             // Workaround for Nov2006 CTP bug. GetEndpointAddress() cannot be             // called on an EndpointListener before the listener is running.             if ( addressFilter == null)             {                 addressFilter = newEndpointAddressFilter( endpointListener.GetEndpointAddress(), false);             }             // check whether we have an immediate match, which means that the message's             // To Header is an excat match for the EndpointListener's address             if ( addressFilter.Match(message))             {                 returntrue;             }             else             {                 // no direct match. Save the original header value and chop off the                 // query portion of the URI.                 Uri originalTo = message.Headers.To;                 string baseUriPath = originalTo.AbsolutePath;                 string baseUriRoot = originalTo.GetLeftPart(UriPartial.Authority);                 // match against the suffix list                 foreach (Regex suffixExpression in suffixes)                 {                     Match match = suffixExpression.Match(baseUriPath);                     if (match != null && match.Success)                     {                         string filterUri = baseUriRoot+baseUriPath.Remove(baseUriPath.LastIndexOf(match.Value));                         message.Headers.To = newUri(filterUri);                         if ( addressFilter.Match(message))                         {                             message.Headers.To = originalTo;                             returntrue;                         }                         message.Headers.To = originalTo;                     }                                        }             }             if ( originalFilter != null)             {                 // of no match has been found up to here, we match against the                 // original filter if that was provided.                 return originalFilter.Match(message);             }             returnfalse;         }         ///<summary>         /// Implements the matching logic by constructing a Message over         /// a MessageBuffer and delegating to the Match(Message) overload         ///</summary>         ///<param name="buffer"></param>         ///<returns></returns>         publicoverridebool Match(MessageBuffer buffer)         {             Message msg = buffer.CreateMessage();             bool result = Match(msg);             msg.Close();             return result;         }         ///<summary>         /// Adds a new suffix to the suffix table         ///</summary>         ///<param name="suffix">Suffix value</param>         publicvoid AddSuffix(Regex suffix)         {             suffixes.Add(suffix);         }         ///<summary>         /// Removes a suffix from the suffix table         ///</summary>         ///<param name="suffix"></param>         publicvoid RemoveSuffix(Regex suffix)         {             suffixes.Remove(suffix);         }     } }

The filter’s filet piece is in the Match method. To finally figure out whether a message is a match, we employ the matching logic of the default EndpointAddressFilter, which deals with matching the host names and the “base URI” at which the service was registered. What the suffix filter does in addition is to match the suffix regex pattern against the incoming message’s “To” header and if that is a match, the suffix is stripped and the remaining URI is matched against the aggregated EndpointAddressFilter. Only if we get a match for the suffix and for the remainder URI, we’ll report a positive match back to the infrastructure by returning true. And in that case and only in that case the service endpoint for which “this” suffix filter was installed and populated gets the request.

For each incoming request, Indigo goes through all registered endpoint address filters and asks them whether they want to service it. And that really means “all”. Indigo will refuse to service the request if two or more filters report ownership of the respective request and will throw a traceable (using Indigo tracing) internal exception that will cause none of the services to be picked due to this ambiguity. In the case of overlapping dispatch namespaces, none is indeed better than “any random”.

Next part: HttpMethodOperationSelectorBehavior

Go to Part 4