How I got ASP.NET vNext running on Mac OS X


Modern Slim MacBook Pro on White BackgroundThe next version of ASP.NET MVC (ASP.NET vNext) will run on a “cloud-optimized” platform which will work on Linux and Mac OS X with Mono, too. Here is how I got it running on my MacBook.

Important Note: ASP.NET vNext is still work in progress and it may not work as intended. Please do not use it in production!

Required Mono Version and Basics of K Runtime

First I installed Mono from source, because the current stable version (Mono 3.4.0) is not sufficient to run ASP.NET vNext applications. This will change when the next stable version of Mono is released. Then I installed the K Version Manager (KVM). KVM is used to manage different versions of the K Runtime the ASP.NET vNext runs on. Graeme Christie and Simon Timms blogged about how to install Mono from source and the KVM.

How you can use KVM to manage different versions of the K Runtime on your machine? Type kvm to see a list of available commands. The most important commands are:

  • kvm upgrade: Installs the latest KRE (K Runtime Environment).
  • kvm list: Lists the installed runtime environments.
  • kvm use: Switches to a specific kRE version.

A Simple “Hello, World” Program

Type kvm upgrade to install the latest KRE. Then create a file somewhere on your disk with the name “project.json” and the following content:

  "dependencies": {
    "System.Console": ""
  "configurations": {
    "net45": {},
    "k10": {}

Create another file in the same directory with the name “Program.cs” and the following C# program as content:

using System;
public class Program
    public static void Main()
        Console.WriteLine("Hello, World!");

The first file is the project file. It contains the dependencies and describes the runtime configurations. The dependencies are NuGet packages. You can use the K Package Manager (KPM) to work with the packages. Type kpm help or kpm to get an overview of the kpm commands. Restore the packages by typing kpm restore now and run the program with k run.

When I was experimenting with ASP.NET vNext I ran into some errors:

  • System.AggregateException: —> System.IO.IOException: Too many open files“. Solution: increase the maxfiles limit of your system:
> launchctl limit maxfiles 16384 32768
  • Could not load type ‘System.Reflection.Internal.MemoryMappedFileBlock’ from assembly ‘System.Reflection.Metadata, Version=, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a’.System.Reflection.Internal.Metadata” Solution: Check the Mono version with mono --version and make sure that the correct version of Mono can be found in your PATH variable.

ASP.NET MVC Project Generator for Yeoman

An MVC application consists of controllers, views, model and configuration files and maybe other files needed by the program. A scaffolding tool can create new projects from a template or a generator. One of those tools is Yeoman and Hassakarn C. wrote an ASP.NET MVC Project Generator for Yeoman which can create projects for ASP.NET vNext.

If you want to use Yeoman you’ll have to install Node.js. Follow the instructions on its homepage. It comes with NPM, the Node Package Manager, which you can use to install Yeoman and the ASP.NET MVC Project Generator:

> npm install -g yo
> npm install -g generator-aspnet

You can create a new project for the K Runtime by running:

> yo aspnet

Then you can select the type of application you want to create.

Screenshot ASP.NET MVC Project Generator for Yeoman

If you create a console application, you can run your program with k run. It is the same application we built before without Yeoman.

k run runs the program by invoking its entry point, a static method called Main. An MVC program doesn’t have such a method. When you open the “project.json” file of the MVC application you’ll find a section called commands:

  "commands": {
    "web": "Microsoft.AspNet.Hosting --server Microsoft.AspNet.Server.WebListener --server.urls http://localhost:5001",
    "kestrel": "Microsoft.AspNet.Hosting --server Kestrel"

This section defines commands which you can use instead of run when you invoke k. As you can see there are two commands defined: web and kestrel. web invokes a server used for self-hosted ASP.NET programs. It doesn’t work on OS X yet. But you can use the alternative Kestrel server which is a libuv-based HTTP server for .NET.

You can run your MVC application with Kestrel with this command:

> k kestrel

The default port is 5000. If you navigate your browser to http://localhost:5000 you should see the default welcome page of ASP.NET vNext.

If you try to start the application with k run you’ll get an error with the following message: “<appname> does not contain a static ‘Main’ method suitable for an entry point“. So make sure that you type the right command for your type of application.

Creating Nancy Projects with Yeoman

Inspired by the Yeoman generator for ASP.NET MVC Jonathan Channon created a generator for the Nancy framework. Nancy is a lightweight framework for building HTTP based services on .NET and Mono. You can install the generator via npm:

> npm install -g generator-nancy

For creating a Nancy project type the following into your terminal:

> yo nancy

The generated project contains a simple Nancy module which is hosted on Kestrel with the OWIN interface. You can start the Nancy application with the k command:

> k kestrel

Using Sublime Text 3 for Working With ASP.NET vNext Projects

One of my favorite text editors is Sublime Text. It can be extended by plugins and Sourabh Shirhatti started working on an extension for ASP.NET vNext, called “Kulture”. He demonstrates the extension in a YouTube video.

You will need Sublime Text 3 which is still in beta and the Package Manager for Sublime Text 3 if you want to try it. Then press Cmd-Shift-P which opens the Command Palette and select “Package Control: Install Package”. Then select “Kulture” from the package list.

The extension configures the Sublime Text Build System for builds with the K Runtime. When you opened an ASP.NET vNext project from the project directory you can build it by pressing Cmd-B. If there are compilation errors you can cycle through them with F4. And with Cmd-Shift-P you can select “Run K Commands” and start one of the commands defined in the project.json file.


With ASP.NET vNext Microsoft tries to build ASP.NET on a new platform which can be run on UNIX like operating systems like Linux or Mac OS X. In this article I showed you how you can install it and how you can run a simple “Hello, world!” program. I introduced you to the Yeoman scaffolding tool and two generators, one for creating MVC apps and one for creating Nancy apps. Finally I showed you an extension for the popular Sublime Text editor.

It’s interesting to see new ideas coming from the community. I’m curious how the new tools will evolve and how creating applications on ASP.NET vNext and Mono will look like in a few months.