How does a .NET tool manifest (dotnet-tools.json) pin tool versions for a team, and how does dotnet tool restore use it in CI with the .NET 10 SDK?
answer
- dotnet new tool-manifest
- version, isRoot, tools, commands, rollForward
- search walks up from the current directory
- isRoot: true stops the search
- auto-created on local install since .NET 10
basics
~20 sA tool manifest is a dotnet-tools.json file, normally .config/dotnet-tools.json at the repository root, listing each local tool's package id, exact version and commands; dotnet tool restore installs exactly those versions, so CI and every developer run the same tools.
solid answer
~40 s`dotnet new tool-manifest` creates `.config/dotnet-tools.json` with `"version": 1`, `"isRoot": true` and an empty `tools` object. Each `dotnet tool install <id>` without `-g` adds an entry with the exact `version`, its `commands` and a `rollForward` flag. You commit the file; a fresh clone or a CI job runs `dotnet tool restore`, which downloads exactly those versions, then calls `dotnet ef` or `dotnet tool run <command>`. To find a tool, the SDK walks up from the current directory checking `.config/dotnet-tools.json` and `dotnet-tools.json` in each folder, and stops at a manifest marked `isRoot: true`. Since .NET 10, installing a local tool with no manifest in reach creates one automatically, preferring the folder that holds `.git`. Because the manifest decides what code runs, it belongs under code review.
code
json · 13 lines{
"version": 1,
"isRoot": true,
"tools": {
"dotnet-ef": {
"version": "10.0.12",
"commands": [
"dotnet-ef"
],
"rollForward": false
}
}
}go deeper
Recall that dotnet-tools.json lists a repository's local tools and that dotnet tool restore installs them after a clone.
Explain the manifest fields, the upward search with isRoot, and that restore installs exact versions, so CI and laptops run the same tool builds.
Show the operational discipline: commit and review the manifest, restore in every pipeline, bump versions deliberately, and know the .NET 10 auto-create behaviour and where it writes the file.
Treat tool manifests as part of the supply chain: decide which feeds tools may come from, who approves new entries, and how version bumps are rolled out across many repositories.
## The team problem A team repository needs the EF Core tool (`dotnet-ef`) to create migrations and a code-formatter tool that the pre-commit check runs. If each developer installs these globally, versions drift: one laptop generates migrations with an older `dotnet-ef`, another formats differently. A **tool manifest** fixes the versions in source control. ## Creating the manifest `dotnet new tool-manifest` writes `.config/dotnet-tools.json`: - `version`: the manifest schema version, `1`. - `isRoot`: `true` stops the upward search here (see below). - `tools`: one object per package id, each holding the exact `version`, the `commands` it provides and a `rollForward` boolean. Then `dotnet tool install dotnet-ef --version 10.0.12` (or, with the .NET 10 SDK, `dotnet tool install [email protected]`) adds the entry and installs it. Commit the file. With the **.NET 10 SDK** the first step is optional: a local install that finds no manifest **creates one**, because `--create-manifest-if-needed` now defaults to `true`. It picks the nearest ancestor folder that contains a `.git` folder, otherwise one with an `.sln`, `.slnx` or `.git` file, otherwise the current directory. In the 10.0.4xx source this auto-created file is written as `dotnet-tools.json` directly in that folder rather than under `.config`; both locations are found by the lookup. Pass `--create-manifest-if-needed=false` to get the old failure instead of a surprise file. ## How the SDK finds a tool When you type `dotnet ef`, the SDK searches **upward from the current directory**. In each folder it checks `.config/dotnet-tools.json` and then `dotnet-tools.json`. Manifests found on the way are combined, nearer entries winning, until one has `"isRoot": true`; the search stops there. That lets a sub-folder add tools on top of the repository's set, while `isRoot` keeps a manifest in some parent folder (your home directory, say) from leaking in. ## Restore in CI 1. Check out the repository. 2. Run `dotnet tool restore`. It reads the manifest and downloads each listed version from the configured NuGet feeds into the NuGet cache. No version resolution happens: the manifest's version is the version. 3. Run the tools: `dotnet ef migrations bundle ...`, `dotnet tool run <formatter-command> --check`. `dotnet tool restore` accepts `--configfile`, `--add-source` and `--tool-manifest <path>` for a manifest outside the search path. Feed credentials and source mapping belong to the NuGet configuration, not to the manifest. ## Changing a version `dotnet tool update dotnet-ef --version 10.0.12` rewrites the entry in the first manifest that lists the package, and the change goes through review like any other dependency bump. `dotnet tool list` shows the tools, versions and the manifest each came from. ## Why the manifest is security-sensitive `dotnet tool run` executes whatever package and version the manifest names, in full trust. A manifest edited by an untrusted party can make every developer and the CI agent run malicious code on the next restore. Keep it in a reviewed location, require review on changes to it, and restrict the feeds the repository restores from. ## Common mistakes - Committing a manifest but never running `dotnet tool restore` in the pipeline: the first `dotnet ef` call then fails on a clean agent with a message telling you to run `dotnet tool restore`. - Keeping two manifests, one under `.config` and one at the root, after the .NET 10 auto-create: both are read, and it becomes unclear which one a teammate should edit. Keep one and delete the other. - Pinning tools in a manifest while a CI step still calls a global install of the same tool by its bare command name, which bypasses the pin.
- What does isRoot: false allow, and why is true the usual choice?With `isRoot` false the SDK keeps searching parent folders after reading this manifest, so tools from a manifest higher up the tree also become available. Repositories normally set it to true so tools from outside the repository, such as a manifest in a home directory, never mix in.
- Does dotnet tool restore update tools to their latest versions?No. It installs exactly the versions written in the manifest. Moving to a newer version is an explicit `dotnet tool update` (or an edit to the file) that is reviewed and committed.
- How can a CI job use a manifest that is not above its working directory?Pass `--tool-manifest <path>` to `dotnet tool restore`, and the same option to install or update commands, so the SDK uses that file instead of searching upward.
- dotnet tool restore installs the newest version of each listed tool.
- Local tools are installed into the repository's bin folder.
- The manifest is a generated file, so it belongs in .gitignore.
- The SDK only looks for dotnet-tools.json in the current directory.
- With the .NET 10 SDK a local install fails unless dotnet new tool-manifest ran first.
Assumes the .NET 10 SDK; automatic manifest creation on a local install and the id@version argument form are new in .NET 10.