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.
Prerequisites: download instructions
To install both the LTS and Current latest version of .NET Core and SDKs go to the download page: https://www.microsoft.com/net/download/core
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: https://www.visualstudio.com/vs/visual-studio-2017-rc/
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:
- .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.
- From a
- 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.
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.
Happy coding!
Duncan
Dec 16, 2016
Hey,
Thanks for the interesting article.
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?
All the Best,
Duncan
Nicolò Carandini
Dec 23, 2016
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.
Duncan
Dec 16, 2016
Oh one other thing…
I believe you don’t need to do 4 downloads as you are instructing. If you download the SDKs the runtime is included, so you don’t then have to download the runtime separately.
Nicolò Carandini
Dec 23, 2016
Good to know, thanks!
Demystifying .NET Core SDK versions – Marco Mansi's Blog
Jan 13, 2017
[…] 13-01-2017: this blogI found which also describes very well the […]
Upgrading to ASP.NET Core 1.1 with Visual Studio Code – JAMIE KEELING
Jan 15, 2017
[…] between SDK versions and how to maintain them across projects, read Nicolò Carandini’s great post on the […]
Dew Drop - February 1, 2017 (#2412) - Morning Dew
Feb 1, 2017
[…] Multiple Versions of .NET Core Runtimes and SDK Tools SxS Survive Guide (Nicolò Carandini) […]
Copyright © 2013 Nicolò Carandini - This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License