ASP.NET vNext running on Mac.

An ASP5 Web Application hosted using Kestrel running on Yosemite

Since Microsoft announced their cross-platform goals last year I’ve been increasingly excited to see their new platform in action, yet up until this weekend all I’d done is read through their GitHub docs.

Until trying to do this, I’ve only really guessed at how all these pieces that Microsoft have released over the last few months fit together. Something that I think confuses people is understanding how Mono, .NET, ASP.NET vNext fit together and hopefully information here will clear things up for those who wondered the same as me.

It’s relatively simple to get up and running with an ASP5 Web Application on Mac, though I did run into some issues with the dependency versions. I’m assuming it’s down to the fact that this platform is still under heavy development and things change very quickly.

Mono is still the only runtime available to Mac and Linux users that allows you to run vNext applications. The new CoreCLR will eventually supersede Mono and this is why K is such an important part of the up and coming infrastructure. You don’t want to have to spend ages porting your application to essentially another platform, right?

If you think about it like this: Mono is the only thing capable of running any C# on Mac or Linux. For now.

Prerequisites:

• Homebrew — Unless you don’t mind compiling Mono and the K runtime yourself, it’s easier just to brew install.

At the time of writing this, the current runtime version is 1.0.0-beta3–11030.

Assuming Homebrew is installed and you’re in your Terminal:

Let’s add the repository for K:

$ brew tap aspnet/k

Then we can just install KVM with the following command:

$ brew install kvm

KVM has a dependency on Mono. This will install the latest version available in the Homebrew repositories (which is 3.10 as of writing this, though 3.12 is available if you compile from source).

K contains a set of utilities for running, installing and managing your applications. A core principal here is self-containment — all you need is your source code and the K runtime to run your application.

To gain access to these utilities you’ll want to run the kvm.sh file in order to add them to your working path:

$ source kvm.sh

If you want the utilities available all the time it might be worth adding them to your .bash_profile.

So we have Mono and we have K, now we need the glue that allows our Web Application to run through K on top of Mono:

$ kvm upgrade

This should install the latest version of the K Runtime Environment.

Now we have all our core components, we need some code and we can run!

I’ve setup a basic project that can be downloaded from my GitHub. Just clone that somewhere, and cd into the directory you’ve clone. It’s just the ASP vNext Start Page:

$ git clone git@github.com:iamthemovie/vnext-demo.git
$ cd vnext-demo

The project.json file contained within the directory defines absolutely everything externally (apart from the self-contained runtime) the project needs to be able to run. All our packages are listed and the command to run the web server which you’ll see is also a dependency included for package restore:

{
    "webroot": "wwwroot",
    "version": "1.0.0-*",
    "exclude": [
        "wwwroot"
    ],
    "packExclude": [
        "**.kproj",
        "**.user",
        "**.vspscc"
    ],
    "dependencies": {
        "Microsoft.AspNet.Server.IIS": "1.0.0-beta3",
        "Microsoft.AspNet.Diagnostics": "1.0.0-beta3",
        "Microsoft.AspNet.Hosting": "1.0.0-beta3",
        "Kestrel": "1.0.0-beta3",
    },
    "commands": {
        "kestrel": "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5004"

    },
    "frameworks" : {
        "aspnet50" : { },
        "aspnetcore50" : { }
    }
}

Next we’ll need to use KPM to initiate a package restore. So everything described in that project file is retrieved from NuGet and used to run our Web Application:

$ kpm restore

And finally we use the K command to run commands defined in our project file, in this instance the project file defines “kestrel” as the command to start the web server and load our application on http://localhost:5004:

$ k kestrel

You should get …

To quit: hit enter! If you use Ctrl + C it will disable the use of enter and you’ll have to kill the process manually!

Explaining K.

Microsoft, albeit their good intentions, never fail to confuse the hell out of people with their naming of core components.

K (the KRE) is effectively the cross-platform runtime that will eventually allow us to seamlessly run our vNext applications cross-platform. It contains the core infrastructure (Package / Dependency Management, a Dependency Injection Stack) that allows you to run applications on top of Mono, .NET, and the up and coming CoreCLR without needing to change any of your application to suit. Nifty eh?

K (the command) is used to initiate commands defined in our JSON project files. Whether it be for ASP5 console apps or running your website in a development server on Mac, Linux or Windows. K uses the runtime selected and manages the entry point bootstrapping to either Mono, the .NET Runtime and eventually the CoreCLR.

KVM is a version manager. It allows you to run multiple versions of different runtimes side-by-side on your machine. If you want to test your vNext application on Mono then switch to the .NET Runtime you can, in one command. I’ll stop there about runtime versions though.

Well done Microsoft for confusing the crap out of anyone using the core VM platform that ships with Linux.

KPM is a package manager. Microsoft are trying to develop a pluggable architecture in which you can, similarly to NodeJS, download the source of your application and run:

kpm restore

Every dependency including the hosting architecture is contained within your ASP5 dependencies. So as you’ll see, when running an ASP Web application on Mac this comes in handy.