From 8f1478892fa3f79965f210a5359b43cadc02e71e Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 12:27:38 -0500 Subject: [PATCH 1/8] Add new `dotnet tool exec` command documentation and point existing docs to use `dnx` as the top-level method. --- docs/core/diagnostics/dotnet-counters.md | 24 +++- docs/core/tools/dotnet-tool-exec.md | 146 +++++++++++++++++++++ docs/core/tools/global-tools-how-to-use.md | 19 ++- docs/core/tools/local-tools-how-to-use.md | 31 ++++- docs/navigate/tools-diagnostics/toc.yml | 2 + 5 files changed, 210 insertions(+), 12 deletions(-) create mode 100644 docs/core/tools/dotnet-tool-exec.md diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 2f7b7e9c00f76..104f05ec8916b 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -1,7 +1,7 @@ --- title: dotnet-counters diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-counter CLI tool for ad-hoc health monitoring and first-level performance investigation. -ms.date: 11/17/2020 +ms.date: 09/06/2020 ms.topic: reference --- # Investigate performance counters (dotnet-counters) @@ -12,16 +12,34 @@ Counters can be read from applications running .NET 5 or later. ## Install -There are two ways to download and install `dotnet-counters`: +There are three ways to download and use `dotnet-counters`: + +- **One-shot execution (Recommended):** + + Starting with .NET 10.0.100, you can run `dotnet-counters` without permanent installation using [`dnx`](../tools/dotnet-tool-exec.md): + + ```dotnetcli + dnx dotnet-counters [options] + ``` + + For example: + ```dotnetcli + dnx dotnet-counters monitor --process-id 1234 + ``` + + This approach automatically downloads and runs the latest version without permanently modifying your system. - **dotnet global tool:** - 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: + 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: ```dotnetcli dotnet tool install --global dotnet-counters ``` +This method installs a `dotnet-counters` binary to your .NET SDK Tools path, which +you can add to your PATH to easily invoke globally-installed tools. + - **Direct download:** Download the tool executable that matches your platform: diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md new file mode 100644 index 0000000000000..23ab8e384b39c --- /dev/null +++ b/docs/core/tools/dotnet-tool-exec.md @@ -0,0 +1,146 @@ +--- +title: dotnet tool exec command +description: The dotnet tool exec command downloads and invokes a .NET tool in one step without permanent installation. +ms.date: 09/06/2025 +--- +# dotnet tool exec + +**This article applies to:** ✔️ .NET 10.0.100-preview.6 SDK and later versions + +## Name + +`dotnet tool exec` - Downloads and invokes a .NET tool without permanently installing it. + +## Synopsis + +```dotnetcli +dotnet tool exec [@] + [--allow-roll-forward] [-a|--arch ] + [--add-source ] [--configfile ] [--disable-parallel] + [--framework ] [--ignore-failed-sources] [--interactive] + [--no-http-cache] [--prerelease] + [-v|--verbosity ] + [--] [...] + +dotnet tool exec -h|--help +``` + +## Description + +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. + +When you run `dotnet tool exec`, the command: + +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 +2. Downloads the specified package to the NuGet cache (if not already present) +3. Invokes the tool with any provided arguments +4. Returns the tool's exit code + +The command interacts with local tool configurations seamlessly: +- If a local tool manifest exists and contains the specified tool, it uses that version +- Otherwise, it downloads the latest version or the version you specify + +This command is ideal for: +- Running tools without permanent installation +- Trying out tools before deciding to install them +- Running tools in CI/CD pipelines without setup steps +- Using different versions of tools for different projects +- Using the same mechanism across global and local tools + +This command also exists in two other forms for easier use +* `dotnet dnx` - a hidden alias for `dotnet tool exec` that is mostly used to give us a point to easily implement the +* `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 `. + +## Arguments + +- **`PACKAGE_NAME`** + + The NuGet package ID of the .NET tool to execute. You can optionally specify a version using the `@` syntax, for example `dotnetsay@2.1.0`. + +- **`tool-arguments`** + + Arguments to pass to the tool being executed. Everything after `--` is passed directly to the tool. + +## Options + +- **`--allow-roll-forward`** + + Allow the tool to use a newer version of the .NET runtime if the runtime it targets isn't installed. + +- **`--add-source `** + + 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). + +- **`--configfile `** + + 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). + +- **`--disable-parallel`** + + Disables querying the configured NuGet feeds in parallel. + +- **`--ignore-failed-sources`** + + Treats package source failures as warnings. + +- **`--interactive`** + + 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. + +- **`--no-http-cache`** + + Doesn't cache HTTP requests to the configured NuGet feeds. + +- **`--prerelease`** + + Allows prerelease packages to be selected when resolving the version to install. + +- **`-v|--verbosity `** + + 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`. + +[!INCLUDE [help](../../../includes/cli-help.md)] + +## Examples + +- **`dotnet tool exec dotnetsay`** + + Downloads (if necessary) and runs the latest version of the `dotnetsay` tool. + +- **`dotnet tool exec dotnetsay@2.1.0`** + + Downloads (if necessary) and runs version 2.1.0 of the `dotnetsay` tool. + +- **`dotnet tool exec dotnetsay@2.*`** + + Downloads (if necessary) and runs the latest version of the `dotnetsay` tool in the 2.x version range. + +- **`dotnet tool exec dotnetsay -- Hello World`** + + Runs the `dotnetsay` tool and passes "Hello World" as arguments to the tool. + +- **`dotnet tool exec --add-source https://api.nuget.org/v3/index.json mytool`** + + Downloads and runs `mytool` using the specified NuGet source. + +## Comparison with other commands + +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. + +| Command | Purpose | Installation | Scope | +|---------|---------|--------------|-------| +| `dotnet tool exec` | One-shot execution | None (cached only) | Temporary | +| `dotnet tool install -g` | Permanent global installation | Global | System-wide | +| `dotnet tool install` | Permanent local installation | Local manifest | Project | +| `dotnet tool run` | Run an already-installed local tool | Requires prior installation | Project | + +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. + +## See also + +- [.NET tools](global-tools.md) +- [dnx command](dnx.md) +- [dotnet tool install](dotnet-tool-install.md) +- [dotnet tool run](dotnet-tool-run.md) +- [Tutorial: Install and use a .NET global tool using the .NET CLI](global-tools-how-to-use.md) +- [Tutorial: Install and use a .NET local tool using the .NET CLI](local-tools-how-to-use.md) diff --git a/docs/core/tools/global-tools-how-to-use.md b/docs/core/tools/global-tools-how-to-use.md index d11a9eb04d2ab..b583234f69058 100644 --- a/docs/core/tools/global-tools-how-to-use.md +++ b/docs/core/tools/global-tools-how-to-use.md @@ -2,7 +2,7 @@ title: "Tutorial: Install and use a .NET global tool" description: Learn how to install and use a .NET tool as a global tool. ms.topic: tutorial -ms.date: 07/25/2023 +ms.date: 09/06/2025 --- # 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 ## Prerequisites * Complete the [first tutorial of this series](global-tools-how-to-create.md). +* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended. -## Use the tool as a global tool +## Run the tool without installation (Recommended) + +Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md): + +1. Run the tool directly using dnx (simplified syntax): + + ```dotnetcli + dnx microsoft.botsay --add-source ./nupkg microsoft.botsay hello from the bot + ``` + + 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. + +## Use the tool as a global tool (Traditional installation) + +If you prefer permanent installation for frequent use: 1. Install the tool from the package by running the [dotnet tool install](dotnet-tool-install.md) command in the *microsoft.botsay* project folder: diff --git a/docs/core/tools/local-tools-how-to-use.md b/docs/core/tools/local-tools-how-to-use.md index 6a05097d9f497..ad53608b58122 100644 --- a/docs/core/tools/local-tools-how-to-use.md +++ b/docs/core/tools/local-tools-how-to-use.md @@ -2,7 +2,7 @@ title: "Tutorial: Install and use .NET local tools" description: Learn how to install and use a .NET tool as a local tool. ms.topic: tutorial -ms.date: 05/06/2022 +ms.date: 09/06/2022 --- # 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 * Complete the [first tutorial of this series](global-tools-how-to-create.md). * Install the .NET Core 2.1 runtime. +* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended. 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. @@ -54,7 +55,7 @@ The tools listed in a manifest file are available to the current directory and s 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`. -## Install botsay as a local tool +## Install botsay as a local tool (Traditional approach) Install the tool from the package that you created in the first tutorial: @@ -88,13 +89,29 @@ The *.config/dotnet-tools.json* file now has one tool: } ``` -## Use the tool +## Use the installed local tool -Invoke the tool by running the `dotnet tool run` command from the *repository* folder: +Once installed as a local tool, you can invoke it in multiple ways: -```dotnetcli -dotnet tool run botsay hello from the bot -``` +1. Run the tool directly using `dnx`: + + ```dotnetcli + dnx microsoft.botsay --add-source ./nupkg hello from the bot + ``` + + > [!NOTE] + > When using dnx with a local tool manifest, it automatically uses the version specified in the manifest. + + +2. Using `dotnet botsay` (recommended for local tools): + ```dotnetcli + dotnet botsay hello from the bot + ``` + +3. Using `dotnet tool run` + ```dotnetcli + dotnet tool run botsay hello from the bot + ``` ## Restore a local tool installed by others diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 2220f172b118a..79265422ba3ff 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -214,6 +214,8 @@ items: href: ../../core/tools/dotnet-test.md - name: dotnet tool items: + - name: dotnet tool exec + href: ../../core/tools/dotnet-tool-exec.md - name: dotnet tool install href: ../../core/tools/dotnet-tool-install.md - name: dotnet tool list From 388f768db3948c657f27926eb040a9045b94ea44 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 14:04:09 -0500 Subject: [PATCH 2/8] resolve linting errors --- docs/core/diagnostics/dotnet-counters.md | 1 + docs/core/tools/dotnet-tool-exec.md | 12 ++---------- docs/core/tools/local-tools-how-to-use.md | 3 ++- 3 files changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 104f05ec8916b..2332326110dd7 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -23,6 +23,7 @@ There are three ways to download and use `dotnet-counters`: ``` For example: + ```dotnetcli dnx dotnet-counters monitor --process-id 1234 ``` diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index 23ab8e384b39c..9a0cfbb6636be 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -36,18 +36,10 @@ When you run `dotnet tool exec`, the command: 3. Invokes the tool with any provided arguments 4. Returns the tool's exit code -The command interacts with local tool configurations seamlessly: -- If a local tool manifest exists and contains the specified tool, it uses that version -- Otherwise, it downloads the latest version or the version you specify - -This command is ideal for: -- Running tools without permanent installation -- Trying out tools before deciding to install them -- Running tools in CI/CD pipelines without setup steps -- Using different versions of tools for different projects -- Using the same mechanism across global and local tools +`dotnet tool exec` works seamlessly with both global and local tools. If you have a local tool manifest available, it uses the manifest to determine which version of the tool to run. This command also exists in two other forms for easier use + * `dotnet dnx` - a hidden alias for `dotnet tool exec` that is mostly used to give us a point to easily implement the * `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 `. diff --git a/docs/core/tools/local-tools-how-to-use.md b/docs/core/tools/local-tools-how-to-use.md index ad53608b58122..edd29cd9db97b 100644 --- a/docs/core/tools/local-tools-how-to-use.md +++ b/docs/core/tools/local-tools-how-to-use.md @@ -102,13 +102,14 @@ Once installed as a local tool, you can invoke it in multiple ways: > [!NOTE] > When using dnx with a local tool manifest, it automatically uses the version specified in the manifest. +2. Using `dotnet botsay`: -2. Using `dotnet botsay` (recommended for local tools): ```dotnetcli dotnet botsay hello from the bot ``` 3. Using `dotnet tool run` + ```dotnetcli dotnet tool run botsay hello from the bot ``` From 4b3d43d25c21d9c9ad096cff5fa49c600695ef62 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 14:13:22 -0500 Subject: [PATCH 3/8] fix invalid link --- docs/core/tools/dotnet-tool-exec.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index 9a0cfbb6636be..400b4ee828699 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -131,7 +131,6 @@ The `dotnet tool install -g` command does still serve an important purpose for u ## See also - [.NET tools](global-tools.md) -- [dnx command](dnx.md) - [dotnet tool install](dotnet-tool-install.md) - [dotnet tool run](dotnet-tool-run.md) - [Tutorial: Install and use a .NET global tool using the .NET CLI](global-tools-how-to-use.md) From 96dc716fa1f8b5cc75f8372b4a44cb9585da91c3 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 14:25:36 -0500 Subject: [PATCH 4/8] fix nuget package source mapping redirects --- docs/core/tools/dotnet-tool-exec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index 400b4ee828699..ee0f5fd82ac02 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -61,11 +61,11 @@ This command also exists in two other forms for easier use - **`--add-source `** - 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). + 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). - **`--configfile `** - 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). + 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). - **`--disable-parallel`** From 230cbcef47882aeb5e83eac1ef4f36edcf3feefb Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 14:28:22 -0500 Subject: [PATCH 5/8] udpate dotnet-counters urls to be relative to silence suggestion from OPB --- docs/core/diagnostics/dotnet-counters.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 2332326110dd7..414243e181b17 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -1,7 +1,7 @@ --- title: dotnet-counters diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-counter CLI tool for ad-hoc health monitoring and first-level performance investigation. -ms.date: 09/06/2020 +ms.date: 09/06/2025 ms.topic: reference --- # Investigate performance counters (dotnet-counters) @@ -127,7 +127,7 @@ dotnet-counters collect [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic- - **`--counters `** - A comma-separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying list of counters, then all counters from the provider are shown. To discover provider and counter names, consult [built-in metrics docs](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics). For [EventCounters](event-counters.md), `provider_name` is the name of the EventSource and for [Meters](metrics.md), `provider_name` is the name of the Meter. + A comma-separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying list of counters, then all counters from the provider are shown. To discover provider and counter names, consult [built-in metrics docs](built-in-metrics.md). For [EventCounters](event-counters.md), `provider_name` is the name of the EventSource and for [Meters](metrics.md), `provider_name` is the name of the Meter. - **`--format `** @@ -199,7 +199,7 @@ dotnet-counters monitor [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic- - **`--counters `** - A comma-separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying list of counters, then all counters from the provider are shown. To discover provider and counter names, consult [built-in metrics docs](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics). For [EventCounters](event-counters.md), `provider_name` is the name of the EventSource and for [Meters](metrics.md), `provider_name` is the name of the Meter. + A comma-separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying list of counters, then all counters from the provider are shown. To discover provider and counter names, consult [built-in metrics docs](built-in-metrics.md). For [EventCounters](event-counters.md), `provider_name` is the name of the EventSource and for [Meters](metrics.md), `provider_name` is the name of the Meter. **`-- `** @@ -274,7 +274,7 @@ dotnet-counters monitor [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic- ``` > [!NOTE] - > If the app uses .NET version 8 or lower the [System.Runtime Meter](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics-runtime#systemruntime) didn't exist yet and dotnet-counters will fall back to display the older [System.Runtime EventCounters](https://learn.microsoft.com/dotnet/core/diagnostics/available-counters#systemruntime-counters) instead. The UI will look slightly different as shown below. + > If the app uses .NET version 8 or lower the [System.Runtime Meter](built-in-metrics-runtime#systemruntime) didn't exist yet and dotnet-counters will fall back to display the older [System.Runtime EventCounters](available-counters#systemruntime-counters) instead. The UI will look slightly different as shown below. ``` [System.Runtime] From 6f279e524fb08cc730c5a95f40495f7718a242e8 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Sat, 6 Sep 2025 15:12:54 -0500 Subject: [PATCH 6/8] Revert these two link suggestion fixes because they result in invalid links --- docs/core/diagnostics/dotnet-counters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 414243e181b17..c063003bdb3a4 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -274,7 +274,7 @@ dotnet-counters monitor [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic- ``` > [!NOTE] - > If the app uses .NET version 8 or lower the [System.Runtime Meter](built-in-metrics-runtime#systemruntime) didn't exist yet and dotnet-counters will fall back to display the older [System.Runtime EventCounters](available-counters#systemruntime-counters) instead. The UI will look slightly different as shown below. + > If the app uses .NET version 8 or lower the [System.Runtime Meter](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics-runtime#systemruntime) didn't exist yet and dotnet-counters will fall back to display the older [System.Runtime EventCounters](https://learn.microsoft.com/dotnet/core/diagnostics/available-counters#systemruntime-counters) instead. The UI will look slightly different as shown below. ``` [System.Runtime] From 64da1f0c912bd653761bc674638ea72040fa96f8 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Tue, 9 Sep 2025 09:55:21 -0500 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/diagnostics/dotnet-counters.md | 4 ++-- docs/core/tools/dotnet-tool-exec.md | 24 +++++++++++----------- docs/core/tools/global-tools-how-to-use.md | 4 ++-- docs/core/tools/local-tools-how-to-use.md | 8 ++++---- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index c063003bdb3a4..dd11610b319a8 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -14,7 +14,7 @@ Counters can be read from applications running .NET 5 or later. There are three ways to download and use `dotnet-counters`: -- **One-shot execution (Recommended):** +- **One-shot execution (recommended):** Starting with .NET 10.0.100, you can run `dotnet-counters` without permanent installation using [`dnx`](../tools/dotnet-tool-exec.md): @@ -38,7 +38,7 @@ There are three ways to download and use `dotnet-counters`: dotnet tool install --global dotnet-counters ``` -This method installs a `dotnet-counters` binary to your .NET SDK Tools path, which + This command installs a `dotnet-counters` binary to your .NET SDK Tools path, which you can add to your PATH to easily invoke globally-installed tools. - **Direct download:** diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index ee0f5fd82ac02..36e362338f3c5 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -5,7 +5,7 @@ ms.date: 09/06/2025 --- # dotnet tool exec -**This article applies to:** ✔️ .NET 10.0.100-preview.6 SDK and later versions +**This article applies to:** ✔️ .NET 10.0.100 SDK and later versions ## Name @@ -27,21 +27,21 @@ dotnet tool exec -h|--help ## Description -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. +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. When you run `dotnet tool exec`, the command: -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 -2. Downloads the specified package to the NuGet cache (if not already present) -3. Invokes the tool with any provided arguments -4. Returns the tool's exit code +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. +2. Downloads the specified package to the NuGet cache (if not already present). +3. Invokes the tool with any provided arguments. +4. Returns the tool's exit code. `dotnet tool exec` works seamlessly with both global and local tools. If you have a local tool manifest available, it uses the manifest to determine which version of the tool to run. This command also exists in two other forms for easier use -* `dotnet dnx` - a hidden alias for `dotnet tool exec` that is mostly used to give us a point to easily implement the -* `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 `. +* `dotnet dnx` - A hidden alias for `dotnet tool exec` that is mostly used to as a point to easily implement the ??? +* `dnx` - A shell script that invokes `dotnet dnx` from the SDK. This script is provided by the installer and is available on `PATH`. It allows for very simple use of tools directly via `dnx `. ## Arguments @@ -61,11 +61,11 @@ This command also exists in two other forms for easier use - **`--add-source `** - 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). + 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. For more information, see [What happens when a NuGet package is installed](/nuget/concepts/package-installation-process#what-happens-when-a-nuget-package-is-installed). You can control this through the use of NuGet package source mapping. For more information, see [Package Source Mapping](/nuget/consume-packages/package-source-mapping). - **`--configfile `** - 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). + The NuGet configuration file (*nuget.config*) to use. If specified, only the settings from this file are used. If not specified, the hierarchy of configuration files from the current directory are used. For more information, see [Common NuGet Configurations](/nuget/consume-packages/configuring-nuget-behavior). - **`--disable-parallel`** @@ -77,7 +77,7 @@ This command also exists in two other forms for easier use - **`--interactive`** - 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. + Allows the command to stop and wait for user input or action, for example, to complete authentication. This option defaults to `true` when the command detects that it's being run directly by a user. - **`--no-http-cache`** @@ -117,7 +117,7 @@ This command also exists in two other forms for easier use ## Comparison with other commands -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. +This command is intended to be a unified way to work with .NET Tools. While the previously available tool installation commands remain available, `dotnet tool exec` provides a simpler and more flexible experience for most users. | Command | Purpose | Installation | Scope | |---------|---------|--------------|-------| diff --git a/docs/core/tools/global-tools-how-to-use.md b/docs/core/tools/global-tools-how-to-use.md index b583234f69058..09f190d516734 100644 --- a/docs/core/tools/global-tools-how-to-use.md +++ b/docs/core/tools/global-tools-how-to-use.md @@ -16,7 +16,7 @@ This tutorial teaches you how to install and use a global tool. You use a tool t * Complete the [first tutorial of this series](global-tools-how-to-create.md). * .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended. -## Run the tool without installation (Recommended) +## Run the tool without installation (recommended) Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md): @@ -28,7 +28,7 @@ Starting with .NET 10.0.100, you can run .NET tools without permanent installati 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. -## Use the tool as a global tool (Traditional installation) +## Use the tool as a global tool (traditional installation) If you prefer permanent installation for frequent use: diff --git a/docs/core/tools/local-tools-how-to-use.md b/docs/core/tools/local-tools-how-to-use.md index edd29cd9db97b..41347effd9b12 100644 --- a/docs/core/tools/local-tools-how-to-use.md +++ b/docs/core/tools/local-tools-how-to-use.md @@ -55,7 +55,7 @@ The tools listed in a manifest file are available to the current directory and s 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`. -## Install botsay as a local tool (Traditional approach) +## Install botsay as a local tool (traditional approach) Install the tool from the package that you created in the first tutorial: @@ -93,7 +93,7 @@ The *.config/dotnet-tools.json* file now has one tool: Once installed as a local tool, you can invoke it in multiple ways: -1. Run the tool directly using `dnx`: +- Run the tool directly using `dnx`: ```dotnetcli dnx microsoft.botsay --add-source ./nupkg hello from the bot @@ -102,13 +102,13 @@ Once installed as a local tool, you can invoke it in multiple ways: > [!NOTE] > When using dnx with a local tool manifest, it automatically uses the version specified in the manifest. -2. Using `dotnet botsay`: +- Using `dotnet botsay`: ```dotnetcli dotnet botsay hello from the bot ``` -3. Using `dotnet tool run` +- Using `dotnet tool run` ```dotnetcli dotnet tool run botsay hello from the bot From 18980e4e3ab4f9996f7ec78f14a1150167fdb367 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Wed, 1 Oct 2025 07:58:29 -0500 Subject: [PATCH 8/8] Update docs/core/tools/dotnet-tool-exec.md --- docs/core/tools/dotnet-tool-exec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index 36e362338f3c5..62abdd17e52e0 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -40,7 +40,7 @@ When you run `dotnet tool exec`, the command: This command also exists in two other forms for easier use -* `dotnet dnx` - A hidden alias for `dotnet tool exec` that is mostly used to as a point to easily implement the ??? +* `dotnet dnx` - A hidden alias for `dotnet tool exec` that is used as a way to easily implement the `dnx` script itself * `dnx` - A shell script that invokes `dotnet dnx` from the SDK. This script is provided by the installer and is available on `PATH`. It allows for very simple use of tools directly via `dnx `. ## Arguments