Limit DotNetCliToolReference Tools to .NET Core 2.2 and Below

[KathleenDollard]

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

[natemcmaster]

I had to read twice to make sure I understood, you're saying this is still okay, right? This is just a restriction for the authors of a DotNetCliTool.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>
   <ItemGroup>
     <DotNetCliToolReference Include="dotnet-banana" Version="x.x.x" />
   </ItemGroup>
</Project>

[wli3]

yes. just dotnet-banana need to be targeting netcoreapp2.2 or lower

[KathleenDollard]

Nate, if you have a wording suggestion to make this more clear, let me know. Do you think including your example is worthwhile?

[KathleenDollard]

Oh, and "OK" is relative. It will still have the problems with transitive dependencies today.

[wli3]

forget to close this issue. It is done.
#3057

[bitbonk]

A drawback of making DotNetCliToolReference obsolete seems to be that there is now no way (out of the box) anymore to automatically restore the local tools for a project when the other nuget packages are being restored. Is there a replacement for this?

[KathleenDollard]

Local tools allow tools to be defined in a tool-manifest file, and you can then use dotnet tool restore to restore them.

You are correct that this is a separate gesture. Restoring with the rest of the project was problematic, partially because the runtime for the tool and the project was often not the same. We designed the tool strategy to avoid these problems and others. As a result, there are two gestures.

[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.

[bitbonk]

@KathleenDollard Is there a plan to support the two scenarios I described above?

Will (or does it already have one) Visual Studio have a UI to install and restore global tools in a solution? That in my view this would more or less solve scenario 1. (except for other .NET IDEs where this would need to be reimplemented). It would also solve scenario 2. if our template has already created or updated a manifest file.

[JeremyMorton]

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.

This was going to be our approach, but our CLI tool needs to load an assembly and the types that it depends on. Since .NET Core 2.X doesn't support multiple AppDomains or Refection Only assembly loading, this means that it could only load an assembly whose assembly dependencies don't target anything but .Net Core 2.X (since the tool already had those runtime assemblies loaded). This has become untenable, so I have to cobble together some sort of local tool solution now in order to work against .NET Core 3.X projects that have dependencies on .NET Core 3.X or .NET Standard 2.1 assemblies.

[dadhi]

@KathleenDollard As I see no answers above, I am adding another hardly (not-at-all) supported use case.

I am publishing the library to NuGet which installed requires the dotnet CLI tool for code generation.

So how can I add this requirement to nuspec?

Should I just add Target with Exec of dotnet tool install my-tool?
What about the local tool manifest then?

[mikel21]

I had to read twice to make sure I understood, you're saying this is still okay, right? This is just a restriction for the authors of a DotNetCliTool.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>
   <ItemGroup>
     <DotNetCliToolReference Include="dotnet-banana" Version="x.x.x" />
   </ItemGroup>
</Project>

but .net core 2.2 sdk for example should be installed ? Although here https://github.com/madskristensen/BundlerMinifier/tree/master/src/BundlerMinifier.Core
DotnetCliTool is not used, but is connected with <DotNetCliToolReference. How it works ?