diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 2f7b7e9c00f76..dd11610b319a8 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/2025 ms.topic: reference --- # Investigate performance counters (dotnet-counters) @@ -12,16 +12,35 @@ 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 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:** Download the tool executable that matches your platform: @@ -108,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 `** @@ -180,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. **`-- `** diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md new file mode 100644 index 0000000000000..36e362338f3c5 --- /dev/null +++ b/docs/core/tools/dotnet-tool-exec.md @@ -0,0 +1,137 @@ +--- +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 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. + +`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 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 + +- **`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. 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 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`** + + 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 option defaults 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, `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) +- [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..09f190d516734 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..41347effd9b12 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,30 @@ 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 -``` +- 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. + +- Using `dotnet botsay`: + + ```dotnetcli + dotnet botsay hello from the bot + ``` + +- 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