Sdk: dotnet list reference help text and output

[mairaw]

Steps to reproduce

1. dotnet list reference --help
2. dotnet list reference solution-name.sln
3. dotnet list reference on a folder that contains a project with no P2P references

Expected behavior

1. It seems that dotnet list reference doesn't accept solution files as a parameter but its description was changed in 2.2 SDK to say it supports solution files. I'd expect that dotnet list reference --help wouldn't say that is either a project or solution if solution files aren't supported.
2. I'm assuming this shouldn't work by design. So, fixing the help text would avoid confusions. Or if it's supposed to be supported, then it should list the P2P references from the solution.
3. For a project that has no P2P references, I'd expect a cleaner output, such as:
   There are no project-to-project references in project C:\Users\mairaw\Documents\GitHub\samples\core\getting-started\unit-testing-using-nunit\PrimeService\.

Actual behavior

1. dotnet list reference --help tells me I can provide a project or solution in .NET Core 2.2 SDK
2. dotnet list reference solution-name.sln doesn't work
3. For a project that has no P2P references, the output is a bit garbled. For example:
   There are no Project to Project references in project C:\Users\mairaw\Documents\GitHub\samples\core\getting-started\unit-testing-using-nunit\PrimeService\. ;; Project to Project is the type of the item being requested (project, package, p2p) and C:\Users\mairaw\Documents\GitHub\samples\core\getting-started\unit-testing-using-nunit\PrimeService\ is the object operated on (a project file or a solution file).

Environment data

dotnet --info output

.NET Core SDK (reflecting any global.json):
 Version:   2.2.100
 Commit:    51868761f2

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.17134
 OS Platform: Windows
 RID:         win10-x64
 Base Path:   C:\Program Files\dotnet\sdk\2.2.100\

Host (useful for support):
  Version: 2.2.0
  Commit:  1249f08fed

.NET Core SDKs installed:
  2.0.0 [C:\Program Files\dotnet\sdk]
  2.1.300-preview1-008174 [C:\Program Files\dotnet\sdk]
  2.1.300 [C:\Program Files\dotnet\sdk]
  2.2.100 [C:\Program Files\dotnet\sdk]

.NET Core runtimes installed:
  Microsoft.AspNetCore.All 2.1.0-preview1-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
  Microsoft.AspNetCore.All 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
  Microsoft.AspNetCore.All 2.2.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
  Microsoft.AspNetCore.App 2.1.0-preview1-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 2.2.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 2.0.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 2.1.0-preview1-26216-03 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 2.2.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

To install additional .NET Core runtimes or SDKs:
  https://aka.ms/dotnet-download

[Jalalx]

@mairaw @peterhuene Please let me know if this fixes the issue

[peterhuene]

@Jalalx thank you for the PR!

[peterhuene]

@mairaw we have a problem with the architecture of the command parser for dotnet list.

The problem is that the list command gets to define the argument that the subcommands will operate on (which is an unconventional approach to a CLI, in my opinion). Thus, the "project or solution" argument is defined for dotnet list because dotnet list package does operate on both project and solution files.

So dotnet list reference cannot change the argument name or description because it is defined on dotnet list. At best we could change dotnet list to use PROJECT and drop mentions of supporting solution files. We could then add an additional help output to dotnet list package that mentions it does support solution files?

It's a mess because the decision for what a command's argument should be shouldn't be made at the top-level command like this.

What are your thoughts?

[mairaw]

Yeah, I think this could work @peterhuene.

[peterhuene]

With @Jalalx's changes:

$ dotnet list --help
Usage: dotnet list [options] <PROJECT> [command]

Arguments:
  <PROJECT>   The project file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help   Show command line help.

Commands:
  package     List all package references of the project or solution.
  reference   List all project-to-project references of the project.

$ dotnet list reference --help
Usage: dotnet list <PROJECT> reference [options]

Arguments:
  <PROJECT>   The project file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help   Show command line help.

With a commit I have to provide additional information after the help text:

$ dotnet list package --help
Usage: dotnet list <PROJECT> package [options]

Arguments:
  <PROJECT>   The project file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help                                Show command line help.
  --outdated                                Lists packages that have newer versions.
  --framework <FRAMEWORK | FRAMEWORK\RID>   Chooses a framework to show its packages. Use the option multiple times for multiple frameworks.
  --include-transitive                      Lists transitive and top-level packages.
  --include-prerelease                      Consider packages with prerelease versions when searching for newer packages. Requires the '--outdated' option.
  --highest-patch                           Consider only the packages with a matching major and minor version numbers when searching for newer packages. Requires the '--outdated' option.
  --highest-minor                           Consider only the packages with a matching major version number when searching for newer packages. Requires the '--outdated' option.
  --config <CONFIG_FILE>                    The path to the NuGet config file to use. Requires the '--outdated' option.
  --source <SOURCE>                         The NuGet sources to use when searching for newer packages. Requires the '--outdated' option.

If a solution file is found or provided as an argument, then this command will list the packages referenced by all projects in the solution.

@mariaw suggestions on the If a solution file is found... text?

[peterhuene]

Ping @mairaw re: new help output, just in case it didn't notify you since I added the mention as an edit to the comment and I'm not sure if GitHub sends notifications for mentions in edits.

[mairaw]

And it was the wrong user anyway 😄

Ok, so when you mentioned that it would change the dotnet list package to mention the solution support, I thought you would be able to say PROJECT/SOLUTION on the argument. I think that note can easily be missed but if it's hard to change just for the list package option, then I think it's better than what we have right now.

[peterhuene]

Oh whoops, good eye.

Yeah, it's not possible to keep dotnet list the way it is without having both subcommands inherit that argument and its description.

So either we keep PROJECT | SOLUTION for dotnet list, dotnet list package, and dotnet list reference with a blurb on dotnet list reference noting solution files are not supported, or we use PROJECT for all three commands and have a blurb on dotnet list package that says solution files are also supported.

Do you have a preference for either?

[peterhuene]

Oh and you're correct, we can't modify the argument description that's being inherited. Basically the command line parser library we're currently using which is controlling the help text output prints out top level command arguments (dotnet list in this case) and then prints out any subcommand arguments.

I guess we could make some architectural changes to the command line parser to maybe fix this if we feel it's that necessary.

[peterhuene]

Actually, I think I spotted a way that would work without having to touch the command line parser (there's a protected property that we may be able to exploit). I'll get back to you :smile:

[mairaw]

I'm used to that. Poor Maria probably doesn't understand why she gets pinged from time to time. 😉

Given that dotnet list reference is shorter, probably listing both and adding the note there makes it more visible in that case and then the argument for package is correct?

[peterhuene]

With this new idea applied:

$ dotnet list --help
Usage: dotnet list [options] <PROJECT | SOLUTION> [command]

Arguments:
  <PROJECT | SOLUTION>   The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help   Show command line help.

Commands:
  package     List all package references of the project or solution.
  reference   List all project-to-project references of the project.

$ dotnet list package --help
Usage: dotnet list <PROJECT | SOLUTION> package [options]

Arguments:
  <PROJECT | SOLUTION>   The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help                                Show command line help.
  --outdated                                Lists packages that have newer versions.
  --framework <FRAMEWORK | FRAMEWORK\RID>   Chooses a framework to show its packages. Use the option multiple times for multiple frameworks.
  --include-transitive                      Lists transitive and top-level packages.
  --include-prerelease                      Consider packages with prerelease versions when searching for newer packages. Requires the '--outdated' option.
  --highest-patch                           Consider only the packages with a matching major and minor version numbers when searching for newer packages. Requires the '--outdated' option.
  --highest-minor                           Consider only the packages with a matching major version number when searching for newer packages. Requires the '--outdated' option.
  --config <CONFIG_FILE>                    The path to the NuGet config file to use. Requires the '--outdated' option.
  --source <SOURCE>                         The NuGet sources to use when searching for newer packages. Requires the '--outdated' option.

$ dotnet list reference --help
Usage: dotnet list <PROJECT> reference [options]

Arguments:
  <PROJECT>   The project file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -h, --help   Show command line help.

@mairaw how does that look?

It's a slight hack so it would need to pass review.

[peterhuene]

Ping @mairaw (double checked the user name this time 😄) regarding the new output of dotnet list based upon both @Jalalx's changes and mine.

[KathleenDollard]

Looks good.