.NET Core: version numbers and global.json

I’m sure most people reading this know that Microsoft recently announced ASP.NET Core and .NET Core 2.0 Preview 1 at Microsoft Build 2017.

This article does not have a goal - to give an introduction to ASP.NET Core. Instead, we will consider installing .NET Core 2.0 Preview 1 on your computer so that it does not interfere with parallel work on other projects under ASP.NET Core 1.0 / 1.1. Those. we will install several versions of .NET Core on the same computer.

Installing .NET Core 2.0 Preview 1 SDK

Obviously, the first thing to do is install the .NET Core 2.0 Preview 1 SDK from here . This is very easy: no choice of installation options - just download and install. And there is only one version number!

One small note: .NET Core now also includes an ASP.NET Core. This means that you need to install fewer external packages when you deploy your application, which is good news!

It is also worth noting that if you want to create ASP.NET Core 2.0 applications in Visual Studio, you will need to install a preliminary version of Visual Studio 2017. You can install it in parallel with a stable version.

.NET Core Versions

Above, I wrote that the new .NET Core has only one version number 2.0 preview 1 , but this is not quite so. There are two different aspects of installing .NET Core: the SDK / CLI version number (command line interface) and the runtime version number (runtime or .NET Core Shared Framework Host).

If you have just installed 2.0 preview 1, then if you type in the dotnet --info console, you will see something like the following:

$ dotnet --info .NET Command Line Tools (2.0.0-preview1-005977) Product Information: Version: 2.0.0-preview1-005977 Commit SHA-1 hash: 414cab8a0b Runtime Environment: OS Name: Windows OS Version: 10.0.14393 OS Platform: Windows RID: win10-x64 Base Path: C:\Program Files\dotnet\sdk\2.0.0-preview1-005977\ Microsoft .NET Core Shared Framework Host Version : 2.0.0-preview1-002111-00 Build : 1ff021936263d492539399688f46fd3827169983 

There are a whole bunch of different information, among which there are two different version numbers:

• 2.0.0-preview1-005977 - SDK version
• 2.0.0-preview1-002111-00 - version of the runtime environment

But these version numbers are a bit misleading. I also have the .NET Core SDK version 1.0 and the .NET Core Runtime versions 1.1.1 and 1.0.4 installed on my computer, but there is no information about them.

Understanding the .NET Core runtime versions

One of the advantages of .NET Core is the ability to install multiple versions of the runtime in parallel in parallel, without affecting each other. This is different from how the .NET Framework is installed. You cannot install parallel. NET Framework 4.5, 4.6 and 4.7 - version 4.7 will replace previous versions.

You can see which versions of the .NET Core runtime are already installed if you go to the C:\Program Files\dotnet\shared\Microsoft.NETCore.App folder (on Macs, look in the /usr/local/share/dotnet/shared/Microsoft.NETCore.App ). As you can see, three versions are installed on my computer:

The next question is how to find out which version of the runtime environment will be used when you launch your application?

Everything is very simple: you need to specify the desired version in the .csproj file!

For example, in a .NET Core 1.1 project, you can set the <TargetFramework> parameter (or <TargetFrameworks> if you build the project for several different versions) to the value netcoreapp1.1 :

 <Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp1.1</TargetFramework> </PropertyGroup> </Project> 

In this case, the application will use .NET Core version 1.1.1 (see the list of installed versions above). If you set <TargetFramework> to netcoreapp1.0 , version 1.0.4 will be used.

The .csproj: file .csproj: for an ASP.NET application using runtime version 2.0 preview 1 will look something like this:

 <Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp2.0</TargetFramework> <UserSecretsId>aspnet-v2test-32250BD7-D335-414A-A537-53B40874D211</UserSecretsId> </PropertyGroup> <ItemGroup> <Folder Include="wwwroot\" /> </ItemGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.0-preview1-final" /> </ItemGroup> </Project> 

In the .csproj file, the .csproj specified for <TargetFramework> and the maximum corresponding version will be used (on my computer it is 2.0.0-preview1-002111-00 ).

Understanding SDK Versions

I hope you now understand everything about the versions of the .NET Core runtime. But we still have an open question about the SDK / CLI version.

If you go to the C:\Program Files\dotnet\sdk folder (you need to look at the /usr/local/share/dotnet/sdk folder on your poppies), you will see which versions of the SDK are installed on your computer. As you can see, I have two versions installed: 1.0.0 and 2.0.0-preview1-005977 .

Roughly speaking, an SDK is a thing that provides commands related to dotnet new : dotnet new , dotnet build , dotnet publish , etc.

In general, any version of the SDK that is larger than the version used to create the project can be used to build it ( dotnet build and dotnet publish ). Thus, you can simply use SDK version 2.0 to work with projects created in SDK version 1.0.

This means that in most cases you can use the latest version of the SDK for all projects. Another version of the SDK may be needed, for example, if you want to build a project that uses the project.json file (in this case, you will need the RC2 SDK).

The current version of the SDK also affects new projects created by the dotnet new command. If you are using SDK version 2.0 Preview 1, you will receive an application based on netcoreapp2.0 , if you are using SDK version 1.0, you will receive an application based on netcoreapp1.1 !

The next question is how to tell the application which version of the SDK to use.

Selecting the SDK version in the global.json file

The global.json file has a very simple format that simply specifies which version of the SDK to use:

 { "sdk": { "version": "1.0.0" } } 

Previously, the global.json file was global.json used to specify the folders with the source code of the solution, but this functionality will be removed in future versions.

When you start dotnet new or dotnet build , dotnet looks for global.json , first in the current folder, then in all parent folders. If global.json found (and the SDK version specified there is available!), Then this version will be used for all SDK commands that are run inside this folder. If no global.json file global.json be found, the latest available version of the SDK will be used, in my case, 2.0.0-preview1-005977 .

Personally, I put the above global.json in my Projects folder and therefore all existing projects that are in it will continue to use the SDK 1.0.0 (as well as all new projects I create there). Then I created the netcore20 subfolder and added the following global.json . In it, I place all the projects in which I want to play with the preliminary version of ASP.NET Core 2.0, without risking getting problems because of this!

 { "sdk": { "version": "2.0.0-preview1-005977" } } 

Conclusion

Versioning was one of the .NET Core problems until recently. Aligning all versions in the future will certainly simplify the situation and, we hope, this will cause less confusion. But you should still try to understand the difference between runtime versions and SDK versions. I hope this post has helped clarify some of these issues!