Where’s Lou

Hello all! This blog post is about OWIN and we’ll look at an owin-sandbox repo that has been created to help test drive the draft spec to bring it closer to a release point. But first there a few notes about things that have been renamed.

The generic self-host process Ghost.exe has been renamed Katana.exe and moved to its own its own git repo. It was originally in the Gate solution but that didn’t make a lot of sense in the end.

Secondly the C# http server Dragonfly.dll has been renamed Firefly.dll. There are simply too many software projects named Dragonfly. :)

Now! To jump right into a diagram.

Here is what it looks like when you have a process with a startup that wires the OWIN call up to the middleware and web frameworks you are using. At that point you have requests from the world call through that stack to your code.

Something very important here is the orange line which is the OWIN event horizon. The significance: if you want to achieve the goal of everything above the orange line being re-hostable on different server implementations, then you can’t directly reference anything from a specific server’s implementation which is below the line.

How is that accomplished in practice? By adding the Startup class to your code which is passed an IAppBuilder as an argument. Your Startup class is free to reference any web frameworks you want to use, and can chain in any middleware, and will do other one-time initialization things like construct your IoC container and configure routing. The only thing you want to avoid is compiling directly against the specifics of a particular web server, like HttpListener, Kayak, Firefly, IIS, or others. Here’s a simple example from the owin-sandbox:

using Gate.Adapters.Nancy;
using Nancy;
using Owin;
using Utils;

namespace Case05_JustNancy
{
    public class Startup
    {
        public void Configuration(IAppBuilder builder)
        {
            builder
                .Use<AppTaskDelegate>(Middleware.LogRequests)
                .RunNancy();
        }
    }

    public class HomeModule : NancyModule
    {
        public HomeModule()
        {
            Get["/"] = _ => "Hello world!";
        }
    }
}

This project compiles as a class library and in a bin subfolder. Why do that? Well – frankly – that way you are compatible with IIS and you can use existing ASP.NET hosting providers, or deploy to your existing corporate servers, without any headaches.

But beyond that, what if you want to run this same web app as a self-hosted executable without changing anything or even recompiling? That’s exactly where Katana.exe comes in. It loads and calls your Startup class directly, and also loads the http server assembly of your choosing based on a server command-line argument or OWIN_SERVER environment variable.

A quick way to see this working in the owin-sandbox is to Download as zip an extract all the files. In the base there is a click-to-start.cmd file which will compile and start all of the case studies simultaneously.

Or, if you prefer, you can also install Katana.exe with Chocolatey and run your web app from the command line directly.

cinst katana
git clone https://github.com/owin/owin-sandbox.git
cd owin-sandbox\src\Case05_JustNancy
msbuild
katana --server kayak

And if you don’t have Chocolatey installed yet, you need to fix that situation right away! :) Run the following one-liner from an admin cmd prompt:

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('http://bit.ly/psChocInstall'))"

Well, thanks again, and I hope this works well for you. The next blog post should probably be a recap of the different components that are connected to this sandbox, OWIN, Gate, Katana, Coral, Sake, etc. and talking a bit about what they do and where they live at the moment.