Making sense of the different versions of .NET Core (runtime and SDK)

“I was happily doing tutorials on v1.0 and once I knew enough, I took the plunge into 1.1 and it’s been hell the whole way through”nwss00 (Reddit)

The .NET Core journey has been confusing for most.

We’ve had alphas, betas and release candidates. All the way through, both the Runtime and Tools (SDK) have been changing at a rapid pace.

Microsoft decided late on to drop the new project.json file in favour of a revamped csproj project file. Consequently your applications created using older versions of the SDK/tools will have the now-deprecated project.json file.

You will need to use the latest version of the tools (and therefore csproj) to continue developing your .NET Core apps as Microsoft will be phasing out the previous versions.

Whilst everything has settled down a bit, the landscape is still a bit confusing, so let’s take stock.

Runtime != SDK

The first thing to know is that the Framework and SDK are separate things.

You can build and publish .NET Core 1.0 applications with the latest SDK as well as build and publish .NET Core 1.1 applications using some older versions of the SDK.

There are two production-ready versions of the runtime.

.NET Core 1.0.4

The first production (RTM) release of .NET Core. Considered stable enough for production use.

Just to complicate matters, there have been a few small patch releases to the 1.0 version, hence it’s now at 1.0.4.

.NET Core 1.1

Brings some improvements on 1.0.x Here are some of the highlights

  • Improved performance
  • Improved version of the Kestrel web server
  • Azure support
  • Azure and SQL 2016 support for EF Core

Choose your runtime

You are free to choose whichever of the two runtime versions you wish.

This decision has no bearing on whether you’ll end up with project.json or csproj, that detail is handled by the SDK.

You might want to keep in mind how long Microsoft will support the version you choose. There is a handy table on the Microsoft site which gives you that information (scroll down until you get to it).

.NET Core SDK 1.0.1

So that brings us on to the SDKs.

The latest SDK (at the time of writing) is 1.0.1.

Not to be confused with the runtime version, this version of the SDK can be used to create 1.0.x or 1.1 .NET Core applications.

Using this version of the SDK will mean that all your new applications get the csproj project file rather than the project.json version.

You can download the latest SDK from the official Microsoft site.

If you’re interested in the version history for .NET Core (runtime and SDK) you can see a handy overview on the dotnet core Github page.

Here’s what part of that page looks like at the time of writing.

Upgrading from project.json

If you have an existing web application which is using project.json, you should be able to upgrade it using the latest version of the SDK.

Once you have it installed, try running the migrate command in the root of your app.

dotnet migrate

For more details on the Migrate command, check out the official docs.

A word on Visual Studio

All of the detail outlined above applies to creating .NET Core projects using the command line (or other non-visual studio tools).

Visual Studio 2017

.NET Core support (including tools for the new csproj file) is baked in to Visual Studio 2017.

Any new .NET Core apps you create will be automatically include a csproj file. If you open an existing app (with a project.json file) in VS2017 it will also be upgraded.

Visual Studio 2015

Microsoft has decided not to pursue support for the new csproj file in Visual Studio 2015.

You can still install the NET Core tools Preview 2 for Visual Studio 2015 (still available on the official site at the time of writing) which makes VS2015 work with project.json.

However, given that MS has dropped project.json and won’t be supporting it going forward, this doesn’t seem like a long-term option and you will need to either use the SDK alongside other tools (e.g. command line or Visual Studio Code) or make the switch to Visual Studio 2017.

In Summary

The .NET Core picture is beginning to take shape.

Your best bet is to use the latest version of the SDK, adopt Visual Studio 2017 if you can (or stick to command line and other editors such as VS Code) and use the highest version of the .NET Core runtime that you’re able to (1.0.x or 1.1).

photo credit: langustefonts signpost in Fife, Scotland via photopin (license)