HTTP.SYS Queuing

HTTP.SYS receives all HTTP requests and queues the requests. The requests are then picked up by the relevant application pool and are processed. After processing of the requests by the application pool, HTTP.SYS returns the response back to the client. If the application pool is unavailable or has been stopped, HTTP.SYS returns the 503 error stating “Service Unavailable” (see Figure 17-1).

HTTP.SYS Caching

Another important feature of HTTP.SYS is the kernel-level caching of the static and dynamic content. This feature helps cached content to be served directly from HTTP.SYS without even hitting the application pool, which leads to improved scalability of the system. The HTTP.SYS cache is ON by default and all cacheable responses get cached by this highly performant kernel-mode cache.

As for static content (e.g., JavaScript, CSS, image and view files), all GET requests can be cached. However, by default, not all responses are cached. If static content is requested twice within ten seconds, it will be cached for 120 seconds. These interval values are stored in the registry and can be configured (see http://support.microsoft.com/kb/820129).

As for dynamic content, it is the responsibility of the application to tell HTTP.SYS whether a response is cacheable, but due to differences in integration, it might not always work. The application will mark the response as cacheable by setting these HTTP response headers:

• Cache-Control: public
• Last-Modified: <date>
• Expires: <date> (optional)

Kernel caching is very important for the scalability of your application, so make sure you take advantage of this feature. Under certain circumstances, the response cannot be cached, including the following situations (for the full list visit http://support.microsoft.com/kb/817445):

• Requests a URL that contains any query string
• Request is not anonymous or requires authentication
• Dynamic compression is enabled (make sure you enable only static compression)
• Response is too large; default limit is 256KB
• Cache is full
• If-Range or Range header is present in the request

The best way to test the HTTP.SYS caching is to use Windows performance counters. The HTTP.SYS cache entrees are under the “Web Service Cache” category and they all start with “Kernel:” (see Figure 17-7).

HTTP.SYS kernel-mode caching is by default enabled for static files. You can see the content of the kernel-mode cache by running the following command in the administrative command prompt:

C:> netsh http show cachestate

HttpConfiguration

HttpConfiguration, as the name implies, is responsible for holding HTTP runtime configuration in ASP.NET Web API. These configuration elements are listed in Table 17-1.

HttpConfiguration only needs to be set up at the startup and your request or responses are only meant to use the runtime configuration and not make any changes to it.

HttpServer

HttpServer is the head of the ASP.NET Web API HTTP processing pipeline and is designed to receive a request from the hosting platform and pass it to the pipeline and return the response it receives back. The tail of this pipeline is normally the ApiController’s action.

HttpServer is designed to be hosting agnostic. It inherits from DelegatingHandler and, similar to all delegating handlers, has the important SendAsync method, which is called as a chain across the whole pipeline. Listing 17-1 is a snippet of the HttpServer’s class.

Listing 17-1.  HttpServer Class Constructors and SendAsync

public class HttpServer : DelegatingHandler
{
    public HttpServer()
            : this(new HttpConfiguration())
    {
    }

    public HttpServer(HttpConfiguration configuration)
            : this(configuration, new HttpRoutingDispatcher(configuration))
    {
    }

    public HttpServer(HttpMessageHandler dispatcher)
            : this(new HttpConfiguration(), dispatcher)
    {
    }

    public HttpServer(HttpConfiguration configuration, HttpMessageHandler dispatcher)
    {
            ...
    }
    protected override Task<HttpResponseMessage> SendAsync( _
            HttpRequestMessage request, CancellationToken cancellationToken)
            {
            ...
    }

    ...

}

As you can see in Listing 17-1, HttpServer is created by passing an instance of HttpConfiguration and a dispatcher of type HttpMessageHandler. The dispatcher represents the rest of the HTTP pipeline after the message handlers and by default is set to an instance of HttpRoutingDispatcher. In other words, HttpServer will be passing the request to the first handler in the MessageHandlers list on the HttpConfiguration. Each handler will pass the execution to the next until the last one, which passes the request to the HttpRoutingDispatcher.

HttpRoutingDispatcher is responsible for:

• 1.  Calling GetRouteData to trigger the route selection:

• If a route is not found, it returns a resource not found error (HTTP error 404).
• If a route is found, it stores the IHttpRouteData returned in the request properties.

• 2.  Passing the execution to the next handler:

• If the per-route message handlers are used, this will be the Handler property of IHttpRouteData, which will be non-null. In this case, handlers will be called in the same order they were defined. After these, an instance of HttpControllerDispatcher will be triggered.
• In a case where there are no per-route handlers (which is usually the case), execution will be passed to an instance of HttpControllerDispatcher.

You can provide an alternative dispatcher instead of the default HttpRoutingDispatcher. This will bypass the routing and execution of requests by the controller actions and can be useful in testing scenarios where you need to test the succession of MessageHandlers and their interaction as a whole. The pipeline is shown in Figure 17-8.

Hosting is connected to controllers and actions via intermediaries, including HttpServer, delegating handlers, HttpRoutingDispatcher, and HttpRoutingDispatcher. Figure 17-8 does not show per-route message handlers. In the case of per-route handlers, they would be called between HttpRoutingDispatcher and HttpControllerDispatcher.

Runtime Configuration

Runtime configuration in web hosting is based on the familiar class HttpConfiguration. But in order to set up a Web Host API, you need to configure the static instance sitting on GlobalConfiguration. As you’ve seen in different examples over the course of this book as well as in the ASP.NET Web API project template, configuration takes place in the Global.asax (see Listing 17-2).

Listing 17-2.  Standard Approach to Configuring a Web Host API

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        ...
        WebApiConfig.Register(GlobalConfiguration.Configuration);
        ...
    }
}

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
         ...
    }
}

As can be seen in Listing 17-2, GlobalConfiguration.Configuration is being used to configure the API. On the other hand, this static object is passed as the parameter to the WebApiConfig class. This simple separation has the benefit of allowing the configuration to be unit tested with no dependency to a global object. Not surprisingly, GlobalConfiguration.Configuration is the configuration used by HttpControllerHandler, which we’ll look at next.

Runtime Execution

As mentioned earlier, in each scenario ASP.NET Web API’s HTTP pipeline is triggered via a call to the HttpServer’s SendAsync method. In the web host scenario, this is the responsibility of HttpControllerHandler. This class is the bridge between ASP.NET HTTP abstractions and ASP.NET Web API (HttpServer). HttpControllerHandler implements IHttpAsyncHandler, which was derived from IHttpHandler (see Listing 17-3).

Listing 17-3.  HttpControllerHandler Implementing IHttpAsyncHandler and IHttpHandler

public class HttpControllerHandler : IHttpAsyncHandler
{
    ...
}

public interface IHttpAsyncHandler : IHttpHandler
{
    IAsyncResult BeginProcessRequest(HttpContext context, AsyncCallback cb, object extraData);
    void EndProcessRequest(IAsyncResult result);
}

public interface IHttpHandler
{
    bool IsReusable { get; }

    void ProcessRequest(HttpContext context);
}

As you can see from the signature of ProcessRequest in IHttpHandler, the HTTP processing model in ASP.NET is built on top of HttpContext. IHttpHandler and its async counterpart IHttpAsyncHandler are the components responsible for handling a request. Unlike modules that sit in the stream of incoming requests and outgoing responses and observe, intercept, or alter them, handlers are the endpoints capable of processing the request. Other examples of handlers are the Page class in Webforms, the MvcHandler class in MVC, and generic handlers (normally created as .ashx files).

HttpControllerHandler is responsible for converting the incoming HttpRequest (Request property of HttpContext) to an instance of ASP.NET Web API’s HttpResponseMessage, and on the return of an instance of HttpResponseMessage, converting it into an instance of HttpResponse, which sits at the Response property of HttpContext. HttpControllerHandler is also responsible for extracting some hosting-related context and storing it in the Properties property of HttpRequestMessage. These include:

• Storing the HttpContext itself with the string key "MS_HttpContext". This is very important because using this stored context in the request properties is the only way to get to the current HttpContext if the context is not available in the asynchronous task continuations.
• Storing the current client certificate with the key HttpPropertyKeys.RetrieveClientCertificateDelegateKey. This entry’s value will be null if there is no client certificate.
• Storing whether the request is local as a Boolean with the key HttpPropertyKeys.IsLocalKey.
• Storing whether a detailed error must be returned as a Boolean against the key HttpPropertyKeys.IncludeErrorDetailKey.

Web API web host shares many aspects of hosting ASP.NET Webforms or MVC, so it is important to have a solid understanding of IIS hosting (integrated vs. classic pipeline, HTTP modules, etc.), which is beyond the scope of this book.

Hosting PingYourPackage Sample

In Chapters 5 through 7, you developed a sample web application called PingYourPackage, and in Chapter 7, you chose web hosting to host it. To run the application successfully on your local environment, you need to perform a few steps first. This project requires Visual Studio 2012 or Visual Web Express 2012.

1. Open an elevated PowerShell command prompt.
2. Make sure that your ExecutionPolicy is set to Unrestricted. You can run the Get-ExecutionPolicy PowerShell command to see your execution policy. If it’s not set to Unrestricted, run the following command:

   Set-ExecutionPolicy Unrestricted

3. After setting your execution policy properly, navigate to PingYourPackage solution’s root folder and run the following command:

   .AddIISExpressCertToTrustedStore.ps1

4. This will add the IIS Express’s development SSL (Secure Socket Layer) certificate into the Trusted Root Certificates store.
5. After these steps, open the solution on Visual Studio or Visual Web Developer Express. Click the solution and press ALT+ENTER to bring up the Solution Property Pages dialog window. From there, navigate to the Startup Project tab and set the following projects as the startup project (put them in the same order):

   PingYourPackage.API.WebHost
   PingYourPackage.API.Client.Web

You’re done! Press F5 (or CTRL+F5) to get the application up and running.

Runtime Configuration

Self-host configuration is based on the HttpSelfHostConfiguration class, which inherits from HttpConfiguration. Extra properties are listed in Table 17-2.

As you can see, self-host configuration “leaks” out many WCF-related properties. Properties of HttpSelfHostConfiguration will be used by HttpSelfHostServer to set up an HttpBinding, which can be modified by inheriting from HttpSelfHostConfiguration and overriding the protected OnConfigureBinding method. Let’s look further into HttpSelfHostConfiguration properties in some code samples.

Runtime Execution

HttpSelfHostServer is responsible for using the configuration and directs the incoming messages from HTTP.SYS to the ASP.NET Web API HTTP pipeline. HttpSelfHostServer is inherited from HttpServer and has two additional asynchronous methods—OpenAsync and CloseAsync—for starting and stopping accepting messages.

HttpSelfHostServer sets up an HttpBinding object and configures it via calling the internal method with ConfigureBinding on HttpSelfHostConfiguration and uses its properties to further configure the binding. This binding will then be used to create a WCF channel, which in turn communicates with HTTP.SYS.

Self-Hosting Example Scenarios

Let’s look at several practical scenarios in self-hosting. These will be the scenarios you will most often come across in your projects, so this will help you gain a deeper understanding of ASP.NET Web API self-host.

System.ServiceModel.AddressAccessDeniedException: HTTP could not register URL http://+:18081/. Your process does not have access rights to this namespace (see http://go.microsoft.com/fwlink/?LinkId=70353 for details).

netsh http

netsh http add urlacl url=https://<ip address>:<port number>/ user=<username>

netsh http add urlacl url=http://+:18081/ user=users

public class HttpsSelfHostConfiguration : HttpSelfHostConfiguration
{
    public HttpsSelfHostConfiguration(string baseAddress) : base(baseAddress)
    {
    }

    public HttpsSelfHostConfiguration(Uri baseAddress) : base(baseAddress)
    {
    }

    protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
    {
        httpBinding.Security.Mode = HttpBindingSecurityMode.Transport;
        return base.OnConfigureBinding(httpBinding);
    }
}

netsh http add sslcert ipport=<ip>:<port> certhash=<thumbprint> appid=<guid>

netsh http add sslcert ipport=0.0.0.0:18081 certhash=1b7644dd
4ab5e5794f5696d9792d284d210e55dd appid={54F62034-D508-4738-88C0-3BA1C1617FA3}

public class NtlmHttpSelfHostConfiguration : HttpSelfHostConfiguration
{
    public NtlmHttpSelfHostConfiguration(string baseAddress)
        : base(baseAddress)
    {
        this.ClientCredentialType = HttpClientCredentialType.Ntlm;
    }

    public NtlmHttpSelfHostConfiguration(Uri baseAddress)
        : base(baseAddress)
    {
        this.ClientCredentialType = HttpClientCredentialType.Ntlm;
    }

    protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
    {
        httpBinding.Security.Mode = HttpBindingSecurityMode.TransportCredentialOnly;
        return base.OnConfigureBinding(httpBinding);
    }
}

public class BasicAuthenticationSelfHostConfiguration: HttpSelfHostConfiguration
{
    private readonly FunctionalUserNamePasswordValidator _functionalUserNamePasswordValidator;

    private class FunctionalUserNamePasswordValidator : UserNamePasswordValidator
    {
        private readonly Func<string, string, bool> _userNamePasswordValidator;

        public FunctionalUserNamePasswordValidator(Func<string, string, bool> _
            userNamePasswordValidator)
        {
            if(userNamePasswordValidator==null)
                throw new ArgumentNullException("userNamePasswordValidator");

            _userNamePasswordValidator = userNamePasswordValidator;
        }

        public override void Validate(string userName, string password)
        {
            if(!_userNamePasswordValidator(userName, password))
                throw new SecurityException("Invalid username/password pair.");
        }
    }

    public BasicAuthenticationSelfHostConfiguration(string baseAddress, Func<string, string,
        bool> userNamePasswordValidator) : base(baseAddress)
    {
        _functionalUserNamePasswordValidator = new  _
            FunctionalUserNamePasswordValidator(userNamePasswordValidator);
    }

    public BasicAuthenticationSelfHostConfiguration(Uri baseAddress, Func<string, string, bool>
        userNamePasswordValidator)
        : base(baseAddress)
    {
        _functionalUserNamePasswordValidator = new _
            FunctionalUserNamePasswordValidator(userNamePasswordValidator);
    }

    protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
    {
        httpBinding.Security.Mode = HttpBindingSecurityMode.TransportCredentialOnly;
        httpBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
        this.UserNamePasswordValidator = _functionalUserNamePasswordValidator;
        return base.OnConfigureBinding(httpBinding);
    }
}

var config = new BasicAUthenticationSelfHostConfiguration("http://localhost:18081",
    (un, pwd) => un=="johndoe" && pwd=="123456");

Why Should I Learn About OWIN?

In late 2012, Microsoft announced that supporting OWIN will be a strategic goal and it has set up the Katana project to implement the interface for a variety of ASP.NET web frameworks. Future developments in the .NET space are likely to have OWIN-specific implementations and sooner or later you will be working on a project that has OWIN dependency. In fact, version 2.0 of the ASP.NET Web API, which is in development at the time of this writing, has been focused on delivering OWIN interoperability.

OWIN provides interoperability between web frameworks and makes it easy to write a single piece of code that can be reused in each and every framework. This is something that has been impossible so far.

The future of the .NET web technologies is going to be heterogenous with a heavy open source software presence. As such, it is important to be prepared for a shift in the .NET horizon.

OWIN Concepts and Runtime

OWIN is a web runtime that acts as a bridge (abstraction) between web hosts and web frameworks (see Figure 17-14). On the one hand, OWIN has defined interfaces for interaction of hosts and frameworks. On the other hand, each host or framework is connected to the OWIN runtime using its OWIN adapter.

Concepts defined for an OWIN system are: Host, Server, Framework, Application, and Middleware (see http://owin.org/spec/owin-1.0.0.html#Definition for further information). Host in OWIN terms is a process that runs the initial set up and provides a runtime platform for incoming requests. Server is a linked concept and its responsibility is to route the incoming requests to the OWIN runtime. In the case of ASP.NET hosting, these two concepts are the same, while in self-host they could be different. OWIN runtime then passes a request to the Application stack and returns the response. The request processing system is composed of an ordered set of Middleware/Applications capable of handling the request. Applications are normally implemented in a Framework such as ASP.NET Web API, NancyFx, among others, and are responsible for the functionality of the web applications. Middlewares are normally pass-through components that enhance the functionality of the application and look after cross-cutting concerns such as security, tracing, caching, monitoring, and so forth. All communications are completely asynchronous (represented by TPL’s Task) and requests and responses flow as part of a dictionary called Environment. Setup work at the startup is the responsibility of AppBuilder, which is represented by the IAppBuilder interface (see Listing 17-4). AppBuilder contains a dictionary called Properties, which represents Host’s properties.

Listing 17-4.  OWIN’s IAppBuilder Interface

public interface IAppBuilder
{
  IDictionary<string, object> Properties { get; }

  IAppBuilder Use(object middleware, params object[] args);

  object Build(Type returnType);

  IAppBuilder New();
}

IAppBuilder is normally constructed by the Host and is passed to the startup code so that the application can configure itself. Middlewares are added by calling the Use method. These components are ordered and will be called in the order they are added.

A common interface within OWIN is a delegate called AppFunc, which is the entry point for the applications:

Func<IDictionary<string, object>, Task>

In this delegate, Application receives an Environment dictionary containing the request and response and returns a Task. Application is meant to complete the Task either by successfully processing the request or by faulting the Task (by throwing an exception).

OWIN projects are composed of the OWIN runtime core (which is in fact relatively small) and a set of adapter projects (see Figure 17-15). Each server or web framework requires an adapter to be able to communicate with OWIN components.

Example: Web Hosting ASP.NET Web API in OWIN

ASP.NET Web API in OWIN as a web host is pretty straightforward and that’s what we’ll show you now.

1. Open Visual Studio and create an empty Web Application. Install two NuGet packages by running the commands below in the Package Manager Console:

   PM> Install-Package microsoft.owin.host.systemweb
   PM> Install-Package Microsoft.AspNet.WebApi.Owin -pre -Version 0.21.0-pre

2. Add a simple controller:

   public class TestController : ApiController
   {
       public string Get()
       {
           return DateTime.Now.ToString();
       }
   }

3. Create a class called Startup and add the following code:

   public class Startup
   {
       public void Configuration(IAppBuilder app)
       {
           var config = new HttpConfiguration();
           config.Routes.MapHttpRoute(
               name: "DefaultApi",
               routeTemplate: "api/{controller}/{id}",
               defaults: new { id = RouteParameter.Optional }
           );
           app.UseWebApi(config);
       }
   }

   As you can guess, the magic happens when you call .UseWebApi.

4. The last step is to add some appSetting configuration to your web.config to send all requests toward your OWIN application:

   <appSettings>
       <!--Makes the OWIN module the default request handler-->
       <add key="owin:HandleAllRequests" value="true" />
       <!--Maps the current directory to the application’s path-->
       <add key="owin:SetCurrentDirectory" value="true" />
     </appSettings>

5. Now run the application and browse to http://localhost:<yourport>/api/Test. You should see the current date being returned.

Future of OWIN

As explained previously, ASP.NET Web API version 2.0, which is at the beta stage at the time of this writing, can work with OWIN. As far as the future of OWIN is concerned, you’ll see more and more decoupling of the frameworks from hostings and further integration into abstractions of OWIN.

So it will be important to watch the developments of the Katana project and take advantage of its interoperability when it goes live.