Skip to content

Commit 8f14788

Browse files
baronfelbaronfel
committed
Add new dotnet tool exec command documentation and point existing docs to use dnx as the top-level method.
1 parent 37097d7 commit 8f14788

File tree

5 files changed

+210
-12
lines changed

5 files changed

+210
-12
lines changed

‎docs/core/diagnostics/dotnet-counters.md

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: dotnet-counters diagnostic tool - .NET CLI
33
description: Learn how to install and use the dotnet-counter CLI tool for ad-hoc health monitoring and first-level performance investigation.
4-
ms.date: 11/17/2020
4+
ms.date: 09/06/2020
55
ms.topic: reference
66
---
77
# Investigate performance counters (dotnet-counters)
@@ -12,16 +12,34 @@ Counters can be read from applications running .NET 5 or later.
1212

1313
## Install
1414

15-
There are two ways to download and install `dotnet-counters`:
15+
There are three ways to download and use `dotnet-counters`:
16+
17+
- **One-shot execution (Recommended):**
18+
19+
Starting with .NET 10.0.100, you can run `dotnet-counters` without permanent installation using [`dnx`](../tools/dotnet-tool-exec.md):
20+
21+
```dotnetcli
22+
dnx dotnet-counters [options]
23+
```
24+
25+
For example:
26+
```dotnetcli
27+
dnx dotnet-counters monitor --process-id 1234
28+
```
29+
30+
This approach automatically downloads and runs the latest version without permanently modifying your system.
1631

1732
- **dotnet global tool:**
1833

19-
To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters), use the [dotnet tool install](../tools/dotnet-tool-install.md) command:
34+
To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters) for frequent use, use the [dotnet tool install](../tools/dotnet-tool-install.md) command:
2035

2136
```dotnetcli
2237
dotnet tool install --global dotnet-counters
2338
```
2439

40+
This method installs a `dotnet-counters` binary to your .NET SDK Tools path, which
41+
you can add to your PATH to easily invoke globally-installed tools.
42+
2543
- **Direct download:**
2644

2745
Download the tool executable that matches your platform:

‎docs/core/tools/dotnet-tool-exec.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: dotnet tool exec command
3+
description: The dotnet tool exec command downloads and invokes a .NET tool in one step without permanent installation.
4+
ms.date: 09/06/2025
5+
---
6+
# dotnet tool exec
7+
8+
**This article applies to:** ✔️ .NET 10.0.100-preview.6 SDK and later versions
9+
10+
## Name
11+
12+
`dotnet tool exec` - Downloads and invokes a .NET tool without permanently installing it.
13+
14+
## Synopsis
15+
16+
```dotnetcli
17+
dotnet tool exec <PACKAGE_NAME>[@<VERSION>]
18+
[--allow-roll-forward] [-a|--arch <ARCHITECTURE>]
19+
[--add-source <SOURCE>] [--configfile <FILE>] [--disable-parallel]
20+
[--framework <FRAMEWORK>] [--ignore-failed-sources] [--interactive]
21+
[--no-http-cache] [--prerelease]
22+
[-v|--verbosity <LEVEL>]
23+
[--] [<tool-arguments>...]
24+
25+
dotnet tool exec -h|--help
26+
```
27+
28+
## Description
29+
30+
The `dotnet tool exec` command provides a one-shot tool invocation mode for .NET Tools. It automatically downloads the specified tool package to the NuGet cache and invokes it without modifying your system PATH or requiring permanent installation.
31+
32+
When you run `dotnet tool exec`, the command:
33+
34+
1. Checks the version (or version range) you specify (or the latest version if none is specified) against your configured NuGet feeds to decide which package to download
35+
2. Downloads the specified package to the NuGet cache (if not already present)
36+
3. Invokes the tool with any provided arguments
37+
4. Returns the tool's exit code
38+
39+
The command interacts with local tool configurations seamlessly:
40+
- If a local tool manifest exists and contains the specified tool, it uses that version
41+
- Otherwise, it downloads the latest version or the version you specify
42+
43+
This command is ideal for:
44+
- Running tools without permanent installation
45+
- Trying out tools before deciding to install them
46+
- Running tools in CI/CD pipelines without setup steps
47+
- Using different versions of tools for different projects
48+
- Using the same mechanism across global and local tools
49+
50+
This command also exists in two other forms for easier use
51+
* `dotnet dnx` - a hidden alias for `dotnet tool exec` that is mostly used to give us a point to easily implement the
52+
* `dnx` - a shell script that invokes `dotnet dnx` from the SDK. This script is provided by the installer and is available on the PATH. It allows for very simple use of Tools directly via `dnx <toolname>`.
53+
54+
## Arguments
55+
56+
- **`PACKAGE_NAME`**
57+
58+
The NuGet package ID of the .NET tool to execute. You can optionally specify a version using the `@` syntax, for example `[email protected]`.
59+
60+
- **`tool-arguments`**
61+
62+
Arguments to pass to the tool being executed. Everything after `--` is passed directly to the tool.
63+
64+
## Options
65+
66+
- **`--allow-roll-forward`**
67+
68+
Allow the tool to use a newer version of the .NET runtime if the runtime it targets isn't installed.
69+
70+
- **`--add-source <SOURCE>`**
71+
72+
Adds an additional NuGet package source to use during installation. Feeds are accessed in parallel, not in a fallback cascade sequence. If the same package and version is available in multiple feeds, the fastest feed wins. See [What happens when a NuGet package is installed](/nuget/concepts/package-installation-process#what-happens-when-a-nuget-package-is-installed). This can be controlled through the use of NuGet Package Source Mapping. For more information, see [Package Source Mapping](~/nuget/consume-packages/package-source-mapping).
73+
74+
- **`--configfile <FILE>`**
75+
76+
The NuGet configuration file (*nuget.config*) to use. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](~/nuget/consume-packages/configuring-nuget-behavior).
77+
78+
- **`--disable-parallel`**
79+
80+
Disables querying the configured NuGet feeds in parallel.
81+
82+
- **`--ignore-failed-sources`**
83+
84+
Treats package source failures as warnings.
85+
86+
- **`--interactive`**
87+
88+
Allows the command to stop and wait for user input or action. For example, to complete authentication. This is defaulted to `true` when the command detects that it's being run directly by a user.
89+
90+
- **`--no-http-cache`**
91+
92+
Doesn't cache HTTP requests to the configured NuGet feeds.
93+
94+
- **`--prerelease`**
95+
96+
Allows prerelease packages to be selected when resolving the version to install.
97+
98+
- **`-v|--verbosity <LEVEL>`**
99+
100+
Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`. The default is `normal`.
101+
102+
[!INCLUDE [help](../../../includes/cli-help.md)]
103+
104+
## Examples
105+
106+
- **`dotnet tool exec dotnetsay`**
107+
108+
Downloads (if necessary) and runs the latest version of the `dotnetsay` tool.
109+
110+
- **`dotnet tool exec [email protected]`**
111+
112+
Downloads (if necessary) and runs version 2.1.0 of the `dotnetsay` tool.
113+
114+
- **`dotnet tool exec dotnetsay@2.*`**
115+
116+
Downloads (if necessary) and runs the latest version of the `dotnetsay` tool in the 2.x version range.
117+
118+
- **`dotnet tool exec dotnetsay -- Hello World`**
119+
120+
Runs the `dotnetsay` tool and passes "Hello World" as arguments to the tool.
121+
122+
- **`dotnet tool exec --add-source https://api.nuget.org/v3/index.json mytool`**
123+
124+
Downloads and runs `mytool` using the specified NuGet source.
125+
126+
## Comparison with other commands
127+
128+
This command is intended to be a unified way to work with .NET Tools. While the previously-available Tool installation commands remain available, we think that `dotnet tool exec` provides a simpler and more flexible experience for most users.
129+
130+
| Command | Purpose | Installation | Scope |
131+
|---------|---------|--------------|-------|
132+
| `dotnet tool exec` | One-shot execution | None (cached only) | Temporary |
133+
| `dotnet tool install -g` | Permanent global installation | Global | System-wide |
134+
| `dotnet tool install` | Permanent local installation | Local manifest | Project |
135+
| `dotnet tool run` | Run an already-installed local tool | Requires prior installation | Project |
136+
137+
The `dotnet tool install -g` command does still serve an important purpose for users who want to permanently install a tool. However, for users who want to try out a tool or run it in a CI/CD pipeline, `dotnet tool exec` is often a better fit.
138+
139+
## See also
140+
141+
- [.NET tools](global-tools.md)
142+
- [dnx command](dnx.md)
143+
- [dotnet tool install](dotnet-tool-install.md)
144+
- [dotnet tool run](dotnet-tool-run.md)
145+
- [Tutorial: Install and use a .NET global tool using the .NET CLI](global-tools-how-to-use.md)
146+
- [Tutorial: Install and use a .NET local tool using the .NET CLI](local-tools-how-to-use.md)

‎docs/core/tools/global-tools-how-to-use.md

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Tutorial: Install and use a .NET global tool"
33
description: Learn how to install and use a .NET tool as a global tool.
44
ms.topic: tutorial
5-
ms.date: 07/25/2023
5+
ms.date: 09/06/2025
66
---
77

88
# Tutorial: Install and use a .NET global tool using the .NET CLI
@@ -14,8 +14,23 @@ This tutorial teaches you how to install and use a global tool. You use a tool t
1414
## Prerequisites
1515

1616
* Complete the [first tutorial of this series](global-tools-how-to-create.md).
17+
* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended.
1718

18-
## Use the tool as a global tool
19+
## Run the tool without installation (Recommended)
20+
21+
Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md):
22+
23+
1. Run the tool directly using dnx (simplified syntax):
24+
25+
```dotnetcli
26+
dnx microsoft.botsay --add-source ./nupkg microsoft.botsay hello from the bot
27+
```
28+
29+
The `--add-source` parameter tells the .NET CLI to use the *./nupkg* directory as an additional source feed for NuGet packages when the tool is not available on NuGet.org.
30+
31+
## Use the tool as a global tool (Traditional installation)
32+
33+
If you prefer permanent installation for frequent use:
1934

2035
1. Install the tool from the package by running the [dotnet tool install](dotnet-tool-install.md) command in the *microsoft.botsay* project folder:
2136

‎docs/core/tools/local-tools-how-to-use.md

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Tutorial: Install and use .NET local tools"
33
description: Learn how to install and use a .NET tool as a local tool.
44
ms.topic: tutorial
5-
ms.date: 05/06/2022
5+
ms.date: 09/06/2022
66
---
77

88
# Tutorial: Install and use a .NET local tool using the .NET CLI
@@ -15,6 +15,7 @@ This tutorial teaches you how to install and use a local tool. You use a tool th
1515

1616
* Complete the [first tutorial of this series](global-tools-how-to-create.md).
1717
* Install the .NET Core 2.1 runtime.
18+
* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended.
1819

1920
For this tutorial you install and use a tool that targets .NET Core 2.1, so you need to have that runtime installed on your machine. To install the 2.1 runtime, go to the [.NET Core 2.1 download page](https://dotnet.microsoft.com/download/dotnet/2.1) and find the runtime installation link in the **Run apps - Runtime** column.
2021

@@ -54,7 +55,7 @@ The tools listed in a manifest file are available to the current directory and s
5455

5556
When you use a CLI command that refers to a local tool, the SDK searches for a manifest file in the current directory and parent directories. If it finds a manifest file, but the file doesn't include the referenced tool, it continues the search up through parent directories. The search ends when it finds the referenced tool or it finds a manifest file with `isRoot` set to `true`.
5657

57-
## Install botsay as a local tool
58+
## Install botsay as a local tool (Traditional approach)
5859

5960
Install the tool from the package that you created in the first tutorial:
6061

@@ -88,13 +89,29 @@ The *.config/dotnet-tools.json* file now has one tool:
8889
}
8990
```
9091

91-
## Use the tool
92+
## Use the installed local tool
9293

93-
Invoke the tool by running the `dotnet tool run` command from the *repository* folder:
94+
Once installed as a local tool, you can invoke it in multiple ways:
9495

95-
```dotnetcli
96-
dotnet tool run botsay hello from the bot
97-
```
96+
1. Run the tool directly using `dnx`:
97+
98+
```dotnetcli
99+
dnx microsoft.botsay --add-source ./nupkg hello from the bot
100+
```
101+
102+
> [!NOTE]
103+
> When using dnx with a local tool manifest, it automatically uses the version specified in the manifest.
104+
105+
106+
2. Using `dotnet botsay` (recommended for local tools):
107+
```dotnetcli
108+
dotnet botsay hello from the bot
109+
```
110+
111+
3. Using `dotnet tool run`
112+
```dotnetcli
113+
dotnet tool run botsay hello from the bot
114+
```
98115

99116
## Restore a local tool installed by others
100117

‎docs/navigate/tools-diagnostics/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,8 @@ items:
214214
href: ../../core/tools/dotnet-test.md
215215
- name: dotnet tool
216216
items:
217+
- name: dotnet tool exec
218+
href: ../../core/tools/dotnet-tool-exec.md
217219
- name: dotnet tool install
218220
href: ../../core/tools/dotnet-tool-install.md
219221
- name: dotnet tool list

0 commit comments

Comments
 (0)