All notes

Overview an overview of katana.

Why Katana – Why Now?

ASP.NET was originally created with two customers in mind.


Lots of change was happening in Web development! Web applications were increasingly being developed as a series of small, focused components rather than large frameworks. The number of components as well as the frequency with which they were released was increasing at an ever faster rate. It was clear that keeping pace with the Web would require frameworks to get smaller, decoupled and more focused rather than larger and more feature-rich.

One of the early changes was the rise in popularity of the well-known model-view-controller (MVC) design pattern thanks to Web development frameworks like Ruby on Rails. Microsoft took the opportunity to position itself better for the future by developing ASP.NET MVC out of band (and not including it in the .NET Framework). ASP.NET MVC was released as an independent download. This gave the engineering team the flexibility to deliver updates much more frequently than had been previously possible.

Another major shift in Web application development was the shift from dynamic, server-generated Web pages to static initial markup with dynamic sections of the page generated from client-side script communicating with backend Web APIs through AJAX requests. This architectural shift helped propel the rise of Web APIs, and the development of the ASP.NET Web API framework. The engineering team took advantage of the opportunity and built ASP.NET Web API such that it had no dependencies on any of the core framework types found in System.Web.dll. With no dependencies to IIS, ASP.NET Web API included the capability to run in a custom host.

The future. A modern Web application generally supports static file serving, dynamic page generation, Web API, and more recently real-time/push notifications. Expecting that each of these services should be run and managed independently was simply not realistic. what was needed was a single hosting abstraction that would enable a developer to compose an application from a variety of different components and frameworks, and then run that application on a supporting host.


Inspired by the benefits achieved by Rack in the Ruby community.

Environment dictionary

This data structure is responsible for storing all of the state necessary for processing an HTTP request and response, as well as any relevant server state. The environment dictionary is defined as follows:

IDictionary<string, object>

The required dictionary keys for an HTTP request:

Application delegate

This is a function signature which serves as the primary interface between all components in an OWIN application. The definition for the application delegate is as follows:

Func<IDictionary<string, object>, Task>;

This design has several implications for developers:

Owin NuGet package (Owin.dll) library contains a single interface, IAppBuilder, which formalizes and codifies the startup sequence described in section 4 of the OWIN specification. While not required in order to build OWIN servers, the IAppBuilder interface provides a concrete reference point, and it is used by the Katana project components.


  1. Create an Empty ASP.NET Web Application.
  2. Install the Microsoft.Owin.Host.SystemWeb NuGet package into the project.
  3. Write codes.

A simple server:

public class Startup
   public void Configuration(IAppBuilder app)
      app.Run(context =>
         context.Response.ContentType = "text/plain";
         return context.Response.WriteAsync("Hello World!");

      // app.UseWelcomePage();

NOTE: By default, the previous “hello world” example runs in the ASP.NET request pipeline, which uses System.Web in the context of IIS.

wcfNote: SystemWeb is used by default for debugging in VS. Remember to switch to OwinHost option (see below) when not using IIS.

Switching hosts

In this example, we’ll host our Web server in a Katana host called OwinHost.exe and will use the Katana HttpListener-based server.

  1. install-package OwinHost
  2. Go to the project root folder and simply run the OwinHost.exe (which was installed in the tools folder of its respective NuGet package). By default, OwinHost.exe is configured to look for the HttpListener-based server and so no additional configuration is needed.


The Katana component architecture divides an application into four logical layers: host, server, middleware, and application. The component architecture is factored in such a way that implementations of these layers can be easily substituted, in many cases, without requiring recompilation of the application.


The host is responsible for:

Presently 3 primary hosting options for Katana-based applications:

The self-host setup for a Katana application is similar:

static void Main(string[] args)
    const string baseUrl = "http://localhost:5000/";

    using (WebApplication.Start<Startup>(new StartOptions { Url = baseUrl })) 
        Console.WriteLine("Press Enter to quit.");

One notable difference between the Web API and Katana self-host examples is that the Web API configuration code is missing from the Katana self-host example. In order to enable both portability and composability, Katana separates the code that starts the server from the code that configures the request processing pipeline. The code that configures Web API, then is contained in the class Startup, which is additionally specified as the type parameter in WebApplication.Start.


owinhost.exe /?
owinhost.exe --port 5000 HelloWorld.Startup


The responsibility of the server is to open a network socket, listen for requests, and send them through the pipeline of OWIN components specified by the user.

Currently, the Katana project includes two server implementations:


A pipeline of OWIN components are known as middleware.

At a very basic level, an OWIN middleware component simply needs to implement the OWIN application delegate so that it is callable.

Func<IDictionary<string, object>, Task>

In order to simplify the development and composition of middleware components, Katana supports a handful of conventions and helper types for middleware components. The most common of these is the OwinMiddleware class.

public class LoggerMiddleware : OwinMiddleware
    private readonly ILog _logger;
    public LoggerMiddleware(OwinMiddleware next, ILog logger) : base(next)
        _logger = logger;
    public override async Task Invoke(IOwinContext context)
        _logger.LogInfo("Middleware begin");
        await this.Next.Invoke(context);
        _logger.LogInfo("Middleware end");

// The middleware class can be easily added to the OWIN pipeline in the application startup code as follows:
public class Startup
   public void Configuration(IAppBuilder app)
      app.Use(new TraceLogger());

Important Middlewares


The OWIN compatible components include: SignalR, Web API and even static HTML pages.



System.Web / Web.Config Settings

Katana's System.Web adapter supports the following config options:

  <add key="owin:appStartup" value="StartupDemo.ProductionStartup" />
  <add key="owin:AutomaticAppStartup" value="true" />


OwinHost.exe will also read the owin:appStartup property from the Web.Config file as described above.


Routing with Web API hosting Web API with owin.

Install-Package Microsoft.AspNet.WebApi.OwinSelfHost