Limit DotNetCliToolReference Tools to .NET Core 2.2 and Below

Limit DotNetCliToolReference Tools to .NET Core 2.2 and Below

.NET Core 3 takes the next step in the .NET Core tool strategy with local tools. As part of this process, starting in Preview 4 DotNetCliToolReference tools will be restricted to targeting .NET Core 2.2 and below. DotNetCliToolReference tools can be used in projects targeting .NET Core 3.0, but the tools themselves should target .NET Core 2.2 or below.

Details

The suggested approach going forward is to to use .NET Core Local Tools when you want a tool that is specific to a project or repository. At the same time we are removing the need to access local tools by the verbose dotnet tool run <toolname> that was present in earlier previews. You can now access local tools via dotnet <toolname>.

DotNetCliToolReference tools have a flaw in how their dependencies are restored which can create difficult to diagnose bugs when running these tools. This issue would occur much more frequently if targeting .NET Core 3.0 was allowed. Restricting tools to target only .NET Core 2.2 and below means existing scenarios to continue to work (as well as they previously did), regardless of the framework version targeted by the project or the current .NET Core SDK.

The new .NET Core tool strategy avoids this flaw in restore strategy and offers other benefits, like the ability to author one type of tool and install it in different ways depending on project and user needs.

We look forward to your feedback on .NET Core Local Tools, and on challenges you face moving away from DotNetCliToolReference tools.

dotnet/sdk #3057

[bitbonk]

That makes sense, however I think DotNetCliToolReference enabled the following two scenarios, which were nice (as in “nice to have”):

1. Users sometimes did not have to use the CLI at all, they could stay in VS all the time: Tools where automatically restored when the user restored the regular nuget packages. And the installed tools would just do do their work under the hood (e.g. when the user builds the project). The user clones the repo in VS and everything just works in VS right away.

2. When building a framework, it is nice to not have to write into the getting started documentation that you have to restore the nuget packges and some global tools. You would just create the project (with our template that already contains all required DotNetCliToolReference entries) and you are ready to go and can use all our tools right away.

[ascott18]

Another use case we have for DotNetCliToolReference is a set of libraries that are used in conjunction with a code gen tool. Generally (although not strictly necessary), these should all be kept on identical version numbers. We used a prop in a Directory.Build.props file to control this version from a single location.

With the deprecation of DotnetCliToolReference, this won’t be possible anymore - we’ll have to make sure the version number is always updated in both locations when updating, which is going to be very error prone.

The separate command for restoring tools from the manifest is also rather undesirable from a usability point of view. Does attempting to execute the tool also perform the restore, similar to how dotnet build automatically does a dotnet restore? If not, this new approach is a non-starter for us and we’ll be forced to stay on netcoreapp2.2 for our CLI tool forever.