Getting Started With OWIN and the Katana Stack

OWIN and Katana is best way to build web server indipendent web applications in .NET ecosystem and this post will help you a bit on getting started.
2013-05-04 21:04
Tugberk Ugurlu


As usual, I tweeted about my excitement which finally led me to this blog post:

OWIN and Katana project is the effort moving towards that direction and even through it's at its early stages, the adoption is promising. Katana is a flexible set of components for building and hosting OWIN-based web applications. This is the definition that I pulled from its Codeplex site. The stack includes several so-called OWIN middlewares, server and host implementations which work with OWIN-based web applications. You can literally get your application going within no time without needing any installations on the machine other than .NET itself. The other benefit is that your application is not tied to one web server; you can choose any of the web server and host implementations at any time without needing to recompile your project's code.

To get started with Katana today, the best way is to jump to your Visual Studio and navigate to Tools > Library Package Manager > Package Manager Settings. From there, navigate to Package Sources and add the following sources:

Now, we should be able to see those sources through PMC (Package Manager Console):

image

We performed these actions because latest bits of the Katana and OWIN Hosting project are pushed to MyGet and those packages are what you want to work with for now. As you can guess, those packages are not stable and not meant to be for production use but good for demonstration cases :) Let's start writing some code and see the beauty.

I started by creating an empty C# Class Library project. Before moving forward, I would like to take a step back and see what packages I have. I selected the MyGet Owin as the current package source and executed the following command: Get-Package -ListAvailable -pre

image

These packages are coming from the OWIN Hosting project and I encourage you to check the source code out. Let's do the same for the MyGet Katana source:

image

We got more packages this time and these packages are coming from the Katana project which is hosted on Codeplex. These packages consist of OWIN middlewares, host and server implementations which we will have a chance to use some of them now.

Let's start installing a host implementation: Microsoft.Owin.Host.HttpListener pre-release package. Now, change the current package source selection to MyGet OWIN and install Owin.Extensions package to be able to get the necessary bits and pieces to complete our demo.

The Owin.Extensions package will bring down another package named Owin and that Owin package is the only necessary package to have actually. The others are just there to help us but as you can understand, there is no assembly hell involved when working with OWIN. In fact, the Owin.dll only contains one interface which is IAppBuilder. You may wonder how this thing even works then. The answer is simple actually: by convention and discoverability on pure .NET types. To get a more in depth answer on that question, check out Louis DeJardin's awesome talk on OWIN.

What we need to do now is have a class called Startup and that class will have a method called Configuration which takes an IAppBuilder implementation as a parameter.

public partial class Startup {

    public void Configuration(IAppBuilder app) {

        app.UseHandler(async (request, response) => {

            response.ContentType = "text/html";
            await response.WriteAsync("OWIN Hello World!!");
        });
    }
}

For the demonstration purposes, I used the UseHandler extension method to handle the requests and return the responses. In our case above, all paths will return the same response which is kind of silly but OK for demonstration purposes. To run this application, we need to some sort of a glue which needs to tie our Startup class with the host implementation that we have brought down: Microsoft.Owin.Host.HttpListener. That glue is the OwinHost.exe which we can install from the MyGet Katana NuGet feed.

image

OwinHost.exe is going to prepare the settings to host the application and give them to the hosting implementation. Then, it will get out of the way. To make it run, execute the OwinHost.exe without any arguments under the root of your project and you should see screen as below:

image

We got this unfriendly error message because the OwinHost.exe was unable to locate our assemblies as it looks under the bin directory but our project outputs the compiled assemblies under bin\Debug or bin\Release; depending on the configuration. Change the output directory to bin through the Properties menu, rebuild the solution and run the OwinHost.exe again. This time there should be no error and if we navigate to localhost:5000 (as 5000 is the default port), we should see that the response that we have prepared:

image

Cool! You may wonder how it knows to which host implementation to use. The default behavior is the auto-detect but we can explicitly specify the server type as well (however, it's kind of confusing how to do it today):

image

OwinHost.exe is great but as you can guess, it's not our only option. Thanks to Katana project, we can easily host our application on our own process. This option is particularly useful if you would like to deploy your application as a Windows Service or host your application on Windows Azure Worker Role. To demonstrate this option, I created a console application and referenced our assembly. Then, I installed Microsoft.Owin.Hosting package to be able to host it easily. Here is the code to do that:

class Program {

    static void Main(string[] args) {

        using (IDisposable server = WebApp.Start<Startup>()) {

            Console.WriteLine("Started...");
            Console.ReadKey();
        }
    }
}

When I run the console application now, I can navigate to localhost:5000 again and see my response:

image

I plan on writing a few more posts on OWIN-based applications but for now, that's all I can give away :) The code I demoed here is available on GitHub as well: https://github.com/tugberkugurlu/OwinSamples/tree/master/HelloWorldOwin. but run the Build.cmd file before starting.

Note: Earlier today, I was planning to play with ASP.NET Web API's official OWIN host implementation (which will come out in vNext) and writing a blog post on that. The playing part went well but Flip W. was again a Sergeant Buzzkill :s

 

References



New Comment