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:

  1. 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).
  2. 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.

Prerequisites: download instructions

To install both the LTS and Current latest version of .NET Core and SDKs go to the download page:

You need to install all the LTS and Current versions of the Runtime and SDK installer for a total of four install operations.

Then install the Visual Studio 2017 RC from here:

On the new VS 2017 installer, select the Web Development to install .NET Core and ASP.NET Core:

and complete the installation of Visual Studio 2017 RC.

.NET Core Runtime and SDKs installation notes

When done, you’ll find a “dotnet” folder inside the “Program Files” folder:

Please note that:

  1. .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.
  2. Each version of the runtime is contained in a version named folder inside the “Microsoft.NETCore.App” folder.
  3. At the time of writing, the Preview2 latest version is “1.0.0-preview2-1-003177”.
  4. 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.
  • From a Rich Lander [MSFT] comment on his post Announcing .NET Core 1.1:
    • preview2 is for .NET Core 1.0 solutions based on project.json.
    • preview2.1 is for .NET Core 1.1 solutions based on project.json.
    • preview3 is for .NET Core 1.0 solutions based on csproj.
  • 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.


  • 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.


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.

Happy coding!

ADAL and the .NET Standard Transition