dotnet core PackageReference vs DotNetCliToolReference

Question

I'm trying to run dotnet aspnet-codegenerator from my comand line. The first time I tried, I got the error No executable found matching command "dotnet-aspnet-codegenerator"

I realized I needed to install the aspnet-codegenerator as "dotnet CLI tool" (part of their extensibility model allows adding CLI commands if I include the correct <DotNetCliToolReference> element to the csproj file.)¹

This answer tells me which <DotNetCliToolReference> I need, i.e. <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="1.0.1" /> but it leaves me with a few questions:

1. Can I install that using the command line rather than hand-editing the csproj?
   • I notice I can install packages using the command dotnet add package, but that adds the element <PackageReference> and I need <DotNetCliToolReference> ;
   • i.e. running the command would produce this (wrong) element: <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="1.0.1" />
2. What's the difference between those two elements?
   • Can I add them to the same <ItemGroup>?
   • When I have a csproj whose first and only <ItemGroup> contains a <DotNetCliToolReference>, then any subsequent dotnet add package commands fail: error: Invalid restore input. Invalid restore input. DotnetCliToolReference-BundlerMinifier.Core Input files:.
   • My workaround is to:
     1. remove any existing DotNetCliToolReference elements
     2. run dotnet add package
     3. After finished, add back what I removed.

¹ (I'm in Visual Studio Code and using the latest; so we're using csproj, not project.json)

Answer 1

1. At the moment adding DotNetCliToolReference items is only possibly by hand-editing the csproj file. The feature was deprecated in .NET Core 3.0, because it caused strange incompatibilities that were difficult to debug. See: https://github.com/dotnet/sdk/issues/3115

2. The logical difference is that PackageReferences will become part of your application - you can use the dlls shipped with the package from your code and it will be deployed with your app. DotNetCliToolReference packages will be restored from feeds but not added to your app's "dependency graph". When the CLI runs commands it looks at the csproj file as well to resolve command names to the corresponding dll files through DotNetCliToolReference items.

3. It does not matter in which item groups those two item types are. MSBuild is very dynamic and you can re-arrange the file as you like. Both the CLI and NuGet use MSBuild API to evaluate the file and query the project's items.

4. The error you are seeing that dotnet add package fails when a DotNetCliToolReference is already present is a bug that has been fixed for the upcoming 2.0 release: https://github.com/NuGet/Home/issues/4771