Hello, world

If you want to jump straight to the solution, the end result of this walkthrough is available on GitHub

Starting a new Visual Studio solution

The most educational way of doing this walkthrough is by starting from a completely empty project and add all of the code. You don't need to actually type the code, copy/paste will work just fine.

1. In Visual Studio start a new project of type "ASP.NET Empty Web Application". This will create a project that contains very little.
2. Go to the NuGet package manager or use Paket to install these NuGet packages
   • Ioc.Modules.Ninject
   • Owin.Framework
   • Owin.Framework.Urchin
   • Owin.Framework.Pages.Core
   • Owin.Framework.Pages.Framework
   • Owin.Framework.Pages.Html
   • Microsoft.Owin.Host.SystemWeb

install-package Owin.Framework
install-package Ioc.Modules.Ninject
install-package Owin.Framework.Urchin
install-package Owin.Framework.Pages.Framework -IncludePrerelease
install-package Owin.Framework.Pages.Html -IncludePrerelease
install-package Microsoft.Owin.Host.SystemWeb -version 2.1.0

Configure your project as an OWIN website hosted on IIS

Note that this step would be required for any OWIN application and is not specific to getting started with the Owin Framework.

1. Modify the web.config file to use the ExtensionlessUrlHandler. You can use this file as an example of what this should look like.
2. In the root of your project add a new Startup.cs file and under the using statements and above the namespace statement add

   [assembly: OwinStartup(typeof(Startup))]

   Resolve references and make sure it compiles.
3. In the Startup class add a method with ths signature

   public void Configuration(IAppBuilder app)
   {
   }

4. Add the necessary using statements so that the code compiles.

Configure an IoC container

For this walkthrough we are going to use Ninject and Urchin, but you can use any IoC container and any configuration mechanism you choose. There is documentation you can read and copy code from, or you can copy from the completed example

Read the documentation to figure out what code you need to add, or just copy the code below to get going quickly.

var packageLocator = new PackageLocator()
   .ProbeBinFolderAssemblies()
   .Add(Assembly.GetExecutingAssembly());
var ninject = new StandardKernel(new Ioc.Modules.Ninject.Module(packageLocator));

Set up the Owin Framework middleware pipeline

This is the first step in this walktrhough that is specific to the Owin Framework

You can review the documentation on Owin Framework configuration, or you can look at Startup.cs for a working example to copy from.

An example of the type of code you will need to add to your Startup class is shown below for reference. In a real application there are a number of ways that you can write this code. For this walkthrough you can copy/paste if you like.

var config = ninject.Get<IConfiguration>();
var pipelineBuilder = ninject.Get<IBuilder>();
pipelineBuilder.Register(ninject.Get<PagesMiddleware>()).ConfigureWith(config, "/pages");
app.UseBuilder(pipelineBuilder);

Configure the Pages middleware

In this section you will configure the Pages middleware to scan your compiled code and construct web pages from classes that are decorated with custom attributes.

1. At the end of the Configuration method in your Startup class, resolve IFluentBuilder from your IoC container, for example

   var fluentBuilder = ninject.Get<IFluentBuilder>();

2. Install the Html element build engine with code similar to this:

   ninject.Get<OwinFramework.Pages.Html.BuildEngine>().Install(fluentBuilder);

3. Get the fluent builder to scan your application assembly for classes that are decorated with attributes that makes them into definitions of pages, regions, layouts etc. The fluent builder will use the build engines that we configured earlier. The extra line of code you need to add for this is:

   fluentBuilder.Register(Assembly.GetExecutingAssembly());

4. Finally, after registering all of the elements of your website with the fluent builder you need to bind the elements together because they can reference each other by name, and they can be registered in any order. You will need these two lines of code to do this:

   var nameManager = ninject.Get<INameManager>();
   nameManager.Bind();

Add some elements to your website

At this point your website is scanning the classes compiled into the application assembly and registering them with the element builder, but it will not find any classes like that because we did not add any yet.

The code you wrote so far scans the main assembly of your application, so you can add pages, regions, layouts, components, templates etc anywhere within the source code and they will be discovered. It is entirely up to you how you organize these classes, but you might like to read the Best Practice Guide before moving on from this getting started example.

If you want to finish up the "Hello, World" example you can copy code from Startup.cs, or you can experiment with creating some pages of your own. If you would like to see some examples of how to define these page elements you can check out this source file.

A compact version of Hello World can be written like this:

[IsPage]                                                   // This is a webpage
[Route("/", Method.Get)]                                   // This page is served for GET requets for the website root
[PageTitle("Getting started with Owin Framework Pages")]   // Specifies the page title
[UsesLayout("homePageLayout")]                             // The layout of this page is 'homePageLayout'
internal class HomePage { }
[IsLayout("homePageLayout", "region1")]                    // The 'homePageLayout' has 1 region called 'region1'
[RegionHtml("region1", "hello-world", "Hello, world")]     // Region 1 contains static Html
internal class HomePageLayout { }

If you press F5 at this point the project should comiple and launch IIS express to display the web page. Try using the "View Source" option in your browser to see the HTML that was produced.

You will see that the HTML contains comments to help you to identify the layouts, regions and components that were involved in constructing the HTML. You can turn off these comments by configuring the Pages middleware like this:

var configurationStore = ninject.Get<IConfigurationStore>();
configurationStore.UpdateConfiguration(
@"{
    ""owinFramework"":{
        ""pages"":{
            ""html"":{
                ""IncludeComments"":false
            }
        }
    }
}");

You can read more about configuration within the Owin Framework here.