A previous post introduced the HTTP core classes (HttpRequestMessage, HttpResponseMessage and HttpMessageHandler) and described the HttpClient class in detail.

This post addresses HTTP message’s content manipulation , and is based on the Web API Preview 6 distribution. Some links point to the MSDN preliminary 4.5 documentation, while others point to the Web API Preview 6 source code; so expect discrepancies. Notice that this post is based on preview code and documentation; the final .NET 4.5 classes may be different of what is described here.

The HttpContent class

The content of both request and response messages is access via the Content property, of type HttpContent.

The HttpContent class contains a Headers property, with the content related HTTP headers (e.g. Content-Language, Content-Type, Last-Modified).

It also contains a set of ReadAsXxx methods for asynchronously accessing the content body:

• Task<Stream> ReadAsStreamAsync()
• Task<byte[]> ReadAsByteArrayAsync()
• Task<string> ReadAsStringAsync()

Creating new content

Reading the message raw content, as a byte sequence or as a string, is accomplished using one of the above methods. However, creating new content involves a hierarchy of concrete classes, rooted at the abstract HttpContent class.

Each one of those classes support a specific type of content or content source. For instance, producing a string based content is accomplished by creating a StringContent instance, parameterized with the string content, the character encoding, and the media type.

Typed Content

The System.Net.Http namespace also contains a ObjectContent class for representing strongly typed content, i.e., content based on a strongly typed object.

As depicted in the following diagram, the ObjectContent derives from HttpContent.  There is also a ObjectContent<T> deriving from ObjectContent, which uses a generic parameter instead of a Type instance to represent the content’s type.

The ObjectContent is used differently when reading content or producing content.

Reading strongly typed content

When reading strongly typed content, an ObjectContent instance is created from a HttpContent and a MediaTypeFormatter is used to convert the HttpContent’s stream into the ObjectContent’s object.

The HttpContentExtensionMethods class contains extension methods to do this

For instance, the ReadAsAsync method performs the following

public static Task ReadAsAsync(this HttpContent content)
{
    if (content == null)
    {
        throw new ArgumentNullException("content");
    }
    return BuildObjectContent(content).ReadAsAsync();
}

private static ObjectContent BuildObjectContent(HttpContent content)
{
    ObjectContent objectContent = content as ObjectContent;
    if (objectContent == null)
    {
        objectContent = new ObjectContent(content);
    }
    return objectContent;
}

Note that reading strongly typed content involves two contents:

• The original message content, exposed as a byte stream.
• The object content, containing an object obtained from the above stream.

Producing strongly typed content

Producing strongly typed content is simpler: just create a ObjectContent (or ObjectContent<T>) instance, passing in the object. Since, ObjectContent derives from HttpContent, this new instance can be directly used as a message content. Internally, a MediaTypeFormatter is used to convert from the typed object into a stream (e.g. when a request message is serialized “to the wire”).

Notice that the MediaTypeFormatter class is used for bidirectional conversion:

• From a byte stream into a typed object.
• From a typed object into a byte stream.

This class will be the subject of a future post.

Final remarks

• Abstract HttpContent base class for representing HTTP message content. Contains a set of methods for reading the content’s body as a byte sequence or a string.
• Concrete HttpContent-derived classes for creating content.
• ObjectContent and ObjectContent<T> classes for reading and creating HTTP message body content from strongly typed objects.

Introduction

The HttpClient class is the .NET (yet another) new client for the HTTP protocol, similar in purpose to HttpWebRequest and WebClient. It is being introduced with .NET 4.5, however there is also an implementation for .NET 4.0 associated with Web API (both source code and NuGet package).

The HttpClient class should not be viewed in isolation or as just a replacement for WebClient. It is part and takes advantage of a set of new classes for the HTTP protocol, present in the System.Net.Http namespace, which are the subject of the next section.

Core HTTP Abstractions

The HTTP protocol is an application level request-response protocol that operates by exchanging messages. The new HttpRequestMessage and HttpResponseMessages framework classes are used to represent these messages. A previous post described these classes on the Web API context. However, they are used outside of that context, namely on the client side.

The computation that produces response messages, given request messages, is represented by the abstract HttpMessageHandler class. To avoid blocking the calling thread, this computation signature is asynchronous, that is, a Task<HttpResponseMessage> is returned instead of a HttpResponseMessage. The “WCF Web API–Message Handlers” post described this new class in the Web API context. However this new class is not used exclusively by the Web API. Namely, similarly to HttpRequestMessage and HttpResponseMessage, this new class is in the System.Net.Http and not on a Web API namespace.

Frequently, messages handlers delegate the response computation to other handlers. Consider, for example, a caching intermediary. If a response to a request can be produced from cached information, then the caching intermediary produces the response directly. Otherwise, the caching component forwards the request message to another handler and caches the response information.

The class DelegatingHandler is used to represent this particular kind of response computation, where the forwarding handler reference is stored on an InnerHandler property.

HttpClient Architecture

The HttpClient class is used to create HTTP request messages, manage the request-response process and extract the response’s content. However, it delegates the actual sending of the request and the asynchronous response reception to a message handler.

Given the usage of a message handler, the HttpClient class may seem redundant. Namely, it is possible to explicitly create a request and use a message handler to obtain a response. However, the HttpClient class adds some relevant functionality:

• Set of helper methods that create requests and also process the responses (e.g. public Task<string> GetStringAsync(string requestUri)).
• Definition of a default header set, that is applied to all sent messages (DefaultRequestHeaders property).
• Timeout and cancellation management (e.g. Timeout property and CancelPendingRequests() method).

The .NET framwork provides two message handlers classes, that can be used with the HttpClient for sending requests: the HttpClientHandler class and the WebRequestHandler class. They both use the old HttpWebRequest internally. The major difference is that WebRequestHandler exposes HttpWebRequest functionality that isn’t available in all platforms (e.g. the Pipelined property is not available on Silverlight). On the other hand, HttpClientHandler should be usable on all platforms.

The handler used by a HttpClient instance is defined in its constructor. If  absent, a HttpClientHandler instance is used by default.
A common technique is to explicitly create a client handler (e.g. HttpWebRequest), then explicitly set some of its properties and finally use it to create a HttpClient instance. Darrel’s  Windows authentication example  is an example of this technique.

The following diagram presents the relation between these classes.

Note that this architecture allows the composition of intermediary delegating handlers (e.g. client side caching), resulting in a handler pipeline.

Conclusions

In conclusion,

• The new HttpClient class for client side HTTP processing, which is a part of the new System.Web.Http namespace.
• Architecture based on message handlers.
• Two concrete handlers:   HttpClientHandler and WebRequestHandler.

The goal is to have an attribute to annotate operations with authorization requirements, such as the illustrated by the following excerpt.

[ServiceContract]
class TheService
{
    [Authorize("Alice")]
    [WebGet(UriTemplate="")]
    HttpResponseMessage Get(...)
    {
		...
    }
}

Notice the [Authorize(“Alice”)] requiring the request’s user to have the “Alice” identity name.

WCF Web API doesn’t have MVC’s filters. However, it is possible to have a similar behavior using operation handlers. The following figure shows the overall idea.

• The EnableAuthorizeAttribute configuration extension method checks if the operation’s description contains any AuthorizeAttribute. If so, it adds a AuthorizeOperationHandler instance to the operation handler pipeline. This instance receives the user identity extracted from the AuthorizeAttribute.
• The AuthorizeOperationHandler declares one input parameter, of type IPrincipal. During the request processing, this handler checks if the input principal has the same identity as the one extracted from the AuthorizeAttribute. If not, it terminates the request before it reaches the operation, by throwing an HttpResponseException.
• Notice that the AuthorizeOperationHandler is completely decoupled from the authentication process. The authorization’s only dependency is on a principal injected as a parameter.
• If the operation doesn’t have a AuthorizeAttribute, then no AuthorizationOperationHandler is added to its pipeline.
• Notice that the end developer only has to annotate the operations with the AuthorizeAttribute and call the EnableAuthorizeAttribute over the configuration, to enable this behavior.

Finally, the (draft) code is available at https://github.com/pmhsfelix/WcfWebApi.Preview5.Explorations.

Operation parameters

On a WCF Web API operation, the URI template variables can be injected as operation’s parameters. The following code excerpt shows a typical example, where the resource identifier (an integer) is obtained from the URI and used as a parameter.

[WebGet(UriTemplate = "{id}")]
public HttpResponseMessage<Contact> Get(int id){...}

As stated in a previous post, these parameters are retrieved from the URI template match result and added into the operation parameter collection by the UriTemplateHandler handler. However, this handlers outputs these parameters as strings. What if the operation expects a different type, such as the integer id used in the above example? Web API runtime knows how to convert these strings into other types, such as integers. However it doesn’t support user-defined types. For instance, consider the following example, using the user-defined AComplexType and AnotherComplexType types.

class AComplexType
{
    public string Value { get; set; }
}
class AnotherComplexType
{
    public int Value { get; set; }
}

[WebGet(UriTemplate = "{prm1}/{prm2}")]
HttpResponseMessage Get(AComplexType prm1, AnotherComplexType prm2)
{
...
}

How is it possible to define the conversion from string into AComplexType and AnotherComplexType, and have it done before the operation is called?

One way of doing this is by using custom operation handlers that:

• receives prm1 and prm2 as strings;
• outputs them as AComplexType and AnotherComplexType.

The following handler does exactly this for a generic T type:

public class ParameterConversionOperationHandler<T> : HttpOperationHandler
{
    private readonly HttpOperationDescription _desc;
    private readonly Func<string, T> _conv;

    public ParameterConversionOperationHandler(HttpOperationDescription desc, Func<string, T> conv)
    {
        _desc = desc;
        _conv = conv;
    }

    protected override IEnumerable<HttpParameter> OnGetInputParameters()
    {
        return _desc.InputParameters
            .Where(prm => prm.ParameterType == typeof(T))
            .Select(prm => new HttpParameter(prm.Name, typeof(string)));
    }

    protected override IEnumerable<HttpParameter> OnGetOutputParameters()
    {
        return _desc.InputParameters
            .Where(prm => prm.ParameterType == typeof(T));
    }

    protected override object[] OnHandle(object[] input)
    {
        var res = new object[input.Length];
        for (var i = 0; i < input.Length; ++i)
        {
            res[i] = _conv(input[i] as string);
        }
        return res;
    }
 }

• The constructor receives a Func<string, T>, i.e. a function that converts a string into a T.
• The OnGetInputParameters finds all the operation’s parameters that have type T and returns them as string input parameters. This means that the Web API runtime will input string parameters into the handler, when processing a request.
• Finally, the OnHandle method uses the conversion function (Func<string,T>) to convert all the input string values into T output values.

Handler registration

The final step is to add an instance of this handler, into the request handlers collection, for each custom type T that we want to be converted. One way of achieving this is by extending  the new Preview 5 configuration model. The following code fragment shows its usage

var config = new HttpConfiguration()
                .UseParameterConverterFor<AComplexType>(
                    s => new AComplexType {Value = s.ToUpper()})
                .UseParameterConverterFor<AnotherComplexType>(
                    s => new AnotherComplexType {Value = Int32.Parse(s)+1});

using (var host = new HttpServiceHost(typeof(TheService), config, "http://localhost:8080/"))
{
    ...
}

The UseParameterConverterFor is a HttpConfiguration extension method, receiving the target type T and the conversion function,  which registers the required operation handler.

public static class ParameterConversionExtensions
{
    public static HttpConfiguration UseParameterConverterFor<T>(
	    this HttpConfiguration cfg, Func<string, T> conv)
    {
        cfg.AddRequestHandlers((coll, ep, desc) =>
            {
                if (desc.InputParameters.Any(p => p.ParameterType == typeof (T)))
                {
                    coll.Add(new ParameterConversionOperationHandler<T>(desc, conv));
                }
            });
        return cfg;
    }
}

Note the conditional addition to the handlers collections: the handler is only added if the operation has at least one parameter of type T.

This extension method uses another HttpConfiguration extension method: AddRequestHandlers.

public static class HttpConfigurationExtensions
{
    public static HttpConfiguration AddRequestHandlers(
	    this HttpConfiguration conf, 
        Action<Collection<HttpOperationHandler>, ServiceEndpoint, HttpOperationDescription> requestHandlerDelegate)
    {
        var old = conf.RequestHandlers;
        conf.RequestHandlers = old == null ? requestHandlerDelegate :
                                        (coll, ep, desc) =>
                                        {
                                            old(coll, ep, desc);
                                            requestHandlerDelegate(coll, ep, desc);
                                        };
        return conf;
    }
}

This new method adds the registration of a new configuration action without removing the ones that may already be defined, i.e., allows for the composition of multiple actions by independent extensions.

Concluding remarks

Some concluding remarks:

• Despite all the code shown on this post the user only has to use the AddParameterConverterFor configuration extension method. The remaining code is infra-structure that only has to written once.
• The code is available at: https://github.com/pmhsfelix/WcfWebApi.Preview5.Explorations

In this post, I describe message handlers in more detail, presenting some examples and a set of external resources on this subject.

Message handlers

Message handlers are a WCF Web API extensibility point located after a HttpRequestMessage is retrieved from the transport channel but before this message is dispatched to an operation, as shown in the following diagram

Message handlers are also located before the operation handlers. This has several consequences:

• The same message handler instance is used for all the operations, i.e., all request URIs and HTTP methods. Namely, the handler doesn’t have access to the dispatching result – the final operation. However, there are different message handler instances per endpoint.
• The message handler only has access to the request message and not to the operation’s parameters.

Message handlers use a “russian-doll” model, also used by other frameworks:

• On initialization, each message handler receives a reference to a inner handler.
• On request processing, each message handler receives the request and is responsible to produce a response, eventually delegating that task to the inner handler (in Preview 4 message handlers are still called delegating handlers).

However, message handlers don’t use a synchronous model. Instead, they use an asynchronous model, based on the Task<T> class: instead of returning a HttpResponseMessage, a message handler must return a Task<HttpResponseMessage>. This means that message handlers are an adequate extension point to insert lengthy I/O requests.

On Preview 4, a message handler is a class that must derive from DelegatingChannel and overrides the SendAsync method.

Example: Adding an header with the elapsed time

The following code excerpt show a simple message channel that records the request’s processing time and adds an header to the response with it. Note how, after creating the Stopwatch, the request is simply delegated to the inner handler (base.SendAsync)

class ElapsedTimeMessageHandler : DelegatingChannel
{
    public ElapsedTimeMessageHandler(HttpMessageChannel innerChannel)
        : base(innerChannel)
    {
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var sw = new Stopwatch();
        sw.Start();
        return
            base.SendAsync(request, cancellationToken)
                .ContinueWith(task =>
                    {
                        sw.Stop();
                        task.Result.Headers.Add("X-Elapsed-Time", 
						    sw.ElapsedMilliseconds.ToString());
                        return task.Result;
                    },TaskContinuationOptions.ExecuteSynchronously);
    }
}

Example: HTTP intermediary

A message handler doesn’t even need to call the inner handler. Namely, it can completely bypass the upper WCF runtime stack.

The following code excerpt shows a message handler prototype that simply forwards all the HTTP requests to the origin server, using an HttpClient object. It illustrates a simplistic way of implementing HTTP  intermediaries (e.g. proxies).

class ProxyMessageHandler : DelegatingChannel
{
    private readonly HttpClient _client = new HttpClient();
    public ProxyMessageHandler(HttpMessageChannel innerChannel)
        : base(innerChannel)
    {
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        try
        {
            var req = new HttpRequestMessage
                    {
                        RequestUri =
                            new Uri("http://" + request.Headers.Host + request.RequestUri.PathAndQuery),
                        Method = request.Method
                    };
            if (req.Method == HttpMethod.Post || req.Method == HttpMethod.Put)
            {
                req.Content = request.Content;
            }
            foreach (var h in request.Headers.Where(h => !h.Key.StartsWith("Proxy-")))
            {
                req.Headers.Add(h.Key, h.Value);
            }
            var resp = _client.SendAsync(req,HttpCompletionOption.ResponseHeadersRead);
            resp.ContinueWith(t => TraceResponse(req,t));
            return resp.ContinueWith(t =>
                {
                    t.Result.Headers.Remove("Transfer-Encoding");
                    return t.Result;
                });
        }
        catch (Exception e)
        {
           TraceException(e);
            throw;
        }
    }
}

Configuration

Message handlers can be configured via a HttpHostConfiguration class and the AddMessageHandlers method. This is illustrated in the following code excerpt. Notice that ProxyMessage handler is the inner handler of ElapseTimeMessageHandlers.

var cfg = HttpHostConfiguration.Create()
			.AddMessageHandlers(typeof(ProxyMessageHandler), typeof(ElapsedTimeMessageHandler));
	
using (var host = new HttpConfigurableServiceHost(typeof(TheService), cfg, new Uri(...)))
...

External resources

Finally, here are some interesting references about message handlers:

• An introduction to message handlers, by Pablo Cibraro, with a very interesting API key verification example.
• Differentiation between message handlers and operation handlers, by Glenn Block.
• Automatic ETag Management with WCF Web API Message Handlers, on Channel 9.
• Supporting HEAD and TRACE, by Darrel Miller.

• Elementary programming model
• Self-hosting
• Self-hosting, HTTPS and HTTP Basic Authentication
• IIS Hosting
• HTTP Message Classes
• Processing Architecture
• HTTP Content Classes
• Description Model

In this post, I show how to handle HTTP requests asynchronously.

.NET’s Asynchronous Programming Model (APM)

The first version of the .NET platform introduced the Asynchronous Programming Model (APM) to represent asynchronous operations. It is characterized by the following:

• Each asynchronous operation is divided into two methods, the Begin method and the End method;
• The Begin method receives the operation’s inputs and two extra parameters – an AsyncCallback and an object state. This method must return an IAsyncResult, representing the asynchronous operation.
• The End method receives the above IAsyncResult and returns the operation result, waiting if it is not yet available

The APM model is used in several places of the .NET platform. Some examples are stream reading and writing; and asynchronous delegate invocation.

Currently, WCF also uses the APM model both on the client side and on the service side:

• On the client-side, the generated proxies can expose each WCF operation as a Begin/End method pair.
• On the service-side, the implementing class may expose a Begin/End method pair that will be called asynchronously by the WCF runtime.

The Preview 4 release of WCF Web API also supports this model. The following code excerpt shows an example of decomposing an Web API operation into a Begin and End methods

[OperationContract(AsyncPattern = true)]
[WebGet(UriTemplate = "image?uri={uri}")]
private IAsyncResult BeginGetImage(HttpRequestMessage req, string uri,
                                                 AsyncCallback ac, object state)
{
	...
}

private HttpResponseMessage EndGetImage(IAsyncResult ar)
{
	...
}

The usage of the asynchronous model is defined by the AsyncPattern property assigned with true on the OperationContract attribute.

More details about the AsyncPattern in “classical” WCF can be found in the following post series: WCF and the AsyncPattern property.

The Task-based model

The version 4.0 of .NET introduced a new asynchronous model based on the Task<T> class and TPL library. A Task<T> represents an asynchronous operation that returns a value of type T. On a first look, this class may seem similar to IAsyncResult, however there are significant differences:

• No need to call an End operation to retrieve the result. Instead, this value can be obtained from the task itself.
• Better support for cancellation, through cancellation tokens.
• Better support for exception handling.
• Native support for asynchronous operation composition, via the ContinueWith and the ContinueWhenAll/ContinueWhenAny methods.

The announced C#async support is also based on the Task<T> model and will provide a language integrated way of building and composing asynchronous operations.

In the .NET framework, this new Task<T> model is slowly replacing the APM model. For instance:

• The new .NET’s HTTP client (HttpClient class) provides a set of XxxAsync methods, returning Task<HttpResponseMessage>, for performing asynchronous HTTP requests.
• The WCF Web API message handlers, briefly described in the sixth post of this series, also use the new Task<T> model.

Using both asynchronous models

Unfortunately, the Preview 4 of WCF Web API doesn’t yet support the Task<T> model for the operation implementation. However, it is not hard to implement a APM based interface using Task<T>, as described in the following reference: TPL and Traditional .NET Asynchronous Programming. The key fact is that the Task<T> class also implements the IAsyncResult interface.

An example

To exemplify these concepts, the following example shows a service for image transcoding. It has one operation, that handles GET requests on the following URI template “image?uri={uri}”, and performs the following actions:

• GETs the representation of the resource (an image) identified by the {uri}
• Tries to build a bitmap with this resource’s representation
• Encodes and returns the bitmap using the JPEG format

Obtaining the response to the GET request and all the associated representation bytes may take a significant time. In order to avoid keeping a thread blocked during this time, this operation’s implementation will be asynchronous.

private HttpResponseMessage _response;
private HttpResponseException _exception;

[OperationContract(AsyncPattern = true)]
[WebGet(UriTemplate = "image?uri={uri}")]
private IAsyncResult BeginGetImage(string uri, AsyncCallback ac, object state)
{
    Trace("BeginGet...");
    var task = Task.Factory.Iterate(GetImageAndConvertItToJpeg(uri), state);
    task.ContinueWith(t =>
        {
         Trace("Main task completed, calling callback");
         if (ac != null) ac(task);
        }, TaskContinuationOptions.ExecuteSynchronously);
     return task;
}

private HttpResponseMessage EndGetImage(IAsyncResult ar)
{
    Trace("...EndGet");
    var task = ar as Task;
    if (task == null || task.IsFaulted)
    {
        throw new HttpResponseException(HttpStatusCode.InternalServerError);
    }
    if (_exception != null) throw _exception;
    return _response;
}

The previous code excerpt presents the BeginGetImage and EndGetImage methods.

Regarding the Begin method:

• The operation core processing is started on line 9, using a iterator based technique described in the following section, and is represented by a task.
• On line 10, a continuation is added to the above task, so that the WCF callback is called when the task completes. This will trigger the call, by the WCF runtime, of the EndGetImage method.
• On line 15, the task created on line 9 is returned. Notice that the operation’s return type is IAsyncResult. However, as stated in the beginning of this post, the Task class implements IAsyncResult interface. This is the key aspect to translate from the Task model into the APM model. The other aspect is the use of the state parameter when creating the task.

Regarding the End method:

• On line 21, the IAsyncResult is casted to a task. Notice that, according to the APM, the IAsyncResult passed into the End method is the one returned by the Begin method.
• Finally, the _exception and _response instance fields are consulted to produce an exception or response. These fields are assigned by the asynchronous process started on line 9 of the Begin method, as described in the following section.

Notice that the above code is rather generic. It could be used to implement other operations, just by changing line 9.

Using iterators to define asynchronous behavior

The typical way of defining asynchronous behavior with the Task<T> model is by chaining tasks with actions, producing other tasks. This breaks the code into multiple methods/anonymous methods/lambdas, reducing the readability.

In this post, we use an iterator based technique proposed by J. Richter for the APM and adapted to the Task<T> model by the ParallelExtensionExtras. The following code excerpt shows the asynchronous processing of the GetImageAndConvertItToJpeg method, implemented as a C# iterator.

private IEnumerable<Task> GetImageAndConvertItToJpeg(string uri)
{
    using (var client = new HttpClient
        {
            MaxResponseContentBufferSize = 1024*1024
        })
    {
        uri = Uri.UnescapeDataString(uri);
        Task<HttpResponseMessage> readTask = null;
        try
        {
            readTask = client.GetAsync(uri);
        }
        catch (Exception)
        {
            _exception = new HttpResponseException(HttpStatusCode.NotFound);
            yield break;
        }
        Trace("yielding for HTTP response...");
        yield return readTask;

        Trace("...resuming after HTTP response completed");
        if (readTask.IsFaulted || readTask.Result.StatusCode != HttpStatusCode.OK)
        {
            _exception = new HttpResponseException(HttpStatusCode.NotFound);
            yield break;
        }
        var httpContent = readTask.Result.Content;
        using (var ms = new MemoryStream())
        {
            var copyTask = httpContent.ContentReadStream.CopyStreamToStreamAsync(ms);
            Trace("yielding for stream copy...");
            yield return copyTask;

            Trace("...resuming after copy completed");
            if (copyTask.IsFaulted)
            {
                _exception = new HttpResponseException(HttpStatusCode.NotFound);
                yield break;
            }
            Bitmap bitmap = null;
            try
            {
                bitmap = new Bitmap(ms);
            }
            catch (Exception)
            {
                _exception = new HttpResponseException(HttpStatusCode.NotFound);
                yield break;
            }
            var output = new MemoryStream();
            bitmap.Save(output, ImageFormat.Jpeg);
            output.Seek(0, SeekOrigin.Begin);
            var content = new StreamContent(output);
            content.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
            _response = new HttpResponseMessage
                {
                    Content = content
                };
        }
    }
}

This code performs the following:

• An HttpClient is created to retrieve the upstream image. If any exception occurs while creating and starting the request, then the _exception instance field is assigned with an HttpResponseException and the iterator stops (yield break). If not, the result of the client.GetAsync(uri) statement is a Task<HttpResponseMessage>, representing the HTTP request. This task is then returned by the iterator, without blocking the hosting thread.
• The iterator is resumed only when this Task<HttpResponseMessage> completes. Then it checks for errors, and if everything is ok, creates a task to copy the HttpResponseMessage’s stream into a memory stream. This is done to ensure that all the image’s content are in memory when the bitmap is created. If the bitmap was created directly from the  HttpResponseMessage’s stream, then the Bitmapconstructor would block the hosting thread while waiting for all the bytes (and we don’t want to block threads!).The stream copy uses the CopyStreamToStreamAsync extension method, also available on the ParallelExtensionExtras. The task returned by this method is then returned by the iterator, so that the stream copy is performed asynchronously.
• The iterator is resumed again when the stream copy completes. After some error checking, the Bitmap is finally created and saved into another memory stream used in the response message. Notice that this can be done synchronously, since it doesn’t require any I/O.

Unfortunately, the above code is slightly cluttered by the error handling and by the fact that a yield statement cannot be inside a try-catch block.

The chaining of the tasks returned by the above iterator is done by the ParallelExtensionExtras Iterate method, that wraps the overall resulting asynchronous processing in a Task (remember line 9 of the second code excerpt).

This chaining is performed by the following:

• When initially called, the Iterate method schedules a task, using StartNew, that will call the iterator to retrieve the first task. It also creates a TaskCompletionSource to represent the  overall task.
• The first task retrieved from the iterator (representing the HTTP request) is then chained with another call to the iterator, using a ContinueWith.
• The second task retrieved from the iterator (representing the stream copy) is also chained with another call to the iterator.
• The final call to the iterator doesn’t return any element (MoveNext returns false), so Iterate signals the TaskCompletionSource that all the work is completed. This results in the call of the WCF callback.

The following diagram presents a sequence diagram, with the interaction between the different components.

The following color scheme is used:

• Red – WCF runtime components;
• Green – user code (Iterator represents the enumerable returned by the GetImageAndConvertItToJpeg method);
• Light blue – TPL scheduler;
• Dark blue – Iterate extension method (from the ParallelExtensionExtras)

The tracing output one of execution is (the first number is the managed thread id)

3: BeginGet…

6: yielding for HTTP response…

9: …resuming after HTTP response completed

9: yielding for stream copy…

6: …resuming after copy completed

6: Main task completed, calling callback

8: …EndGet

Conclusions and final remarks

• Currently, WCF Web API only allows asynchronous operation implementations exposing the APM model.
• However, it is not difficult to use a Task<T> based model with an APM interface, using the fact that Task implements IAsyncResult.
• While the future C# 5 asynchronous support is not available, the use of iterators and the ParallelExtensionExtras’s Iterate method provides for a similar experience.
• In this post I was not concerned with measuring the scalability improvements due to the use of asynchronous operation implementation. Namely, asynchronous processing may be disadvantageous if the blocking time is very small. My main goal here was the how and not the why of using asynchronous processing.
• The ParallelExtensionExtras library is full of interesting utilities, of which the Iterate and the CopyStreamToStreamAsync are just examples.

Finally, feedback is greatly welcomed.

The code is available from github: https://github.com/pmhsfelix/ISELTech11

For generating the HTML 5 slides from markdown, I used the following great tool: https://github.com/atiw003/html5-slides-markdown

• Elementary programming model
• Self-hosting
• Self-hosting, HTTPS and HTTP Basic Authentication
• IIS Hosting
• HTTP Message Classes
• Processing Architecture

This post presents the HTTP content class hierarchy.

The HTTP Message Classes post introduced the HttpRequestMessage and HttpResponseMessage classes, which represent HTTP requests and responses. Both this classes have a Content property, of type HttpContent, that represents the HTTP message body.

The HttpContent abstract class is just the root of a class hierarchy with multiple content classes, as presented in the following class diagram.

I’ve divided this class diagram into several regions, in order to highlight the different design aspects:

• The HttpContent is the hierarchy root, and is referenced by both the HttpRequestMessage and HttpResponseMessage  classes.
• There are several concrete HttpContent-derived classes for handling basic content types.
• The StreamContent, ByteArrayContent and StringContent classes are self-explanatory.
• The FormUrlEncoded is used to create application/x-www-form-urlencoded type content, based on a Iterable<KeyValuePair<string,string>> containing (name,value) pairs.
• The ObjectContent class represents object-based content, i. e.
• content produced by the serialization/formatting of an object;
• content that is to be read as an object, using deserialization/unformatting.
• The ObjectContent<T> generic class provides a more typed version of ObjectContent: instead of dealing with plain object, this classes provides methods to obtain a T from the content or to construct a content based on a T.
• This ObjectContent<T> is used by both the new HttpRequestMessage<T> and HttpResponseMessage<T> classes. This two classes represent HTTP request and responses, similarly to the non-generic HttpResponseMessage and HttpRequestMessage classes, with one big difference: the content is strongly-typed – a T instance.
• The conversion between byte streams and object instances is the responsibility of media-type formatters, represented by the MediaTypeFormatter abstract base class. This class contains two abstract methods, OnReadFromStream and OnWriteToStream, implemented by concrete classes such as XmlMediaTypeFormatter or JsonMediaTypeFormatter.

Concluding notes

• This post was based on the observation of the Preview 4 source code, available at http://www.codeplex.com. Since this is just a preview, this model is to be interpreted as “work in progress”.
• On future post, I will show how both the content classes and the generic request and response classes can be used as operation parameters.