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);
    server.OpenAsync().Wait();
    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.

SelfHosting

 

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.

WcfArchitecture

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.

WcfBindingElementsChannels

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.

SelfHostingDiagram

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.

SelfHostingDetail

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

2 thoughts on “ASP.NET Web API: self-hosting

  1. Flávio Oliveira

    Hi Pedro,

    i’ve a question that i still could not find examples on internet about the self-hosted configuration of webapi.

    how can configure my webapi to multiple host-headers, in IIS i add new binding to the website.

    how can it be done for Selfhosted solutions?

    for example, my application sould respond to “static1.domain.com”, “static2.domain.com”, “static3.domain.com”

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s