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.
Posts
Runtime SDK Version vs .NET CLI Tooling Version
{
"projects": [ "src", "test" ],
"sdk": {
"version": "1.0.0-preview2-003121"
}
}
In the
global.json
file above, you see notice something odd about the SDK version. If we are using the
ASP.NET Core 1.0 runtime RTM, why does the version number has
"preview" in it?
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
Installing NEWER .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.
dotnet SDK and Tooling installation path
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.
Choose the .NET Core SDK instead of .NET Core download
Multiple .NET CLI Tooling Versions
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
.
Multiple .NET Tooling Versions
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
Using the Newer Tooling Version
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"
}
}
Now, run the
dotnet --version
again inside the project folder, and you will see it reports the newer version.
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.
Invalid .NET SDK Version
Peek Inside the SDK Version
If you peek inside the .NET SDK version folder, you will see it has some kind of .NET Runtime DLLs inside it.
What is inside .NET SDK Version Folder?
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∓clcid=0x409
Summary
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.
References