TL;DR

You can skip the preamble and go directly to the relevant facts, or continue to read:

The whole story

Managing the development of .NET Core and ASP.NET Core apps can become a daunting task, in these days, due to:

The well-known, needful but painful move from “project.json” to “.csproj” file

Two differentiated (“Long-Term Support” and a “Current”) releases of .NET Core runtimes and SDKs

Multiple versions of .NET Core and SDK that can be installed SxS (side by side)

Visual Studio 2015 and Visual Studio 2017 RC that can be installed SxS

Many different ways to create an ASP.NET project (from the command line, with Yeoman generators, with VS 2015 and VS 2017 templates, migrating from older version, …)

Moreover, there are some things we still need to cope with:

The tools are still in beta! We all know that this is unfortunate (to be polite) but Microsoft is very transparent on this: they are working hard to fill the gap ASAP (see ASP.NET Community Standup).

The new csproj file and the new SDK tools are built for VS 2017 RC (ad upward) only. This means that if you migrate a project based on “project.json” to a project based on “.csproj” file, you will not be able to build it with VS 2015 anymore.

Knowing that, let’s see what we can do to succeed with side by side installed versions of .NET Core, SDK and Visual Studio, because every other scenario is a subset of this one and can be easily managed in the same manner.

I’ll start with download instructions to have all installed side by side, then I’ll explain where all those stuffs are installed and remark some relevant facts about the preview2 and preview3 versions of the tools, and finally describe a solution to an issue generated by the existence of multiple tools versions installed side by side on the same machine.

.NET Core Runtime and SDKs installation notes

.NET Core doesn’t prescribe a specific installation folder (you can move it around as long as you set the PATH accordingly), but the installers by default use the “C.\Program Files\dotnet” as the root folder.

Each version of the runtime is contained in a version named folder inside the “Microsoft.NETCore.App” folder.

At the time of writing, the Preview2 latest version is “1.0.0-preview2-1-003177”.

At the time of writing, the Preview3 latest version is “1.0.0-preview3-004056”.

Relevant facts

Here are the things you need to know to survive when having multiple versions of .NET runtimes and SDK tools versions:

The preview2.x version of the tools use the “project.json” file and is the greatest version of the tools that Visual Studio 2015 can use.

The preview3 version of the tools use the “.csproj” file and is the first version of the tools that Visual Studio 2017 RC can use.

Project based on the “.csproj” file and the preview3 version of the tools cannot be built in Visual Studio 2015.

Due to the unfortunate previous versioning schema, the “1.0.0” prefix of preview version does not reflect the targeted .NET Core version. In fact, both the “1.0.0-preview2-1-003177” and the “1.0.0-preview3-004056” versions of the SDK tools do work perfectly well with .NET Core 1.1 runtime versions. This is one of the things that are already been solved, because future versions of the tools will be prefixed accordingly to the .NET Core runtime.

When multiple versions of the tools are installed (as in this case), a “global.json” file placed at the root of the solution can be used to declare what is the desired version of tools to be used. If not present, the latest version of the tools will be used.

Global.json to the rescue

A common issue that may happen after installing Visual Studio 2017 RC is to open with Visual Studio 2015 a previously perfectly building ASP.NET Core app and discover that all stopped working, with lots of strange errors.

Cause:

When installing the VS2017, a newer version of SDK tools is installed in your PC (“1.0.0-preview3-004056”, at the time of writing).

We know that without a “global.json” file at the solution root, the latest SDK tools set will be used (in this case, the “preview3” one).

We know that (sadly) Visual Studio 2015 can’t cope with “Preview3”, so we need to declare that we want to use the latest “Preview2” version.

Solution:

Create a file named “global.json” that explicitly require the latest “Preview-2” version of the .NET Core SDK, where the version value is the latest “Preview2” installed in the machine (usually found in the “C:\Program Files\dotnet\SDK” folder), and save it in the root folder of your solution.

Hope this will help and prevent yourself from uninstalling Visual Studio 2017 RC from your machine.

There is an error running through your article though. I believe every occurrence of the Preview3 version number is incorrect. In your article you have written the version number as 1.0.0-preview3-1-004056, however it should be 1.0.0-preview3-004056 ( no -1). I believe that in the Preview2-1 sdk the -1 indicates that it works with the 1.1.0 runtime. If you look at the file system image in your article you can see the correct version number.

It’s worth knowing about the global.json. However what I would really like to know is, how can I configure the `dotnet` CLI to use the 1.1.0 runtime when I use the `new` command to create a project? I believe the Preview2-1 SDK creates a 1.1.0 runtime project, whereas the Preview3 and Preview5 SDKs create 1.0.1 runtime projects. Can I use global.json to instruct `dotnet` which runtime to base a project on when running the `new` command?

Hi Duncan, you are right, I’ve changed “1.0.0-preview3-1-004056” to “1.0.0-preview3-004056”.
Anyway, the important thing is how and where to look at for the installed tools versions (the c:\programfiles\dotnet folder). As an example, now on my PC I don’t have the preview3 anymore, but I have the “1.0.0-preview4-004233”.
For the ‘dotnet’ CLI question: AFAIK you can use the –fx-version optional parameter to set the dotnet core runtime version, but CLI will always use the latest tools version installed. Please let us know if you find something more on this.