Global vs. project tools (why two package formats?)

[daveaglick]

I've seen some mentions of the differences between global tools (or really, "CLI tools" since global/local is a switch) and project tools (those that use DotNetCliToolReference) but I can't find much information on why we have to have two different kinds of tool packages.

There's this comment:

I understand that you would want to produce one single package and use it both ways, but that's not possible, as it would have serious performance implications on NuGet side. It is explicitly not allowed.

But it doesn't expand on the "serious performance implications". I'd like to know more about the decision to bifurcate the NuGet tool distribution ecosystem.

Without additional context (which I'm hoping someone can provide here), this seems unnecessarily complex. I can think of three main ways in which someone might want to install a tool:

• Local to the project and installed during build/restore (DotNetCliToolReference, "repo tools"?).
• Local to the project or other folder and explicitly installed (dotnet tool install ...).
• Global and explicitly installed (dotnet tool install -g ...).

It make sense there needs to be both a MSBuild task and CLI support for tools delivered as packages to cover each of these scenarios. What doesn't make sense to me is why the packaging and production side of things needs to be different depending on the intended scenario (or why the tool author should even care about the consumer scenario at all in the first place). If I write a tool, why should it matter to me whether it's going to get installed as part of a restore or as a CLI global tool?

I have a few practical concerns with the current design:

• It's overly burdensome for the tool author to have to decide which of the end-user scenarios they want to support and release packages that cover them all. A great example is the AWS Extensions. They're publishing it as a project-based tool, but there's absolutely no reason why I shouldn't be able to install this as a global tool if I do a lot of AWS work, other than that the tool ecosystem is split and they either didn't know/didn't care to create two different packages.
• It's very confusing, both for producers of tool packages and for consumers. There's almost no documentation on the two different types of tool packages, and certainly nothing that makes it clear why we're stuck with this.
• It will result in packages that contain the same tool but are packaged just a little bit differently. That seems wasteful and unnecessary.
• It doesn't seem clean. The idea of "global or local" tool installation in NPM is a breeze. You install it on the command line, it ends up in the appropriate package file, and gets installed when required. The producer doesn't care and it's a single -g for the consumer to change behavior. The current .NET implementation of tools look very silly by comparison.

[livarcocc]

@peterhuene @wli3

[KathleenDollard]

@daveaglick

The project based DotNetCliToolReference has issues that aren't solvable. A big one is that you can have conflicting dependencies between a tool and a package in your project. It also generally isn't clear why you have to build to restore your tools.

We looked at these issues and npm in deciding on a new tool strategy. Our goal is the simplicity of the npm install experience.

We decided to begin with the global tool scenario. Global tools (and CLI Repo tools when they appear) are based on "self contained packages" that are NuGet packages that carry all of their dependencies to guarantee an independent experience. This is inherently different from the project based DotNetCliToolReference, and thus we can't use the same packages.

Our plan is that repo tools will use a manifest, allowing It to be checked in to the project. This is closer to the npm manifest.

We're still designing repo tools so the is tentative. We are currently planning to have the packages installed (for repo tools) in the package cache and the manifest state the important thing for the project - the version that is required. This seems the best of the NuGet and npm experiences. We are still working on the plan for the manifest and whether another standalone file is needed :-( or we can combine this with other data about your project tooling - like global.json.

We are not currently planning to support your middle option without manifest.

Local to the project or other folder and explicitly installed (dotnet tool install ...).

Can you describe a scenario where you would need this instead of global or repo-installed tools?

When all of this is in place, meaning we have fully covered the current project-based DotNetCLIToolReference scenario, we will encourage use of the new approach, supporting the old for compatibility. If we can't meet that bar (and we expect to) we would either plug the gap or find an answer with the new style (self contained package, etc) of tool.

Yes, our current implementation is awkward because it is in transition.
Yes, there is temporary pain that there are two styles needed
Yes, we've done a bad job communicating about this (I'd like to do this when we land the project based DotNetCLIToolReference design)

[daveaglick]

The project based DotNetCliToolReference has issues that aren't solvable.

Our plan is that repo tools will use a manifest, allowing it to be checked in to the project.

When all of this is in place, meaning we have fully covered the current project-based DotNetCLIToolReference scenario, we will encourage use of the new approach, supporting the old for compatibility.

This tells a much better story than what's evident in the available docs and issues. Thank you very much for summarizing the entire plan, I feel much better about the direction now. The transition will be a bit awkward, but it looks like we'll end up in a good place.

Can you describe a scenario where you would need this instead of global or repo-installed tools?

No - I had written this mainly to support the repo-installed scenario, which it sounds like will be covered using a manifest which is fine. And I'm happy to eliminate that first scenario (project-based build/restore) when a CLI command is available that "restores" your repo-installed tools.

[livarcocc]

Going to close this issue given @KathleenDollard's answer above.