Skip to content

Update the .NET tools documentation based on a review of the code. #47675

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update the .NET tools documentation based on a review of the code. #47675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4eb445f
Update the .NET tools documentation based on a review of the code.
marcpopMSFT Jul 30, 2025
2db4cfd
PR feedback
marcpopMSFT Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/core/tools/dotnet-tool-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ The `dotnet tool install` command provides a way for you to install .NET tools o
* To install a global tool in a custom location, use the `--tool-path` option.
* To install a local tool, omit the `--global` and `--tool-path` options.

> [!WARNING]
> Make sure the directory you specify with the `--tool-path` option is secure. Tools installed in this location can be executed directly, so using an untrusted or shared path might introduce security risks.

## Installation locations

### Global tools
Expand Down Expand Up @@ -121,6 +124,11 @@ For more information, see [Install a local tool](global-tools.md#install-a-local

For more information on how manifests are located, see [Install a local tool](global-tools.md#install-a-local-tool).

Starting in .NET 10, this flag is applied automatically if no tools manifest is found.

> [!WARNING]
> Don't run tool commands from the **Downloads** folder or any shared location. The CLI walks up the directory tree to find a tool manifest, which might cause it to use a manifest you don't expect. Always run tool commands from a trusted, project-specific directory.

- **`--disable-parallel`**

Prevent restoring multiple projects in parallel.
Expand Down
3 changes: 3 additions & 0 deletions docs/core/tools/global-tools-how-to-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,9 @@ Before you can pack and distribute the application as a tool, you need to modify

`<ToolCommandName>` is an optional element that specifies the command that will invoke the tool after it's installed. If this element isn't provided, the command name for the tool is the assembly name, which is typically the project file name without the *.csproj* extension.

> [!NOTE]
> Choose a unique value for `<ToolCommandName>`. Avoid using file extensions (like `.exe` or `.cmd`) because the tool is installed as an app host and the command should not include an extension. This helps prevent conflicts with existing commands and ensures a smooth installation experience.

`<PackageOutputPath>` is an optional element that determines where the NuGet package will be produced. The NuGet package is what the .NET CLI uses to install your tool.

The project file now looks like the following example:
Expand Down
3 changes: 3 additions & 0 deletions docs/core/tools/global-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,9 @@ dotnet new tool-manifest

This command creates a manifest file named *dotnet-tools.json* under the *.config* directory. To add a local tool to the manifest file, use the [dotnet tool install](dotnet-tool-install.md) command and **omit** the `--global` and `--tool-path` options, as shown in the following example:

> [!WARNING]
> Make sure the tool manifest file is stored in a controlled location. The .NET CLI launches local tools with `dotnet tool run` based on the contents of the tool manifest. If the manifest is modified by an untrusted party, it could cause the CLI to run malicious code.

```dotnetcli
dotnet tool install dotnetsay
```
Expand Down