From 724365dfe93907408c8638639199a074a3553714 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 Aug 2025 17:31:01 +0000 Subject: [PATCH 1/6] Initial plan From 5bdfddab38e5cdc7d271ff2be423dc93bf15c3ef Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 Aug 2025 17:37:07 +0000 Subject: [PATCH 2/6] Add breaking change documentation for dotnet tool install --local manifest creation Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- .../dotnet-tool-install-local-manifest.md | 42 +++++++++++++++++++ docs/core/tools/dotnet-tool-install.md | 8 ++-- 2 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md diff --git a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md new file mode 100644 index 0000000000000..f8e75c4d0d76b --- /dev/null +++ b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md @@ -0,0 +1,42 @@ +--- +title: "Breaking change: dotnet tool install --local works by default, by creating a manifest by default" +description: "Learn about the breaking change where dotnet tool install --local now creates a manifest by default using --create-manifest-if-needed behavior." +ms.date: 08/27/2025 +ai-usage: ai-generated +--- + +# dotnet tool install --local works by default, by creating a manifest by default + +When running `dotnet tool install --local`, a manifest is now created if one does not exist instead of failing with an error. This was implemented by making `--create-manifest-if-needed` enabled by default. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +When a user tried to install a .NET tool as a local tool in a folder that did not contain a manifest, they would get an error: "Cannot find a manifest file." + +## New behavior + +The `--create-manifest-if-needed` functionality is now enabled by default, so the manifest will be created automatically if it does not exist when a tool is installed as a local tool. The manifest is created according to the following rules: + +- Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory. +- If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory. +- If neither of the previous two steps finds a directory, create the manifest in the current working directory. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change improves the user experience by making `dotnet tool install --local` work by default without requiring users to manually create a manifest first. Previously, the concern was about creating a manifest in a working directory rather than the repository root, but the tool now tries to put the manifest in the repository root when possible. + +## Recommended action + +Users can turn off the automatic manifest creation behavior by setting `--create-manifest-if-needed=false` if they prefer the previous behavior where the command would fail when no manifest exists. + +## Affected APIs + +N/A \ No newline at end of file diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index d8ea2002dba2d..b9b55963cee13 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -80,7 +80,7 @@ Tools with explicit tool paths are stored wherever you specified the `--tool-pat Local tools are stored in the NuGet global directory, whatever you've set that to be. There are shim files in `$HOME/.dotnet/toolResolverCache` for each local tool that point to where the tools are within that location. -References to local tools are added to a *dotnet-tools.json* file in a *.config* directory under the current directory. If a manifest file doesn't exist yet, create it by using the `--create-manifest-if-needed` option or by running the following command: +References to local tools are added to a *dotnet-tools.json* file in a *.config* directory under the current directory. Starting in .NET 10, if a manifest file doesn't exist yet, one is created automatically. You can also create one manually by running the following command: ```dotnetcli dotnet new tool-manifest @@ -112,11 +112,11 @@ For more information, see [Install a local tool](global-tools.md#install-a-local - **`--create-manifest-if-needed`** - Applies to local tools. Available starting with .NET 8 SDK. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file. + Applies to local tools. Available starting with .NET 8 SDK. Starting in .NET 10, this behavior is enabled by default. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file. If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to false, the `CannotFindAManifestFile` error occurs. - If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to true, the tool creates a manifest automatically. It chooses a folder for the manifest as follows: + If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to true (or starting in .NET 10, when not specified), the tool creates a manifest automatically. It chooses a folder for the manifest as follows: * Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory. * If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory. @@ -124,7 +124,7 @@ 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. + Starting in .NET 10, this behavior is applied automatically if no tools manifest is found. Users can opt out by explicitly setting `--create-manifest-if-needed=false`. > [!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. From 3e81ee2272496bc42513852e865e0f2cfbd5dfb7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 27 Aug 2025 17:39:32 +0000 Subject: [PATCH 3/6] Improve title and fix date format in breaking change documentation Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- .../sdk/10.0/dotnet-tool-install-local-manifest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md index f8e75c4d0d76b..a2d382249f5e4 100644 --- a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md +++ b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md @@ -1,11 +1,11 @@ --- -title: "Breaking change: dotnet tool install --local works by default, by creating a manifest by default" +title: "Breaking change: dotnet tool install --local creates manifest by default" description: "Learn about the breaking change where dotnet tool install --local now creates a manifest by default using --create-manifest-if-needed behavior." -ms.date: 08/27/2025 +ms.date: 08/27/2024 ai-usage: ai-generated --- -# dotnet tool install --local works by default, by creating a manifest by default +# dotnet tool install --local creates manifest by default When running `dotnet tool install --local`, a manifest is now created if one does not exist instead of failing with an error. This was implemented by making `--create-manifest-if-needed` enabled by default. From 7040aec34aed480fd2a227bbd7e077d4d46ffd93 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:51:26 -0700 Subject: [PATCH 4/6] human edits --- docs/core/compatibility/10.0.md | 1 + .../dotnet-tool-install-local-manifest.md | 28 +++++++++++-------- docs/core/compatibility/toc.yml | 2 ++ docs/core/tools/dotnet-tool-install.md | 24 ++++++++-------- 4 files changed, 32 insertions(+), 23 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 4aeef9dd0abcf..482d5fe338c29 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -107,6 +107,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 | | [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 | | [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 | +| [`dotnet tool install --local` creates manifest by default](sdk/10.0/dotnet-tool-install-local-manifest.md) | Behavioral change | Preview 7 | | [project.json not supported in `dotnet restore`](sdk/10.0/dotnet-restore-project-json-unsupported.md) | Source incompatible | Preview 7 | | [SHA-1 fingerprint support deprecated in `dotnet nuget sign`](sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md) | Behavioral change | Preview 1 | | [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md index a2d382249f5e4..932ad0f708227 100644 --- a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md +++ b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md @@ -1,13 +1,15 @@ --- -title: "Breaking change: dotnet tool install --local creates manifest by default" -description: "Learn about the breaking change where dotnet tool install --local now creates a manifest by default using --create-manifest-if-needed behavior." -ms.date: 08/27/2024 +title: "Breaking change: 'dotnet tool install --local' creates manifest by default" +description: "Learn about the breaking change where 'dotnet tool install --local' now creates a manifest by default if no tools manifest is found." +ms.date: 08/27/2025 ai-usage: ai-generated --- # dotnet tool install --local creates manifest by default -When running `dotnet tool install --local`, a manifest is now created if one does not exist instead of failing with an error. This was implemented by making `--create-manifest-if-needed` enabled by default. +When running [`dotnet tool install --local`](../../../tools/dotnet-tool-install.md), a manifest is now created if none exists instead of failing with an error. This change was implemented by making the [`--create-manifest-if-needed` option](../../../tools/dotnet-tool-install.md#options) enabled by default. This is a breaking change, since users might have relied on the failure behavior to check if they needed to create a manifest. + +The `-d` flag on `dotnet tool install` was previously added to show a user the locations that were searched for manifests. This information was relayed in the error given when there was no manifest. That error is no longer shown since a manifest is now created if necessary. Also, the flag never worked properly. ## Version introduced @@ -15,15 +17,13 @@ When running `dotnet tool install --local`, a manifest is now created if one doe ## Previous behavior -When a user tried to install a .NET tool as a local tool in a folder that did not contain a manifest, they would get an error: "Cannot find a manifest file." +Previously, if you tried to install a .NET tool as a local tool in a folder that didn't contain a manifest, you got an error: -## New behavior +> Cannot find a manifest file. -The `--create-manifest-if-needed` functionality is now enabled by default, so the manifest will be created automatically if it does not exist when a tool is installed as a local tool. The manifest is created according to the following rules: +## New behavior -- Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory. -- If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory. -- If neither of the previous two steps finds a directory, create the manifest in the current working directory. +Starting in .NET 10, the `--create-manifest-if-needed=true` functionality is now enabled by default. When a tool is installed as a local tool, the manifest is created automatically if it doesn't exist. The manifest is created according to the rules defined under the [`--create-manifest-if-needed` option documentation](../../../tools/dotnet-tool-install.md#options). ## Type of breaking change @@ -35,8 +35,12 @@ This change improves the user experience by making `dotnet tool install --local` ## Recommended action -Users can turn off the automatic manifest creation behavior by setting `--create-manifest-if-needed=false` if they prefer the previous behavior where the command would fail when no manifest exists. +You can turn off the automatic manifest creation behavior by passing `--create-manifest-if-needed=false` when calling `dotnet tool install --local`. ## Affected APIs -N/A \ No newline at end of file +N/A + +## See also + +- [dotnet tool install](../../../tools/dotnet-tool-install.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 5e587e9139a61..d2e010e22c47a 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -120,6 +120,8 @@ items: href: sdk/10.0/default-workload-config.md - name: "`dotnet package list` performs restore" href: sdk/10.0/dotnet-package-list-restore.md + - name: "`dotnet tool install --local` creates manifest by default" + href: sdk/10.0/dotnet-tool-install-local-manifest.md - name: MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed href: sdk/10.0/custom-build-event-warning.md - name: MSBuild custom culture resource handling diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index b9b55963cee13..86050d7aa3f1a 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -1,7 +1,7 @@ --- title: dotnet tool install command description: The dotnet tool install command installs the specified .NET tool on your machine. -ms.date: 04/07/2025 +ms.date: 08/27/2025 --- # dotnet tool install @@ -46,9 +46,9 @@ dotnet tool install -h|--help The `dotnet tool install` command provides a way for you to install .NET tools on your machine. To use the command, you specify one of the following installation options: -* To install a global tool in the default location, use the `--global` option. -* 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. +- To install a global tool in the default location, use the `--global` option. +- 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. @@ -112,19 +112,21 @@ For more information, see [Install a local tool](global-tools.md#install-a-local - **`--create-manifest-if-needed`** - Applies to local tools. Available starting with .NET 8 SDK. Starting in .NET 10, this behavior is enabled by default. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file. + Available starting in .NET 8 SDK. - If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to false, the `CannotFindAManifestFile` error occurs. + Applies to local tools. To find a manifest, the search algorithm searches up the directory tree for `dotnet-tools.json` or a `.config` folder that contains a `dotnet-tools.json` file. - If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to true (or starting in .NET 10, when not specified), the tool creates a manifest automatically. It chooses a folder for the manifest as follows: + If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to `false`, the `CannotFindAManifestFile` error occurs. - * Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory. - * If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory. - * If neither of the previous two steps finds a directory, create the manifest in the current working directory. + If a tool-manifest can't be found and the `--create-manifest-if-needed` option is set to `true` (or, in .NET 10 and later versions, when not specified), the tool creates a manifest automatically. It chooses a folder for the manifest as follows: + + - Walk up the directory tree searching for a directory that has a `.git` subfolder. If one is found, create the manifest in that directory. + - If the previous step doesn't find a directory, walk up the directory tree searching for a directory that has a `.sln` or `.git` file. If one is found, create the manifest in that directory. + - If neither of the previous two steps finds a directory, create the manifest in the current working directory. 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 behavior is applied automatically if no tools manifest is found. Users can opt out by explicitly setting `--create-manifest-if-needed=false`. + Starting in .NET 10, a manifest is created automatically if no tools manifest is found. You can opt out by explicitly setting `--create-manifest-if-needed=false`. This change can be a [breaking change](../compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md). > [!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. From d7b346c9b2a30a98eca241ace639171f62edd1dd Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 27 Aug 2025 12:53:45 -0700 Subject: [PATCH 5/6] Update docs/core/tools/dotnet-tool-install.md --- docs/core/tools/dotnet-tool-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-tool-install.md b/docs/core/tools/dotnet-tool-install.md index 86050d7aa3f1a..3658389a36f0a 100644 --- a/docs/core/tools/dotnet-tool-install.md +++ b/docs/core/tools/dotnet-tool-install.md @@ -126,7 +126,7 @@ 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, a manifest is created automatically if no tools manifest is found. You can opt out by explicitly setting `--create-manifest-if-needed=false`. This change can be a [breaking change](../compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md). + Starting in .NET 10, a manifest is created automatically if no tools manifest is found. This change can be a [breaking change](../compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md). You can opt out by passing `--create-manifest-if-needed=false`. > [!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. From 72e429e8c283b0c9bb4385d33268af2a008c4abe Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 27 Aug 2025 12:58:34 -0700 Subject: [PATCH 6/6] tweaks --- .../sdk/10.0/dotnet-tool-install-local-manifest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md index 932ad0f708227..e4bdb22384e15 100644 --- a/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md +++ b/docs/core/compatibility/sdk/10.0/dotnet-tool-install-local-manifest.md @@ -9,7 +9,7 @@ ai-usage: ai-generated When running [`dotnet tool install --local`](../../../tools/dotnet-tool-install.md), a manifest is now created if none exists instead of failing with an error. This change was implemented by making the [`--create-manifest-if-needed` option](../../../tools/dotnet-tool-install.md#options) enabled by default. This is a breaking change, since users might have relied on the failure behavior to check if they needed to create a manifest. -The `-d` flag on `dotnet tool install` was previously added to show a user the locations that were searched for manifests. This information was relayed in the error given when there was no manifest. That error is no longer shown since a manifest is now created if necessary. Also, the flag never worked properly. +The `-d` flag on `dotnet tool install` was previously added to show the locations that were searched for manifests. This information was relayed in the error given when there was no manifest. That error is no longer shown since a manifest is now created if necessary. You should no longer use the `-d` flag. ## Version introduced @@ -23,7 +23,7 @@ Previously, if you tried to install a .NET tool as a local tool in a folder that ## New behavior -Starting in .NET 10, the `--create-manifest-if-needed=true` functionality is now enabled by default. When a tool is installed as a local tool, the manifest is created automatically if it doesn't exist. The manifest is created according to the rules defined under the [`--create-manifest-if-needed` option documentation](../../../tools/dotnet-tool-install.md#options). +Starting in .NET 10, the `--create-manifest-if-needed=true` functionality is now enabled by default. When a tool is installed as a local tool, the manifest is created automatically if it doesn't exist. The manifest is created according to the rules described in the [`--create-manifest-if-needed` option](../../../tools/dotnet-tool-install.md#options) documentation. ## Type of breaking change @@ -31,7 +31,7 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -This change improves the user experience by making `dotnet tool install --local` work by default without requiring users to manually create a manifest first. Previously, the concern was about creating a manifest in a working directory rather than the repository root, but the tool now tries to put the manifest in the repository root when possible. +This change improves the user experience by making `dotnet tool install --local` work by default without requiring users to manually create a manifest first. Previously, there was a concern about creating a manifest in a working directory rather than the repository root, but the tool now puts the manifest in the repository root when possible. ## Recommended action