Runtime: dotnet --version/--help should be more explicit that they only work when the SDK is installed

[livarcocc]

From @davkean at https://github.com/dotnet/cli/issues/5775

Provide a little clearer information that dotnet --version/--help are only applicable when the SDK is installed.

Running:

> dotnet --version

or

```

dotnet --help

Outputs the following:

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 of the installed Shared Framework to use to run the application.
--additionalprobingpath 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
```

This should be more clearer that this is only applicable when the _actual SDK_ is installed.

[omajid]

As a user, I find this very confusing!

If I install a program named python, I can use python --version. Same for java -version and gcc --version. Is there any other program that requires installing something else for --version (or equivalent) to work? Why does dotnet behave this way?

[gkhanna79]

What is incorrect above the information above? The output reflects the version details for the host. SDKVersion display should be a SDK command - and the above does not require SDK to be installed.

[davkean]

@gkhanna79 --help and --version require that the SDK is installed. It's extremely unclear from the output of those commands when the SDK _isn't_ installed that this is the case.

Why is --version and --help even shown as options when SDK isn't installed?

[davkean]

To make it clear, this is what it outputs when the SDK _is_ installed:

> dotnet --version
1.0.0

-and-

> dotnet --help
.NET Command Line Tools (1.0.0)
Usage: dotnet [host-options] [command] [arguments] [common-options]

Arguments:
  [command]             The command to execute
  [arguments]           Arguments to pass to the command
  [host-options]        Options specific to dotnet (host)
  [common-options]      Options common to all commands

Common options:
  -v|--verbose          Enable verbose output
  -h|--help             Show help

Host options (passed before the command):
  -d|--diagnostics      Enable diagnostic output
  --version             Display .NET CLI Version Number
  --info                Display .NET CLI Info

Commands:
  new           Initialize .NET projects.
  restore       Restore dependencies specified in the .NET project.
  build         Builds a .NET project.
  publish       Publishes a .NET project for deployment (including the runtime).
  run           Compiles and immediately executes a .NET project.
  test          Runs unit tests using the test runner specified in the project.
  pack          Creates a NuGet package.
  migrate       Migrates a project.json based project to a msbuild based project.
  clean         Clean build output(s).
  sln           Modify solution (SLN) files.

Project modification commands:
  add           Add items to the project
  remove        Remove items from the project
  list          List items in the project

Advanced Commands:
  nuget         Provides additional NuGet commands.
  msbuild       Runs Microsoft Build Engine (MSBuild).
  vstest        Runs Microsoft Test Execution Command Line Tool.

[davkean]

The jekyll and hyde behavior of these commands is confusing.

[mklement0]

@davkean:

Why is --version and --help even shown as options when SDK isn't installed?

Not only that, but the specific wording even suggests that host information will be supplied:

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

And, of course, that would be helpful too, but with the current hybrid approach (single entry point to both host CLI and SDK CLI - wouldn't know which incarnation to call Jekyll and which Hyde :), that's not possible if the SDK is also installed.

For those looking for a better understanding of the current behavior:

---

Curiously,

• if you run dotnet _without arguments_, you get the host's version (embedded in additional information),
• whereas dotnet --version gives you the _SDK_ version (only).

For instance, with a 1.0.1 host installed (the host version, which typically - but not necessarily - corresponds to the highest installed CoreCLR version):

$ dotnet

Microsoft .NET Core Shared Framework Host

  Version  : 1.0.1
  Build    : cee57bf6c981237d80aa1631cfe83cb9ba329f12
  # ...

By contrast, using --version outputs the installed SDK version, 1.0.0-preview2-003156 in this example:

 $ dotnet --version
 1.0.0-preview2-003156

Note (as of this writing, CoreCLR 1.x and 2.0 beta):

• If you _only_ have the runtime (CoreCLR) installed (and not also the SDK) installed, all you can use dotnet for is to _run binaries_ (*.dll or *.exe, i.e., previously compiled projects), and the command-line syntax for that is:
  dotnet [common-options] [[options] path-to-application]

• dotnet _by itself_ is the host CLI that provides access to the runtime; if you also have the SDK installed, dotnet then _also_ provides access to the SDK sub-commands, such as new, restore, ..., in which case the command-line syntax is:
  dotnet [host-options] [command] [arguments] [common-options]

• Only the _SDK_ truly understands --version and --help - despite what the output you (currently get) from just running dotnet suggests; in practice, this means:

  • If you run dotnet --version, and instead of a single version number you get multi-line output that starts with Microsoft .NET Core Shared Framework Host, the implication is that the SDK isn't installed.

  • Without the SDK, using anything other than the correct syntax for running a binary is apparently unrecognized by the dotnet host, and instead of (also) complaining about unrecognized arguments, it simply prints the default usage information you also get if you run dotnet without arguments.

  • This is especially confusing with --version and --help:

    • If, unbeknownst to you, the SDK isn't installed, yet you're expecting _SDK_ information with --version and --help, you're getting _host_ information instead, without any obvious indication that unrelated information is being provided.

[omajid]

if you run dotnet without arguments, you get the CoreCLR version (embedded in additional information),

AFAIK, for 1.x , it actually prints the version of the muxer (host) not CoreCLR. It generally matches the CoreCLR version, but the two can differ. I don't know if there's any command to actually display the CoreCLR/CoreFX version.

[mklement0]

I appreciate the clarification, @omajid - once I have the full picture, I will clean up my previous post and the SO answer accordingly.

• Is there really no way to determine the actual CoreCLR version?

• Does anybody know under what circumstances the host and the CoreCLR version can differ?

• Similarly, with multiple CoreCLRs / SDKs installed, is there a way to _select_ a specific CoreCLR / SDK to target? Unlike what the docs say, you apparently cannot combine --fx-version with an _SDK_ command (and the docs confusingly talk about the version of the _tooling_ (SDK) rather than the _framework_).

Also, the terminology is confusing: the dotnet executable is variously referred to as "driver" (in the docs, somewhat unfortunately), "host", and "muxer".

[omajid]

Is there really no way to determine the actual CoreCLR version?

I have been looking directory names under $PATH_TO_DOTNET/shared/Microsoft.NETCore.App/ to see what shared runtime versions this .NET Core installation supports.

Does anybody know under what circumstances the host and the CoreCLR version can differ?

There's many ways. The host corresponds to the https://github.com/dotnet/core-setup repo. The runtime (also called shared framework) includes CoreCLR (https://github.com/dotnet/coreclr) and CoreFX (https://github.com/dotnet/corefx). All 3 of them are separate repositories and can have different versions. SDK is yet another version.

Check out this build of .NET Core 1.1.1:

$ ls ~/dotnet-1.1.1/shared/Microsoft.NETCore.App/    # sharedframework (coreclr/corefx) versions
1.1.1
$ ~/dotnet-1.1.1/dotnet                              # host version

Microsoft .NET Core Shared Framework Host

  Version  : 1.1.0
  Build    : 362e48a95c86b40cd1f2ef3d08741f7fed897956
... 
$ ~/dotnet-1.1.1/dotnet --version                   # sdk version
1.0.0-preview2-1-003176

Similarly, with multiple CoreCLRs / SDKs installed, is there a way to select a specific CoreCLR / SDK to target? Unlike what the docs say, you apparently cannot combine --fx-version with an SDK command (and the docs confusingly talk about the version of the tooling (SDK) rather than the framework).

You can target a specific sdk using global.json. You can target a specific shared framework in your project.json or .csproj file.

[mklement0]

@omajid:

That's very helpful, thank you (original post updated).

So the SDK versions, Host (fxr) versions, and CoreCLR versions are reflected in folder names.

I presume that the CoreFX DLLs are hosted inside the folder for the CoreCLR that they depend on, correct?

Given that CoreFX versions therefore don't have their own folders reflecting their version numbers, how can you determine the CoreFX version associated with a given CoreCLR version?

Finally, is all that information already documented somewhere and I just missed it?
If not, it deserves documenting.

[mklement0]

@omajid: To close this tangent of mine:

• To answer my own question: in each CoreCLR folder, file Microsoft.NETCore.App.deps.json contains version information about related components such as CoreFX (in keys [starting with] microsoft.netcore.platforms), as far as I can tell.

• I've updated my SO answer based on your information.

• I've wrapped up the information in a (cross-platform) PowerShell Core script here (should run on Windows PowerShell too, once v6 is released) - see below.

---

Example uses of the script:

• Get global information (installed SxS versions, active SDK and host versions)

> ./Get-DotNetCoreVersion

ActiveSDK   : 2.0.0-preview1-005660
ActiveHost  : 2.0.0-beta-001863-00   
Runtimes    : {2.0.0-beta-001863-00, 2.0.0-beta-001836-00, 1.1.1, 1.1.0...}
CoreFX      : {2.0.0-beta-25129-02, 2.0.0-beta-25122-02, 1.1.0, 1.1.0...}
NetStandard : {2.0.0-beta-25129-01, 2.0.0-beta-25123-01, 1.6.1, 1.6.1...}
SDKs        : {2.0.0-preview1-005660, 1.0.0-preview2-1-003177, 1.0.0-preview2-003156}
Hosts       : {2.0.0-beta-001863-00, 2.0.0-beta-001836-00, 1.1.0, 1.0.1}

• Get project-specific information (what runtime version the project targets, and what (potentially project-specific) SDK version it uses)

> ./Get-DotNetCoreVersion /path/to/project

ProjectTargetFramework ProjectRuntime       EffectiveSDK          UsesActiveSDK
---------------------- --------------       ------------          -------------
netcoreapp2.0          2.0.0-beta-001836-00 1.0.0-preview2-003156         False

[steveharter]

Closing this.

This issue addresses --version: https://github.com/dotnet/core-setup/issues/3332
This issue addresses --info: https://github.com/dotnet/core-setup/issues/3502

Also --list-runtimes and --list-sdks were recently added to 2.1.0.