Upgrading from ASP.NET 5 RC1 to ASP.NET Core RC2

ASP.NET 5 is dead. Long live .NET Core!

ASP.NET 5 has been through more than a name change. dnvm, dnu and dnx are gone, all replaced with a single dotnet command.

There are a number of new ideas, one of the most immediate being that all .NET Core applications are console applications. Yep, even your fancy web applications (like this very site) are all just console applications now. How very retro.

Follow along with how I upgraded from ASP.NET 5 RC1 to ASP.NET Core RC2 and hopefully this may even help you avoid some of the headaches that came with this update.

Step 1 - Install the framework

Installing the .NET Core framework is remarkably simple, especially when compared to previous releases of ASP.NET 5. So simple, I’m not even going to go through it here and instead just tell you to follow the (at most) 4 step procedure at the official site.

Step 2 - Update your references

One major part of the rename to .NET Core is a renaming of namespaces to match

All the versions of these packages have also been reset to 1.0.0-rc2-final

.NET Core itself is now a dependency. That's right, the runtime for an application is now just a dependency of the application. So we need to add it to our dependencies

"dependencies": {
    "Microsoft.NETCore.App": {
      "version": "1.0.0-rc2-3002702",
      "type": "platform"
    },
    "Microsoft.AspNetCore.Server.Kestrel": "1.0.0-rc2-final",
    "Microsoft.AspNetCore.Mvc": "1.0.0-rc2-final",
    "Microsoft.AspNetCore.Diagnostics": "1.0.0-rc2-final",
    "Microsoft.AspNetCore.StaticFiles": "1.0.0-rc2-final",
    "Microsoft.Extensions.Configuration.Json": "1.0.0-rc2-final",
    "Microsoft.EntityFrameworkCore": "1.0.0-rc2-final",
    "Microsoft.EntityFrameworkCore.Relational": "1.0.0-rc2-final",
    "Microsoft.AspNetCore.Identity.EntityFrameworkCore": "1.0.0-rc2-final"
  }

One particular package which was affected by the name change is how
Microsoft.AspNet.Identity.EntityFramework has become Microsoft.AspNetCore.Identity.EntityFrameworkCore

Some other popular packages have released new versions which are compatible with .NET Core so they are definitely worth upgrading to.

"AutoMapper": "5.0.0-beta-1",
"Humanizer.Core": "2.0.1",
"Npgsql.EntityFrameworkCore.PostgreSQL": "1.0.0-rc2-release1"

Step 3

Namespaces have changed, don't forget to update their usages in code. So

using Microsoft.AspNet.Mvc;

now becomes

using Microsoft.AspNetCore.Mvc;

Some namespaces are no longer required, tag helpers are now included by default, so Microsoft.AspNet.Mvc.TagHelpers doesnt have to be included in your using directives.

Another major change to the structure of project.json is to the frameworks section.
What was previously

"frameworks": {
  "dnx451": {}
}

now becomes

"frameworks": {
  "netcoreapp1.0": {
    "imports": [
      "dotnet5.6",
      "dnxcore50",
      "portable-net452+win81"
    ]
  }
}

Looks painful, but without this change you will have problems ranging from your application not compiling to it becoming self-aware and giving you a good telling off.

One final change is that compilationOptions is now buildOptions and has a new property

"buildOptions": {
  "emitEntryPoint": true
}

Step 4 - Program.cs

As I previously mentioned all .NET Core applications are console applications. So if our web application is now a console application it needs an entry point.
This is where we need to add in our usual Program.cs to act as our entry point. We already have all of our application configuration specified in our Startup class so we can tell our application to use it as below

using System;
using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace TheObjectifiedProgrammer
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseStartup<Startup>()
                .Build();

            host.Run();
        }
    }
}

Now to start our web application we cd to the application root to restore dependencies and run the application

dotnet restore
dotnet run

This will start the application, automatically listening on http://localhost:5000. Check out how to configure how the application starts here.