[release/10.0.1xx] Fix dnx --help and tool commands to use valid .NET tool examples

.github/copilot-instructions.md

@@ -16,6 +16,11 @@ Testing:
  - Examples:
  - `dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~ItShowsTheAppropriateMessageToTheUser"`
  - `dotnet exec artifacts/bin/redist/Debug/dotnet.Tests.dll -method "*ItShowsTheAppropriateMessageToTheUser*"`
+- To test CLI command changes:
+ - Build the redist SDK: `./build.sh` from repo root
+ - Create a dogfood environment: `source eng/dogfood.sh` 
+ - Test commands in the dogfood shell (e.g., `dnx --help`, `dotnet tool install --help`)
+ - The dogfood script sets up PATH and environment to use the newly built SDK
 
 Output Considerations:
 - When considering how output should look, solicit advice from baronfel.

src/Cli/dotnet/CliStrings.resx

@@ -817,7 +817,7 @@ The default is 'false.' However, when targeting .NET 7 or lower, the default is
  <comment>{Locked="dotnet workload update"}</comment>
  </data>
  <data name="PackageIdentityArgumentDescription" xml:space="preserve">
- <value>Package reference in the form of a package identifier like 'Newtonsoft.Json' or package identifier and version separated by '@' like 'Newtonsoft.Json@13.0.3'.</value>
+ <value>Package reference in the form of a package identifier like '{0}' or package identifier and version separated by '@' like '{0}@{1}'.</value>
  </data>
  <data name="PackageIdentityArgumentIdOrVersionIsNull" xml:space="preserve">
  <value>Package reference id and version must not be null.</value>

src/Cli/dotnet/Commands/Tool/Install/ToolInstallCommandParser.cs

@@ -10,7 +10,7 @@ namespace Microsoft.DotNet.Cli.Commands.Tool.Install;
 
 internal static class ToolInstallCommandParser
 {
- public static readonly Argument<PackageIdentityWithRange> PackageIdentityArgument = CommonArguments.RequiredPackageIdentityArgument();
+ public static readonly Argument<PackageIdentityWithRange> PackageIdentityArgument = CommonArguments.RequiredPackageIdentityArgument("dotnetsay", "2.1.7");
 
  public static readonly Option<string> VersionOption = new("--version")
  {

src/Cli/dotnet/Commands/Tool/Update/ToolUpdateCommandParser.cs

@@ -9,7 +9,7 @@ namespace Microsoft.DotNet.Cli.Commands.Tool.Update;
 
 internal static class ToolUpdateCommandParser
 {
- public static readonly Argument<PackageIdentityWithRange?> PackageIdentityArgument = CommonArguments.OptionalPackageIdentityArgument();
+ public static readonly Argument<PackageIdentityWithRange?> PackageIdentityArgument = CommonArguments.OptionalPackageIdentityArgument("dotnetsay", "2.1.7");
 
  public static readonly Option<bool> UpdateAllOption = ToolAppliedOption.UpdateAllOption;
 

src/Cli/dotnet/CommonArguments.cs

@@ -12,17 +12,23 @@ namespace Microsoft.DotNet.Cli
  internal class CommonArguments
  {
  public static DynamicArgument<PackageIdentityWithRange?> OptionalPackageIdentityArgument() =>
+ OptionalPackageIdentityArgument("Newtonsoft.Json", "13.0.3");
+
+ public static DynamicArgument<PackageIdentityWithRange?> OptionalPackageIdentityArgument(string examplePackage, string exampleVersion) =>
  new("packageId")
  {
- Description = CliStrings.PackageIdentityArgumentDescription,
+ Description = string.Format(CliStrings.PackageIdentityArgumentDescription, examplePackage, exampleVersion),
  CustomParser = (ArgumentResult argumentResult) => ParsePackageIdentityWithVersionSeparator(argumentResult.Tokens[0]?.Value),
  Arity = ArgumentArity.ZeroOrOne,
  };
 
  public static DynamicArgument<PackageIdentityWithRange> RequiredPackageIdentityArgument() =>
+ RequiredPackageIdentityArgument("Newtonsoft.Json", "13.0.3");
+
+ public static DynamicArgument<PackageIdentityWithRange> RequiredPackageIdentityArgument(string examplePackage, string exampleVersion) =>
  new("packageId")
  {
- Description = CliStrings.PackageIdentityArgumentDescription,
+ Description = string.Format(CliStrings.PackageIdentityArgumentDescription, examplePackage, exampleVersion),
  CustomParser = (ArgumentResult argumentResult) => ParsePackageIdentityWithVersionSeparator(argumentResult.Tokens[0]?.Value)!.Value,
  Arity = ArgumentArity.ExactlyOne,
  };

test/dotnet.Tests/CompletionTests/snapshots/zsh/DotnetCliSnapshotTests.VerifyCompletions.verified.zsh

@@ -1103,7 +1103,7 @@ _testhost() {
  '--allow-roll-forward[Allow a .NET tool to roll forward to newer versions of the .NET runtime if the runtime it targets isn'\''t installed.]' \
  '--help[Show command line help.]' \
  '-h[Show command line help.]' \
- ':packageId -- Package reference in the form of a package identifier like '\''Newtonsoft.Json'\'' or package identifier and version separated by '\''@'\'' like '\''Newtonsoft.Json@13.0.3'\''.:->dotnet_dynamic_complete' \
+ ':packageId -- Package reference in the form of a package identifier like '\''dotnetsay'\'' or package identifier and version separated by '\''@'\'' like '\''dotnetsay@2.1.7'\''.:->dotnet_dynamic_complete' \
  && ret=0
  case $state in
  (dotnet_dynamic_complete)
@@ -1151,7 +1151,7 @@ _testhost() {
  '--all[Update all tools.]' \
  '--help[Show command line help.]' \
  '-h[Show command line help.]' \
- '::packageId -- Package reference in the form of a package identifier like '\''Newtonsoft.Json'\'' or package identifier and version separated by '\''@'\'' like '\''Newtonsoft.Json@13.0.3'\''.:->dotnet_dynamic_complete' \
+ '::packageId -- Package reference in the form of a package identifier like '\''dotnetsay'\'' or package identifier and version separated by '\''@'\'' like '\''dotnetsay@2.1.7'\''.:->dotnet_dynamic_complete' \
  && ret=0
  case $state in
  (dotnet_dynamic_complete)
@@ -1229,7 +1229,7 @@ _testhost() {
  '-v=[Set the MSBuild verbosity level. Allowed values are q\[uiet\], m\[inimal\], n\[ormal\], d\[etailed\], and diag\[nostic\].]:LEVEL:((d\:"d" detailed\:"detailed" diag\:"diag" diagnostic\:"diagnostic" m\:"m" minimal\:"minimal" n\:"n" normal\:"normal" q\:"q" quiet\:"quiet" ))' \
  '--help[Show command line help.]' \
  '-h[Show command line help.]' \
- ':packageId -- Package reference in the form of a package identifier like '\''Newtonsoft.Json'\'' or package identifier and version separated by '\''@'\'' like '\''Newtonsoft.Json@13.0.3'\''.:->dotnet_dynamic_complete' \
+ ':packageId -- Package reference in the form of a package identifier like '\''dotnetsay'\'' or package identifier and version separated by '\''@'\'' like '\''dotnetsay@2.1.7'\''.:->dotnet_dynamic_complete' \
  '*::commandArguments -- Arguments forwarded to the tool: ' \
  && ret=0
  case $state in