Document the `--create-manifest-if-needed` flag on `dotnet tool install`

[baronfel]

Type of issue

Before adding this feature, in .NET tools, when a user tries to install a .NET tool as a local tool, it requires the user to generate a manifest file through

> dotnet new tool-manifest

If the user tries to install a local .NET tool on a folder that does not contain the manifest, they get an error Cannot find a manifest file.

> dotnet tool install --local foo.tool --version 0.38.4

Cannot find a manifest file.
For a list of locations searched, specify the "-d" option before the tool name.
If you intended to install a global tool, add `--global` to the command.
If you would like to create a manifest, use `dotnet new tool-manifest`, usually in the repo root directory.

After that, if the user tries to update an existing local .NET tool on the folder that contain the corresponding manifest file, dotnet tool is able to update the existing manifest:

dotnet new tool-manifest
dotnet tool install --local foo.tool--version 1.0.0
dotnet tool update --local foo.tool

Tool 'foo.tool' was successfully updated from version '1.0.0' to version '2.0.0' (manifest file /Users/path/to/tool/.config/dotnet-tools.json).

---

To enhance user experience and make user's behavior more consistent, we implemented the following change.

Description

In dotnet/sdk#31231 we implemented a flag on dotnet tool install that would allow from-scratch tool installs to automatically create the required manifest file through --create-manifest-if-needed flag.

The manifest file and .config directory (final pattern: .config/dotnet-tools.json) will be created in the first directory that matches the following algorithm:

1. The first .git-directory-containing directory found from the dir the command was issued
2. The first .sln or .git-file-containing directory found from the dir the command was issued
3. Use the current working directory

Use Case

dotnet tool install --local foo.tool --create-manifest-if-needed

You can invoke the tool from this directory using the following commands: 'dotnet tool run dotnet-foo' or 'dotnet dotnet-foo'.
Tool 'foo.tool' (version '1.0.0') was successfully installed. Entry is added to the manifest file C:\Users\Path\To\the\Tool\.config\dotnet-tools.json.

Page URL

https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install

Content source URL

https://github.com/dotnet/docs/blob/main/docs/core/tools/dotnet-tool-install.md

Document Version Independent Id

80822879-4c2e-1c28-ae04-1adb5e7e8a99

Article author

@tdykstra

Metadata

• ID: 7df78c19-0c6f-fe28-213c-b51dd73398ef
• Service: dotnet-fundamentals

---

Associated WorkItem - 214648