Differences between global tools invocations via generated apphost or dotnet CLI

[DamianEdwards]

We maintain and ship a set of .NET CLI diagnostics tools documented at https://learn.microsoft.com/dotnet/core/diagnostics/tools-overview

Note that this documentation:

• Refers to them all as "global tools" and only documents how to install them that way, i.e. no mention of using them as local tools
• Documents the invocation command syntax as dotnet-toolname, i.e. directly invoking the tool apphost that's put on the path at tool install time

Global tools can be invoked either:

• via the .NET CLI, e.g. dotnet tool-name; or
• directly via the tool apphost shim that's on the path, e.g. dotnet-tool-name.

The different invocation patterns have implications on things like usage telemetry as the first pattern (via the .NET CLI) goes through the CLI's command and argument parsing pipeline, whereas the second pattern (via the apphost) does not. If the .NET CLI is not involved in the invocation of the tool, then no .NET CLI telemetry can be emitted.

Note: invocations of local tools always go through the .NET CLI, via the dotnet tool run command

We should consider how we might update the global tool invocation mechanism such that even if the tool is invoked directly via the executable on the path, the .NET CLI is involved such that things like usage telemetry can be facilitated (with all the usual considerations for opt-out, data privacy via hashing, etc.).

[baronfel]

Note: invocations of local tools always go through the .NET CLI, via the dotnet tool run command

This is not strictly the case - local tools can, and often are!, invoked via dotnet <toolname>, the same way that global tools can be (though our docs point folks to dotnet-<toolname>.

Case in point, most FAKE, FsAutoComplete, paket, and cake users use the space-delimited forms.

[baronfel]

If we want to get usage telemetry in a consistent way, then that telemetry needs to happen when the tool apphosts themselves are invoked. While we could put tool telemetry in the CLI for invocations that go through dotnet, many (global) tools are invoked directly (i.e. dotnet-dump) and would sidestep this mechanism.

Therefore, we could consider a somewhat significant shift in how tools are installed:

Global tool installation should install shell-specific shims (batch files, shell scripts) that invoke a hidden dotnet CLI command that sends tool usage telemetry and then subsequently invoke the actual tool.

As @DamianEdwards mentions above, privacy/telemetry controls would need to apply (the generated shell scripts should adhere to the telemetry opt-out CLI scripts).

[DamianEdwards]

This is not strictly the case - local tools can, and often are!, invoked via dotnet , the same way that global tools can be (though our docs point folks to dotnet-.

Ah my bad. I read the docs to figure it out and didn't see any example or detail of using local tools other than via dotnet tool run. OK re-read and now see it: https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#invoke-a-local-tool

So either way they're run via the dotnet CLI, yes?