"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)

Note: Updated 9th August 2018 to reflect latest releases of .NET Core 2.1.x

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 Runtime 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 several production-ready versions of the runtime.

.NET Core 2.1.x

The latest and greatest.

This is where .NET Core really starts to make sense for production use and a lot of the bugs have been ironed out.

.NET Core 1.0.x

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

.NET Core 1.1.6

Brought some improvements on 1.0.x Here were some of the highlights

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

If you’re starting a new .NET Core project you’re really better off sticking with 2.1.x. There was a general feeling that 1.1.x, whilst “production ready” had some pretty big gaps in functionality and was still pretty rough around the edges.

Choose your runtime

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

But 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 2.x

So that brings us on to the SDKs.

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

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

This is the SDK that goes alongside .NET Core 2.1.2 (you don’t need to download the runtime separately, you can just grab this SDK and it will install everything).

.NET Core SDK 1.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.

If you used an early version of .NET Core you may have encountered project.json files. They are now consigned to history and your new applications will get a csproj project file instead.

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 looked like at the time of writing.

Upgrading from project.json

If you have an older asp.net core web application still using 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.

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