Global.json and .NET Core SDK

Previously in part 1, I introduced JSON-based configuration files inside ASP.NET Core Web Applications. In this post, I will go over the role of global.json config file in determining which .NET SDK version to use when executing .NET Core applications.

• Part 1 - Introduction
• Part 2 - global.json and .NET Core SDK

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-preview2-003121"
  }
}

Microsoft MVP Stephen Cleary explained it in his blog post regarding the RTM and Preview confusion. The RTM announcement is for the SDK runtime environment of .NET Core (i.e., the framework). However, the .NET CLI Tooling (i.e., dotnet.exe) which we used to execute the application from the Command Prompt is still in preview stages. Stephen Cleary also mentioned that the version number gets displayed when you type the dotnet --version inside a Command Prompt window.

$ dotnet --version
1.0.0-preview2-003121

I want to emphasize and repeat the difference between the SDK and the CLI Tooling.
.NET Core SDK = Software Development Kit which .NET Core applications depend upon
.NET Core CLI Tooling = Runs apps written with the .NET Core SDK

1.0.0-preview2-003121 is the Tooling version that was installed when we installed the .NET Core 1.0.0 - VS 2015 Tooling Preview 2. According to Scott Hanselman's blog post, it is installed at C:\Program Files\dotnet\sdk on your computer.

Newer versions of it can be downloaded from the official .NET CLI (command line interface) GitHub repository. At the time of this writing, the latest CLI tooling version available for download is 1.0.0-preview3-003223. Which one should we download then? You should download the .NET Core SDK since it includes the CLI tools in addition to the .NET Core runtime and framework.

After installing the latest .NET Core SDK version 1.0.0-preview3-003223, you will see another version folder under C:\Program Files\dotnet\sdk folder existing side-by-side with the older 1.0.0-preview2-003121.

However, when you run dotnet --version command, the tool will report a version number depending on where you are running from. As shown below, when I run it anywhere else, I get the latest installed version. When I run it from inside the AspNetCoreApp project folder, I get the version defined in the global.json configuration file.

C:\Users\Soe\Desktop>dotnet --version
1.0.0-preview3-003223

C:\Users\Soe\Desktop>cd AspNetCoreApp

C:\Users\Soe\Desktop\AspNetCoreApp>dotnet --version
1.0.0-preview2-003121

Now that the 1.0.0-preview3-003223 is installed, how do we upgrade our app to use it instead of an older version? Let's try changing the SDK version inside global.json to the new version.

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-preview3-003223"
  }
}

C:\Users\Soe\Desktop\AspNetCoreApp>dotnet --version
1.0.0-preview3-003223

If you accidentally entered the wrong .NET SDK version, you will see the following error message in Visual Studio.

If you peek inside the .NET SDK version folder, you will see it has some kind of .NET Runtime DLLs inside it.

If we try executing the corehost.exe inside the SDK version folder, it looks like it is the actual executable file that runs and hosts .NET Core applications when we execute dotnet run from the Command Prompt. See the highlighted text below where it gives instructions on how to use it.

c:\Program Files\dotnet\sdk\1.0.0-preview3-003223>corehost.exe --help

Microsoft .NET Core Shared Framework Host

  Version  : 1.0.1
  Build    : cee57bf6c981237d80aa1631cfe83cb9ba329f12

Usage: dotnet [common-options] [[options] path-to-application]

Common Options:
  --help                           Display .NET Core Shared Framework Host help.
  --version                        Display .NET Core Shared Framework Host version.

Options:
  --fx-version <version>           Version of the installed Shared Framework to use to run the application.
  --additionalprobingpath <path>   Path containing probing policy and assemblies to probe for.

Path to Application:
  The path to a .NET Core managed application, dll or exe file to execute.

If you are debugging the Shared Framework Host, set 'COREHOST_TRACE' to '1' in your environment.

To get started on developing applications for .NET Core, install .NET SDK from:
  http://go.microsoft.com/fwlink/?LinkID=798306&mp;clcid=0x409

We discussed the difference between .NET Core SDK and .NET Core CLI Tooling, and why there are two different versions. global.json configuration file affects which .NET SDK Runtime is used to host and run .NET Core apps. We also discovered that inside each .NET Core SDK version folder, there exists a corehost.exe executable that gets indirectly executed by the dotnet.exe.

The most significant discovery is that .NET Core SDK Runtimes coexist side-by-side inside the C:\Program Files\dotnet\sdk\ folder similar to the original .NET Frameworks.

At this point, we have only looked at the SDK version attribute in the global.json file. We haven't figured out what the projects attribute does. In my next post, we will look at what we can do with it.

• http://blog.stephencleary.com/2016/06/dotnet-netcore-versions.html
  by Stephen Cleary
• http://www.hanselman.com/blog/WheresDNVMSafelyRunningMultipleVersionsOfTheNETCoreSDKAndToolingWithGlobaljson.aspx
  by Scott Hanselman