This post is for developers that have been using the Microsoft Owin components (e.g. the Katana project) and want to know how it relates to ASP.NET 5.

As discussed in Katana’s roadmap, the next major version of Katana is being fully integrated into ASP.NET 5. This integration has resulted in several changes that make Katana v3.0 based components not directly compatible with 5. Developers and consumers of v3.0 based components may choose to fully migrate their components or use OWIN to help bridge the gap.

Migrate

Developers may choose to update their components to integrate directly with ASP.NET 5. ASP.NET 5 builds on the concepts, designs, and components initially developed in Katana so the migration process should be largely mechanical.Here is a list of changes made to Katana components that developers can use as a guide when migrating their own components. I will use the StaticFile middleware as a reference to demonstrate most of the changes.

Hosting and Repositories

The first thing you’ll notice looking at the roadmap is that we are building the new components on GitHub. The new code base is divided into many smaller repositories, with the roadmap showing where each component moved to.

Packages and Versions

The next most obvious change is renaming the packages and namespaces from Microsoft.Owin.* to Microsoft.AspNet.* to conform to the rest of ASP.NET. Due to the rename the package versions have been reset to v1.0.0.

Startup

The Startup class conventions have been refined. Katana would search for an assembly that specified the OwinStartup attribute and then fallback to searching all assemblies for a class named Startup or AssemblyName.Startup. ASP.NET does not define an attribute and it only searches the primary application assembly for a type named Startup (in any namespace). The Configuration(IAppBuilder app) method is now Configure(IApplicationBuilder app). Middleware can still define extension methods to add themselves to the pipeline.

Dependency Injection

The availability and usage of dependency injection has been significantly expanded. The Startup class constructor and its Configure method can both have parameters injected. IApplicationBuilder.ApplicationServices is the IServiceProvider available for any manual dependency resolution. Middleware can also take constructor parameters via injection, as well as having services injected per-request as parameters to the Invoke method. Middleware and applications can also access services from HttpContext.ApplicationServices or RequestServices.

Request Object Model

Implementing middleware should look familiar with a next parameter and an Invoke method. The IOwinContext family of APIs have been renamed to HttpContext but don’t worry, it’s not the old System.Web HttpContext; moving middleware over should only need to account for minor refactoring. Under the hood things are a little different though. IOwinContext’s default implementation was based on the raw OWIN abstraction. HttpContext’s default implementation is based on an IFeatureCollection that exposes groups of functionality via feature interfaces. These feature interfaces can be implemented on top of different servers (or on top of the OWIN abstraction), making the object model server independent. See this Channel 9 video for more details.

Platform

With ASP.NET 5 comes support for a new platform, the “cloud-optimized CLR”. Most of the ASP.NET 5 components have been cross-compiled to target both the full .NET CLR and the new platform. Katana v3.0 based components only target the full .NET CLR and will not run on the new platform.

Almost all of the Katana components have already been migrated to ASP.NET 5, there are just a few security middleware and the CORS middleware remaining. Note that migrated components will not be usable in a Katana v3 based application. Migration may also not be an option if you do not own the component.

OWIN Interop

Some developers will need their components to work with both Katana v3.0 based applications and ASP.NET 5. Developers and consumers may also not have the option to migrate their components and must attempt to use them as is. Katana v3.0 and ASP.NET 5 both support extensibility via OWIN and this can be used to enable interop between the two. OWIN is a community standard designed to reduce component interdependencies in an HTTP pipeline for improved interoperability. OWIN based components can plug into ASP.NET 5 using the new OWIN pipeline builder (the standard is still a work in progress) or IAppBuilder extensions.

OWIN Builder

ASP.NET 5 has built in support for the new OWIN pipeline builder model. See the extensions and samples. Middleware may use any OWIN helpers they wish internally, including the IOwinContext if that’s what they’re already using. Middleware that depend on IAppBuilder and/or the OwinMiddleware base class won’t be able to use the OWIN pipeline builder approach directly. Removing these dependencies is recommended.

IAppBuilder Bridge

Middleware that can’t remove their IAppBuilder or OwinMiddleware dependencies can use a modified approach to run in ASP.NET 5. See this linked sample for an IApplicationBuilder extension that provides an IAppBuilder for use with Katana v3 based middleware. This extension creates a new AppBuilder instance and then wraps the OWIN pipeline builder pattern around it to integrate into ASP.NET 5. The sample also shows how to populate IAppBuilder.Properties data that the middleware may depend on, the data protection provider in this case.

The Thinktecture folks helped write this sample and used it to get their Katana v3 based identity framework up and running on ASP.NET 5, including Katana security middleware and Web API v2. This is a nice quick way to get existing components up and running, but should be considered a temporary solution. The OWIN community is moving away from IAppBuilder in favor of the OWIN pipeline builder referenced above. The Katana v3.0 versions of migrated components will also only receive incremental bug fixes, not new feature development. As noted above, Katana components will only work on the full .NET framework, not on the new Core framework.

Note that the OWIN integration is limited to standard and common functionality defined by the community so not all ASP.NET 5 features will be available. For example parts the security middleware pattern will not be able to interoperate across between OWIN and ASP.NET 5 because OWIN does not define a standard for them.

This post was written by Chris Ross. He can be reached on Twitter @tratcher