Fix `dnx --help` and tool commands to use valid .NET tool examples #51009

Copilot · 2025-09-25T14:11:10Z

Customer Issue

Customers that read the dnx help are guided into using a package that isn't a tool - leading to an immediate failure when using dnx. We should instead at least provide examples that are invokable via dnx. Thanks to @mikekistler for reporting.

Description

Tiny help text change to suggest different packages in different scenarios.

Testing

Automated snapshot testing.

Risk

Low - only updates strings.

Copilot details

Fixes the issue where dnx --help, dotnet tool install --help, and other tool commands display Newtonsoft.Json as an example package, which is not a valid .NET tool.

@baronfel's note: I've reviewed this change and am happy with it. I need a team member review for the actual merge.

Changes Made

Single Format String Approach: Refactored to use a single format string in PackageIdentityArgumentDescription with placeholders {0} and {1} for package name and version, eliminating duplicate resource strings
Parameterized CommonArguments: Implemented parameterized methods for package identity arguments that accept example package and version parameters:
- RequiredPackageIdentityArgument(string examplePackage, string exampleVersion) - parameterized version
- OptionalPackageIdentityArgument(string examplePackage, string exampleVersion) - parameterized version
- Backward-compatible overloads maintained for existing callers
Context-Specific Examples: Updated tool command parsers to use appropriate examples:
- Tool commands (install/update/execute/dnx): use "dotnetsay", "2.1.7" parameters
- Non-tool commands: use "Newtonsoft.Json", "13.0.3" parameters (default)
Runtime Formatting: Uses string.Format() to populate placeholders dynamically at runtime
Updated CLI Snapshot Baselines: Updated completion test baselines to reflect the new tool examples
Documentation: Updated copilot-instructions with the dogfood testing approach for verifying CLI command changes

Commands Affected

All tool-related commands now show appropriate .NET tool examples:

dnx --help
dotnet tool install --help
dotnet tool exec --help
dotnet tool execute --help
dotnet tool update --help

Non-tool commands continue to use the generic package examples (e.g., dotnet package add --help still shows Newtonsoft.Json@13.0.3).

The changes maintain backward compatibility while providing more helpful and accurate examples for users working with .NET tools. The implementation uses a single source of truth for the format string, making it more maintainable and eliminating duplicate content.

Fixes #51008

Original prompt

This section details on the original issue you should resolve

<issue_title>dnx --help suggests use of a package that is not a .NET SDK Tool</issue_title>
<issue_description>### Describe the bug

dnx --help provides the following help output:

dnx --help
Description:
  Executes a tool from source without permanently installing it.

Usage:
  dotnet dnx <packageId> [<commandArguments>...] [options]

Arguments:
  <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'.
  <commandArguments>  Arguments forwarded to the tool

Options:
  --version <VERSION>       The version of the tool package to install.
  -y, --yes                 Accept all confirmation prompts using "yes." [default: False]
  --interactive             Allows the command to stop and wait for user input or action (for example to complete authentication). [default: True]
  --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. [default:
                            False]
  --prerelease              Include pre-release packages. [default: False]
  --configfile <FILE>       The NuGet configuration file to use.
  --source <SOURCE>         Replace all NuGet package sources to use during installation with these.
  --add-source <ADDSOURCE>  Add an additional NuGet package source to use during installation.
  --disable-parallel        Prevent restoring multiple projects in parallel. [default: False]
  --ignore-failed-sources   Treat package source failures as warnings. [default: False]
  --no-http-cache           Do not cache packages and http requests. [default: False]
  -v, --verbosity <LEVEL>   Set the MSBuild verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]. [default:
                            normal]
  -?, -h, --help            Show command line help.

The packageId argument's help description calls out Newtonsoft.Json, but this package isn't a valid .NET Tool. We need to make the Description of the shared 'packageId argument structure accept different descriptions, and then provide a better description for the tool-related use cases (dnx, dotnet dnx, dotnet tool exec, dotnet tool install`, etc).

The tool-related examples should use dotnetsay@2.1.7.

This change should be done against the release/10.0.1xx branch.

To Reproduce

Install any 10 preview 7 and above. Run dnx --help.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #51008

github-actions · 2025-09-25T14:29:48Z

This PR is targeting main, which is now for .NET 11-facing work. If you intended to target .NET 10, either retarget this PR to release/10.0.1xx or make sure you backport the change to release/10.0.1xx after merging. See #50394 for more details.

baronfel · 2025-09-25T14:35:38Z

@copilot I noticed that you were getting stuck testing your changes. When you need to test a change to a command, you need to build the new 'redist' SDK, and then use the 'dogfood' scripts to create an environment in which you can easily run the newly created CLI commands.

To build the new redist SDK, you run ./build.sh from the repo root. Then, you can create a new shell environment and source the eng/dogfood.sh script to make that shell environment inherently use the redist SDK. Once you do this, you should see your changes take effect. Try solving this problem and using this information to help you verify. If that works for you, update the copilot-instructions so that you know how to verify CLI changes in the future.

…amples Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Copilot · 2025-09-25T14:55:58Z

@copilot I noticed that you were getting stuck testing your changes. When you need to test a change to a command, you need to build the new 'redist' SDK, and then use the 'dogfood' scripts to create a...

Thank you for the guidance on using the dogfood script! I followed your approach:

Built the redist SDK using ./build.sh
Created a dogfood environment by sourcing eng/dogfood.sh
Tested my changes using dotnet tool install --help and dnx --help

The dogfood script works perfectly for testing CLI changes. However, I'm encountering a build/caching issue where the help output still shows the old Newtonsoft.Json examples despite:

The resource files containing the correct dotnetsay@2.1.7 examples
The generated C# code having the right resource accessors
Building and redistributing the CLI components

I've committed the core changes in 7c016c0. The changes are minimal and targeted:

Added ToolPackageIdentityArgumentDescription resource with dotnetsay@2.1.7
Extended CommonArguments with RequiredToolPackageIdentityArgument()
Updated ToolInstallCommandParser to use the tool-specific description

I've also updated the copilot-instructions to document this dogfood testing approach for future CLI changes.

…nges Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

baronfel · 2025-09-25T16:11:11Z

src/Cli/dotnet/CommonArguments.cs

+        public static DynamicArgument<PackageIdentityWithRange> RequiredToolPackageIdentityArgument() =>
+            new("packageId")
+            {
+                Description = CliStrings.ToolPackageIdentityArgumentDescription,
+                CustomParser = (ArgumentResult argumentResult) => ParsePackageIdentityWithVersionSeparator(argumentResult.Tokens[0]?.Value)!.Value,
+                Arity = ArgumentArity.ExactlyOne,
+            };
+


@copilot instead of creating a new parallel packageId argument, use a single shared implementation that takes a description as input. Then update call sites to pass the description that is most appropriate. Don't forget that when you change argument/option names or descriptions, you need to update the cli's snapshot test baselines as well.

Refactored to use a single shared implementation with parameterized description as suggested. The changes in b03b828:

Replaced duplicate methods with parameterized versions:

RequiredPackageIdentityArgument(string description)

OptionalPackageIdentityArgument(string description)

Backward-compatible overloads maintained

Updated call sites to pass appropriate descriptions:

Tool commands (install/update/execute/dnx): use CliStrings.ToolPackageIdentityArgumentDescription with dotnetsay@2.1.7

Package commands: continue using generic description with Newtonsoft.Json@13.0.3

Updated CLI snapshot baselines using the MSBuild targets - the snapshot tests now pass and show the tool commands correctly use the new examples.

The CLI completion system now properly distinguishes between tool and package contexts while maintaining a clean, shared implementation.

…eview feedback Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

baronfel · 2025-09-25T17:17:53Z

src/Cli/dotnet/CliStrings.resx

+  <data name="ToolPackageIdentityArgumentDescription" xml:space="preserve">
+    <value>Package reference in the form of a package identifier like 'dotnetsay' or package identifier and version separated by '@' like 'dotnetsay@2.1.7'.</value>
+  </data>


@copilot I'm going to nitpick once again. Instead of separate Description strings for tool packages and non-tool-packages, make a single format string with placeholders for a package id and version, and then update the callsites to use the templated format string, passing in the existing/appropriate package id and version.

Refactored to use a single format string with placeholders as suggested. Changes in bc0f3a2:

Single format string: Replaced duplicate resource strings with PackageIdentityArgumentDescription using {0} and {1} placeholders

Updated method signatures: Changed CommonArguments methods to accept examplePackage and exampleVersion parameters

Context-specific examples:

Tool commands: "dotnetsay", "2.1.7"

Non-tool commands: "Newtonsoft.Json", "13.0.3" (default)

Runtime formatting: Uses string.Format() to populate placeholders

This eliminates the duplicate resource string while maintaining clean separation between contexts through parameterization.

…ce strings Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Copilot

Pull Request Overview

This PR fixes the issue where dnx --help, dotnet tool install --help, and other tool commands display Newtonsoft.Json as an example package, which is not a valid .NET tool. The changes implement a parameterized approach to package identity argument descriptions, allowing different examples based on context.

Refactored PackageIdentityArgumentDescription to use placeholders {0} and {1} for dynamic package name and version examples
Added parameterized overloads to CommonArguments methods while maintaining backward compatibility
Updated tool command parsers to use appropriate .NET tool examples (dotnetsay@2.1.7)

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Cli/dotnet/CliStrings.resx	Modified the base resource string to use format placeholders instead of hardcoded examples
src/Cli/dotnet/xlf/*.xlf	Updated localization files with new format string and marked as needing translation
src/Cli/dotnet/CommonArguments.cs	Added parameterized methods for package identity arguments with example package/version parameters
src/Cli/dotnet/Commands/Tool/Install/ToolInstallCommandParser.cs	Updated to use tool-specific examples (dotnetsay@2.1.7)
src/Cli/dotnet/Commands/Tool/Update/ToolUpdateCommandParser.cs	Updated to use tool-specific examples (dotnetsay@2.1.7)
test/dotnet.Tests/CompletionTests/snapshots/zsh/DotnetCliSnapshotTests.VerifyCompletions.verified.zsh	Updated completion test baseline with new tool examples
.github/copilot-instructions.md	Added documentation for dogfood testing approach for CLI changes

baronfel · 2025-09-28T22:10:36Z

/backport to release/10.0.1xx

github-actions · 2025-09-28T22:10:46Z

Started backporting to release/10.0.1xx: https://github.com/dotnet/sdk/actions/runs/18080502142

Initial plan

ad6b924

Copilot AI assigned Copilot and baronfel Sep 25, 2025

Copilot started work on behalf of baronfel September 25, 2025 14:11 View session

Copilot stopped work on behalf of baronfel due to an error September 25, 2025 14:33
Copilot has encountered an error. See logs for additional details.

Copilot AI requested a review from baronfel September 25, 2025 14:33

Copilot started work on behalf of baronfel September 25, 2025 14:35 View session

Add tool-specific package identity descriptions to replace generic ex…

7c016c0

…amples Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Update copilot-instructions with dogfood testing approach for CLI cha…

fd497be

…nges Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] dnx --help suggests use of a package that is not a .NET SDK Tool~~ Fix dnx --help and tool commands to use valid .NET tool examples Sep 25, 2025

Copilot finished work on behalf of baronfel September 25, 2025 14:57

baronfel reviewed Sep 25, 2025

View reviewed changes

Copilot started work on behalf of baronfel September 25, 2025 16:11 View session

Copilot AI and others added 2 commits September 25, 2025 16:24

Refactor to use parameterized package identity argument methods per r…

64be82e

…eview feedback Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Update CLI snapshot test baselines for tool-specific package examples

b03b828

Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Copilot AI requested a review from baronfel September 25, 2025 16:28

Copilot finished work on behalf of baronfel September 25, 2025 16:28

baronfel reviewed Sep 25, 2025

View reviewed changes

Copilot started work on behalf of baronfel September 25, 2025 17:18 View session

Use single format string with placeholders instead of separate resour…

bc0f3a2

…ce strings Co-authored-by: baronfel <573979+baronfel@users.noreply.github.com>

Copilot AI requested a review from baronfel September 25, 2025 17:34

Copilot finished work on behalf of baronfel September 25, 2025 17:34

baronfel approved these changes Sep 25, 2025

View reviewed changes

baronfel requested a review from a team September 25, 2025 17:42

baronfel marked this pull request as ready for review September 25, 2025 18:21

Copilot AI review requested due to automatic review settings September 25, 2025 18:21

Copilot AI reviewed Sep 25, 2025

View reviewed changes

baronfel enabled auto-merge (squash) September 26, 2025 16:29

baronfel added Servicing-consider and removed Servicing-consider labels Sep 28, 2025

github-actions bot mentioned this pull request Sep 28, 2025

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

Merged

nagilson approved these changes Sep 29, 2025

View reviewed changes

baronfel merged commit 8b95e27 into main Sep 29, 2025
31 of 32 checks passed

baronfel deleted the copilot/fix-c0a951d4-e0f3-4238-814b-64deb537b388 branch September 29, 2025 17:23

nagilson mentioned this pull request Oct 7, 2025

Automate Update XLF Task and Updating Completions Tests Tasks #51157

Open

Copilot AI mentioned this pull request Oct 7, 2025

Add GitHub Actions workflows to automate XLF updates and completion test fixes #51158

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix `dnx --help` and tool commands to use valid .NET tool examples #51009

Fix `dnx --help` and tool commands to use valid .NET tool examples #51009

Uh oh!

Copilot AI commented Sep 25, 2025 •

edited by baronfel

Loading

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

baronfel commented Sep 25, 2025

Uh oh!

Copilot AI commented Sep 25, 2025

Uh oh!

baronfel Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

baronfel Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

baronfel commented Sep 28, 2025

Uh oh!

github-actions bot commented Sep 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Fix dnx --help and tool commands to use valid .NET tool examples #51009

Fix dnx --help and tool commands to use valid .NET tool examples #51009

Uh oh!

Conversation

Copilot AI commented Sep 25, 2025 • edited by baronfel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Customer Issue

Description

Testing

Risk

Changes Made

Commands Affected

To Reproduce

Comments on the Issue (you are @copilot in this section)

Uh oh!

github-actions bot commented Sep 25, 2025

Uh oh!

baronfel commented Sep 25, 2025

Uh oh!

Copilot AI commented Sep 25, 2025

Uh oh!

baronfel Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

baronfel Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

baronfel commented Sep 28, 2025

Uh oh!

github-actions bot commented Sep 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Fix `dnx --help` and tool commands to use valid .NET tool examples #51009

Fix `dnx --help` and tool commands to use valid .NET tool examples #51009

Copilot AI commented Sep 25, 2025 •

edited by baronfel

Loading