Category Archives: Software

ASP.NET Web API: self-hosting

In the last posts, I’ve been exploring the new ASP.NET Web API Beta architecture. I started by the high-level processing architecture, then described web hosting and in-memory hosting, i.e., directly connecting a client to the server without going through the network.

This post describes a third “out of the box” hosting option: self-hosting. The following code excerpt exemplifies the usage of the HttpSelfHostServer class to host a server on a console application.

    var config = new HttpSelfHostConfiguration("http://localhost:8080");
    config.Routes.MapHttpRoute("default", "{controller}/{id}", 
                                    new { id = RouteParameter.Optional });
    var server = new HttpSelfHostServer(config);
    Console.WriteLine("Server is opened");


The HttpSelfHostServer class derives from HttpServer and and is configured by a HttpSelfHostConfiguration instance, as shown in the following diagram.



Internally, the HttpSelfHostServer uses a WCF channel stack layer to obtain messages from the transport medium and then pushes them into the upper message handler pipeline.

The following section briefly presents the WCF high-level architecture, setting the ground for the description of Web API self-hosting characteristics.

WCF architecture

The WCF architecture is divided into two layers: the channel stack layer and the service model layer, as depicted in the following diagram.


The lower channel stack layer is composed by a stack of channels and behaves similarly to a classical network protocol stack.  The channels are divided into two types: transport channels and protocol channels. Transport channels are responsible by the interface with the transport medium (e.g. TCP, MSMQ, HTTP) (yes, I know, HTTP is not a transport protocol), namely by receiving and sending messages. Protocol channels process the messages that flow up and down through the stack. A typical use case for a protocol channel is the addition of digital signatures at the sending side and the verification of those signatures at the receiving side. The transport channels use encoders to convert between the transport medium byte streams and message instances.

The upper service model layer performs the interface between the messages and methods calls, dealing with tasks such as:

  • transforming a received message into a parameter sequence;
  • obtaining the service instance to use;
  • selecting the method to call;
  • obtaining the thread where to call the method.

However, the HttpSelfHostServer doesn’t use the service model layer. Instead, it directly consumes the messages retrieved from channel stack layer.

The concrete channel stack layer organization is described by bindings, as presented in the following diagram.


A binding is a ordered collection of binding elements, where each element roughly describes one channel or encoder. The first binding element describes the upper channel and the last element describes the lower channel, which is always a transport channel.


The HttpSelfHostServer and HttpSelfHostConfiguration classes

Internally, the HttpSelfHostserver.OpenAsync method creates and configures a HttpBinding instance, based on the HttpSelfHostConfiguration instance properties. Then it uses this binding to asynchronously create a WCF channel stack. It also creates a pump that pulls messages from this channel stack, converts them into HttpRequestMessage instances and pushes these new requests into the HttpServer, that is, the message handler pipeline.


When self-hosting, most of the WCF HTTP binding capabilities and settings are available. The configuration of the internally created HttpBinding instance can be accomplished in two ways. The first is to use HttpSelfHostConfiguration properties, such as MaxBufferSize and TransferMode, that will be used to configure the internal HttpBinding instance. The second is to create a HttpSelfHostConfiguration derived class and override the OnConfigureBinding method, which receives the internally created binding instance. This method has the opportunity to change the binding settings before it is used to create the channel stack.


In a future post, I will show how to create a custom host. Until then, comments are welcomed.

ASP.NET Web API: web hosting

In a previous post, I described the processing architecture of the new ASP.NET Web API, namely its division into three layers: hosting, message handler pipeline and controller handling.

In this post, I’m going to address one of the hosting options: web hosting, i.e., hosting on top of the ASP.NET classical pipeline.


On the ASP.NET platform, routing is commonly performed by adding routes to the RouteTable.Routes static property, which holds a RouteCollection. For example, the following code excerpt shows the default routing defined by the ASP.NET MVC project template.

    protected void Application_Start()

    public static void RegisterRoutes(RouteCollection routes)

            "Default", // Route name
            "{controller}/{action}/{id}", // URL with parameters
            new { controller = "Home", action = "Index", id = UrlParameter.Optional } 

Most of the routing logic is performed by the UrlRoutingModule, attached to the PostResolveRequestCache ASP.NET pipeline event. On each request, this module matches the current request against the route collection, obtaining a RouteData instance. If there is a match, then:

  1. A route handler is obtained from the route data.
  2. A HTTP handler, implementing the IHttpHandler interface, is obtained from the route handler.
  3. Finally, the current request context is mapped to the above HTTP handler.

    As a consequence, at the end of the ASP.NET pipeline the request is sent to this handler .

Web API integration

When hosting on ASP.NET, the Web API specific configuration is defined on a singleton HttpConfiguration object, accessible via the static GlobalConfiguration.Configuration property.

Web API also defines a couple of new RouteCollection extension methods, named MapHttpRoute, to register Web API specific routes. The following code excerpt contains an example configuration.

    HttpConfiguration config = GlobalConfiguration.Configuration;
    config.Routes.MapHttpRoute("default", "{controller}/{id}",  new {id = UrlParameter.Optional});
    // other configuration settings



The routes added to the route collection by the MapHttpRoute extension methods use the new HttpControllerRouteHandler route handler . When a route added via MapHttpRoute is matched by a request, the associated route handler returns a new type of handler – the HttpControllerHandler – which implements the asynchronous IAsyncHttpHandler interface. This handler is initialized with the route data, containing the matching information.

When called, the HttpControllerHandler on its BeginProcessRequest method performs the following actions:

  1. Creates a HttpRequestMessage instance from the current HttpContext;
  2. Creates an HttpServer using the configuration referenced by GlobalConfiguration.Configuration and then pushes the new `HttpRequestMessage` into the server pipeline.

After the request is receive by the HttpServer instance, it enters the host independent phase of the processing (the Web API new pipeline).

The following diagram summarizes the route resolution process and the dispatch into the HttpServer instance (the message handler pipeline).


ASP.NET Web API: in-memory hosting

One of the nice features in the new ASP.NET Web API is in-memory hosting, i.e., the possibility to directly connect a HttpClient to the server-side runtime, without any network usage or HTTP message serialization:

var config = new HttpConfiguration();
config.Routes.MapHttpRoute("default", "{controller}/{id}", new { id = RouteParameter.Optional });
// additional config ...
var server = new HttpServer(config);
var client = new HttpClient(server);
var r = client.GetAsync("")

In the above code, notice how the HttpClient is initialized with the HttpServer, establishing the direct client-server connection.

This feature is relevant on integration or end-to-end testing scenarios, by decreasing the time required for a round-trip and avoiding the self-hosting complexity (e.g. URI access control).

This feature also illustrates an interesting symmetry between the client and server stacks, around the message handler concept, as described in the following paragraphs.

Server side

The last post described the ASP.NET Web API server-side processing architecture : what happens since a HTTP request is received until a response is produced.

As stated in that post, this processing architecture is composed by three layers: hosting, message handler pipeline and controller handling. The hosting layer

  • translates HTTP requests, received from lower level APIs, into HttpRequestMessage instances;
  • pushes this messages into the above message handler pipeline, wrapped by a HttpServer.  Typically, at the end of this pipeline there is an handler that dispatches the messages to the chosen controller.

Of special relevance is the fact that HttpServer derives from HttpMessageHandler (composite pattern).

Client side

The architecture of the new HttpClient class was also described in a previous post, namely the fact that the HttpClient internally uses a HttpMessageHandler to compute the HTTP response, given the HTTP request.



It is this symmetry – HttpServer is a message handler and HttpClient receives a message handler – that allows the direct connection of the client to the server, bypassing the server side hosting layer, as showed in the following diagram.



Nice, isn’t it?

ASP.NET Web API Processing Architecture


This post presents a first overview of the ASP.NET Web API processing architecture: what happens since a HTTP request is received until a response is produced.

Processing Architecture

The ASP.NET Web API processing architecture, represented in the following diagram, is composed by three layers: hosting, message handler pipeline and controller handling.



The lower layer is responsible for the Web API hosting, i.e., the interface between Web API and an underlying HTTP handling runtime.  Succinctly, this layer is responsible for creating HttpRequestMessage instances, and then pushing them into the upper message handler pipeline. The hosting layer is also responsible for processing the HttpResponseMessage returned back from this handler pipeline.

Currently, there are two “out-of-the-box” hosting options: self-hosting and web hosting, i.e., hosting on top of the ASP.NET classical pipeline.

Self-hosting is based on a pump that retrieves WCF Message instances from a WCF channel stack, converts them into HttpRequestMessage instances and then push those into the upper message handler pipeline.

Web-hosting is based on a specific IHttpAsyncHandler, named HttpControllerHandler, that converts HttpRequest instances into HttpRequestMessage.

The Web API hosting is not limited to these two options. There are already some additional hosts, contributed by the community:

Message Handler Pipeline

The middle layer is composed by a message handler pipeline, similar to the one that existed on WCF Web API. This pipeline is exposed by the HttpServer class, which also extends HttpMessageHandler (composite pattern).

This pipeline provides the extensibility point for “middleware” addressing cross-cutting concerns such as: logging, HTTP authentication, HTTP method translation, …

Usually, at the top of this pipeline, there is a special handler: the HttpControllerDispatcher. This handler is responsible for obtaining and calling a controller to handle the request.

The presence of this HttpControllerDispatcher is only required when using the controller-based programming model (ApiController derived classes). It is also possible to mount a completely different model, just by replacing the pipeline’s top message handler.

Controller Handling

Finally, the upper layer corresponds to the controller specific processing, namely:

This processing is done inside the ApiController instance, called by the HttpControllerDispatcher.

Final Remarks

Future posts will address each one of this layers in more details. Until then, feel free to use the comments.

Enabling HTTPS with self-hosted ASP.NET Web API

In a previous post, I showed how to  self-host ASP.NET Web API. This post shows how to change that example in order to enable HTTPS support.

  1. On an elevated console (“Run as administrator”), execute “netsh http add urlacl url=https://+:4443/ user=<your user name>”, to allow the running user to listen on port 4443 using HTTPS (note the use of ‘https’ instead of ‘http’ in the above command).
  2. Also on an elevated console, register the server certificate by running

    netsh http add sslcert ipport= certhash=thumbprint appid={app-guid} where

    • port is the listening port (e.g. 4443); the special IP address matches any IP address for the local machine;
    • thumbprint is the certificate’s SHA-1 hash, represented in hexadecimal;
    • app-guid is any GUID (e.g. {00000000-0000-0000-0000-000000000000}) , used to identity the owning application.
  3. In the previous post’s Main method, replace the HttpSelfHostConfiguration class with the new MyHttpsSelfHostConfiguration class, containing the following code.
  4. class MyHttpsSelfHostConfiguration : HttpSelfHostConfiguration
        public MyHttpsSelfHostConfiguration(string baseAddress) : base(baseAddress){}
        public MyHttpsSelfHostConfiguration(Uri baseAddress) : base(baseAddress){}
        protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
            httpBinding.Security.Mode = HttpBindingSecurityMode.Transport;
            return base.OnConfigureBinding(httpBinding);
  5. Change the base address passed to the MyHttpsSelfHostConfiguration constructor: var config = new MyHttpsSelfHostConfiguration(“https://localhost:4443&#8221;);
  6. Run the program, open a browser and access https://localhost:4443/helloimage

That’s it: you now have a self-hosted ASP.NET Web API server, using the secure HTTPS protocol.

Self-hosting ASP.NET Web API

Just a simple example, showing how to self-host ASP.NET Web API.

    1. On an elevated console (“Run as administrator”), execute “netsh http add urlacl url=http://+:8080/ user=<your user name>”, to allow the running user to listen on port 8080.
    2. On Visual Studio, create a “Console Application” project.
    3. Change the project’s Target Framework property from “.NET Framework 4 Client Profile” to “.NET Framework 4 profile”.
    4. Install the AspNetWebApi.Selfhost NuGet package
    5. Create a public ApiController derived class.
public class HelloController : ApiController
  public HttpResponseMessage Get()
    return new HttpResponseMessage
          Content = new StringContent("Hello HTTP")
    1. In the program’s Main method,
      1. Create a HttpSelfHostConfiguration, initialized with the base address.
      2. Add the default route: MapHttpRoute(“default”, “{controller}/{id}”, new { id = RouteParameter.Optional });
      3. Create a HttpSelfHostServer, initialized with the above configuration object.
      4. Open the server, bearing in mind that the OpenAsync method is asynchronous.
static void Main(string[] args)
  var config = new HttpSelfHostConfiguration("http://localhost:8080");
  config.Routes.MapHttpRoute("default", "{controller}/{id}", new { id = RouteParameter.Optional });
  var server = new HttpSelfHostServer(config);

  Console.WriteLine("Server is opened");

  1. Run the program, open a browser and access http://localhost:8080/hello.


That’s it. You now have a self-hosted ASP.NET Web API server.

WCF Web API is now ASP.NET Web API

For the past year, I’ve been studying and exploring the preview releases of WCF Web API. The result of these activities is reflected in a series of posts presenting its programing model, processing architecture and extensibility points.

However, WCF Web API was recently renamed as ASP.NET Web API, as the result of its merge with the Microsoft Web platform, namely with ASP.NET MVC.

This renaming is n0t just mere branding issue; it reflects changes in both the programming model and processing architecture. For instance:

  • The programming model is now based on the controller and action concepts, used in ASP.NET MVC, instead of on the service and operation concepts, from the WCF world.
  • Operation handlers were removed and a model-binding mechanism was introduced.

As a consequence, some of my WCF Web API related posts are now software archeology.

However, in the near future, I will be posting more information about this new programming model and processing architecture. Stay tuned.

The new System.Net.Http classes: message content

The 4.5 version of the .NET platform introduces the new System.Net.Http namespace with several HTTP related classes. These classes are also available for .NET 4.0, via the Web API Preview 6 distribution (both source code and NuGet package).

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.

The new .NET HttpClient class

A recent post by Darrel Miller, entitled “HttpClient, it lives, and it is glorious.” motivated me to investigate more about the HttpClient class underlying architecture.
This post is the result of that study, and focus mainly on design and organization aspects, namely extensibility.
For code examples, refer to Darrel’s excellent post.


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.



In conclusion,

WCF Web API–building an Authorize attribute

This is the thirteenth post on a series about the WCF Web API Preview 4 and 5.  Last post focused on custom operation parameter conversion. This post shows how to also use operation handlers to build something similar to ASP.NET MVC’s AuthorizeAttribute.

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

class TheService
    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