[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