ASP.NET 5 (formerly known as ASP .NET vNext) is the next generation of ASP .NET, still in a prerelease state. At the time of writing, the current runtime version is 1.0.0-rc1-update1, and ASP .NET 5 is set to launch in Q1 2016. The APIs seen here may change in the time leading up to that release; in fact, this article is written precisely to address recent API changes.

ASP .NET 5 is a game changer, and everything we’ve learned in ASP .NET so far no longer applies. In this article, we’ll see how to do a basic “Hello World” with ASP .NET 5. This usually sounds like something easy, but given that things are changing pretty quickly (even fundamental things such as the IIS hosting model), it’s not. In fact, I would have liked to say you can create a new project in Visual Studio and select the “Empty” ASP .NET 5 Preview Template:

Unfortunately, however, these templates are so outdated that they no longer work. Starting with these and getting them to work is an exercise in frustration. Fortunately, however, there’s an alternative way to easily set up an ASP .NET 5 project. And, surprise surprise, it does not involve Visual Studio.

Update 27th December 2015: If you do want to use the latest Visual Studio templates, install Visual Studio 2015 Update 1 as well as the latest ASP .NET 5 Release Candidate.

Yeoman provides a tool called yo, which allows you to create a new web application from various different templates. Nowadays, with so many tools and technologies, it is sometimes difficult to piece things together. You can use yo and its generators to set up a web application with the bits and pieces you need without much effort. For example:

• Want to create an AngularJS Single-Page App (SPA)? No problem, there’s a generator for that.
• Want to create an ASP .NET MVC application? No problem, there’s a generator for that.
• Want to create an ASP .NET 5 empty application? No problem, there’s a generator for that too.
• Want a full rack of barbecue ribs with fries? I don’t think there’s a generator for that, but perhaps someone may write one someday.

Like various other web tools, yo and its generators require npm, the node.js package manager. You will first need to install node.js, and npm comes packaged with it. You can then install yo by running the following command from the command prompt:

npm install -g yo

In order to generate a web application template, yo relies on plugins, called generators. At the time of writing, there are several generators for ASP .NET 5, but generator-aspnet is the only one that’s up to date. Let’s also install it using the following command:

npm install -g generator-aspnet

With that done, we can now generate our ASP .NET project. You can either invoke yo and do it interactively:

…or just invoke the following command:

yo aspnet

You will then be asked a few questions that allow you to configure your ASP .NET 5 project. For starters, we’ll create an Empty Application:

You will then be asked for the name of your application, after which the web app skeleton will be generated, and you will be told the commands you need to build and run it:

Before we run these commands, let’s take a second to see what our project actually contains. The files we care about are Startup.cs…

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNet.Builder;
using Microsoft.AspNet.Hosting;
using Microsoft.AspNet.Http;
using Microsoft.Extensions.DependencyInjection;

namespace myapp
{
    public class Startup
    {
        // This method gets called by the runtime. Use this method to add services to the container.
        // For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?LinkID=398940
        public void ConfigureServices(IServiceCollection services)
        {
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app)
        {
            app.UseIISPlatformHandler();

            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Hello World!");
            });
        }

        // Entry point for the application.
        public static void Main(string[] args) => Microsoft.AspNet.Hosting.WebApplication.Run<Startup>(args);
    }
}

…and project.json:

{
  "version": "1.0.0-*",
  "compilationOptions": {
    "emitEntryPoint": true
  },
  "tooling": {
    "defaultNamespace": "myapp"
  },

  "dependencies": {
    "Microsoft.AspNet.IISPlatformHandler": "1.0.0-rc1-final",
    "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final"
  },

  "commands": {
    "web": "Microsoft.AspNet.Server.Kestrel"
  },

  "frameworks": {
    "dnx451": { },
    "dnxcore50": { }
  },

  "exclude": [
    "wwwroot",
    "node_modules"
  ],
  "publishExclude": [
    "**.user",
    "**.vspscc"
  ]
}

Now, in order to proceed, you need to have the DNX tools (dnu, dnvm and dnx). If you don’t have them, you can get them when you install Visual Studio 2015, or by following the instructions on the ASP .NET 5 Github page. You may also need to upgrade to the latest runtimes (use dnvm list to check what you’re using, dnvm upgrade to get the latest, and dnvm use <runtime> to switch to the latest) – learning to use the DNX tools is beyond the scope of this article.

Once you have DNX in place, you can run the commands suggested by the aspnet generator earlier. First, cd into the application directory:

cd myapp

Then, run the following command to restore packages (essentially works like NuGet):

dnu restore

You can now build the web application using the following command:

dnu build

Finally, the following command runs the application. You’ll notice that web is actually one of the commands defined in the project.json we saw earlier.

dnx web

As shown in the screenshot above, the web application is hosted at localhost:5000 by default. Indeed, we can confirm that this works by going there:

The output we see comes from Startup.cs as we have seen earlier:

        public void Configure(IApplicationBuilder app)
        {
            app.UseIISPlatformHandler();

            app.Run(async (context) =>
            {
                await context.Response.WriteAsync("Hello World!");
            });
        }

The Configure() method allows us to set up our web application pipeline. In here, we define any middleware we need. For example, if we want to use MVC, then we set it up here; but ASP .NET 5 does not assume that any such infrastructure is required by default. In this case, we are always giving a fixed response.

This is as far as I’m going to go with this little “Hello World” setup for ASP .NET 5. We haven’t even begun to see how different ASP .NET 5 is from the ASP .NET we have known so far. But hopefully, this article will save you a lot of frustration in setting things up until the tooling in Visual Studio 2015 catches up.