dotnet-tool-management

dotnet-tool-management

面向使用者的 .NET CLI 工具管理：安装全局和本地工具、创建和维护 .config/dotnet-tools.json 清单、固定版本以确保团队使用一致、在 CI 流水线中运行 dotnet tool restore、更新和卸载工具，以及排查常见工具问题。

**版本假设：**基线为 .NET 8.0+。本地工具和工具清单从 .NET Core 3.0 起提供。特定 RID 的工具打包从 .NET 10 起提供。

**范围之外：**工具创作和打包（PackAsTool、NuGet 打包、ToolCommandName）——请参阅 [skill:dotnet-cli-packaging]。分发策略（AOT 与依赖框架的部署方式，或选择 dotnet tool）——请参阅 [skill:dotnet-cli-distribution]。发布 CI/CD 流水线——请参阅 [skill:dotnet-cli-release-pipeline]。

交叉引用：[skill:dotnet-cli-packaging]（工具创作和 NuGet 打包）、[skill:dotnet-cli-distribution]（分发策略和 RID 矩阵）、[skill:dotnet-cli-release-pipeline]（自动化发布工作流）、[skill:dotnet-project-analysis]（检测现有工具清单）。

---

全局工具安装

全局工具按用户安装，可从任何目录使用。工具二进制文件会添加到用户 PATH 中的某个目录。

# Install a global tool
dotnet tool install -g <package-id>

# Install a specific version
dotnet tool install -g <package-id> --version 1.2.3

# Install a pre-release version
dotnet tool install -g <package-id> --version "*-rc*"

# List installed global tools
dotnet tool list -g

# Update a global tool to the latest stable version
dotnet tool update -g <package-id>

# Uninstall a global tool
dotnet tool uninstall -g <package-id>

默认安装位置：

操作系统	路径
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

全局工具的作用范围是用户，而不是整台计算机。每个用户分别维护自己的工具安装。

自定义安装位置

使用 --tool-path 安装到自定义目录。该目录不会自动添加到 PATH 中——你必须自行管理 PATH：

dotnet tool install <package-id> --tool-path ~/my-tools

---

本地工具安装

本地工具的作用范围为某个目录树，并通过清单文件进行跟踪。不同目录可以使用同一工具的不同版本。

创建工具清单

清单文件 .config/dotnet-tools.json 用于跟踪本地工具版本。在仓库根目录创建该文件：

# Create the manifest (first time only, at repo root)
dotnet new tool-manifest

生成的内容如下：

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

将此文件提交到源代码管理中，以便所有团队成员使用相同的工具版本。

安装本地工具

省略 -g 标志即可在本地安装工具。工具会记录在最近的清单文件中：

# Install a local tool (recorded in .config/dotnet-tools.json)
dotnet tool install <package-id>

# Install a specific version
dotnet tool install <package-id> --version 2.0.1

# List local tools
dotnet tool list

# Update a local tool
dotnet tool update <package-id>

# Uninstall a local tool
dotnet tool uninstall <package-id>

安装两个工具后，清单内容如下：

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-ef": {
      "version": "9.0.3",
      "commands": [
        "dotnet-ef"
      ]
    },
    "nbgv": {
      "version": "3.7.112",
      "commands": [
        "nbgv"
      ]
    }
  }
}

运行本地工具

# Run a local tool (long form)
dotnet tool run <command-name>

# Run a local tool (short form, when command starts with dotnet-)
dotnet <command-name>

# Examples
dotnet tool run dotnet-ef migrations add Init
dotnet ef migrations add Init  # equivalent short form

---

版本固定和团队工作流

工具清单可确保团队使用可复现的工具版本。

固定版本策略

1. 一名团队成员创建清单，并安装指定版本的工具
2. 将 .config/dotnet-tools.json 提交到源代码管理中
3. 所有团队成员在克隆或拉取后运行 dotnet tool restore
4. 更新必须显式进行：由一人运行 dotnet tool update <package-id>，然后提交更新后的清单

版本范围

使用 --version 选项和 NuGet 版本范围，实现受控的灵活性：

# Exact version (strictest)
dotnet tool install <package-id> --version 2.0.1

# Allow patch updates (recommended for most tools)
dotnet tool install <package-id> --version "2.0.*"

# Pre-release versions
dotnet tool install <package-id> --version "*-preview*"

清单始终记录解析后的确切版本，确保所有团队成员还原后使用相同版本。

---

CI 集成

构建前还原工具

在 CI 流水线中，应在任何依赖这些工具的构建步骤之前还原工具。工具还原速度快，且具有幂等性。

GitHub Actions：

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '8.0.x'
  - name: Restore tools
    run: dotnet tool restore
  - name: Build
    run: dotnet build
  - name: Run EF migrations check
    run: dotnet ef migrations has-pending-changes

Azure DevOps Pipelines：

steps:
  - task: UseDotNet@2
    inputs:
      packageType: sdk
      version: '8.0.x'
  - script: dotnet tool restore
    displayName: 'Restore tools'
  - script: dotnet build
    displayName: 'Build'

CI 最佳实践

• 始终在构建前运行 dotnet tool restore——不要依赖 CI Agent 上预先安装的工具
• 提交 .config/dotnet-tools.json——该清单可确保 CI 使用与本地开发相同的工具版本
• 不要在 CI 中全局安装工具——使用本地工具清单确保可复现；全局安装可能会在并发作业之间产生冲突
• 缓存 NuGet 包以加快工具还原（Linux/macOS 上为 ~/.nuget/packages，Windows 上为 %USERPROFILE%\.nuget\packages）

---

特定 RID 的工具

从 .NET 10 开始，工具作者可以发布特定 RID、自包含或 Native AOT 版本的工具。对于使用者而言，这一过程是透明的——dotnet tool install 命令会自动为你的平台选择最佳软件包。

# RID selection is automatic -- no extra flags needed
dotnet tool install -g <package-id>

.NET CLI 会检测你的平台并下载相应的特定 RID 软件包。如果没有与平台匹配的特定 RID 软件包，CLI 会回退到依赖框架的软件包（前提是工具作者提供了该软件包）。

有关如何创作和打包特定 RID 的工具，请参阅 [skill:dotnet-cli-packaging]。

---

故障排除

常见问题

“工具已安装”——先卸载，或使用 dotnet tool update：

dotnet tool update -g <package-id>

“未找到清单文件”——运行 dotnet new tool-manifest 来创建清单，或确认你位于清单所在目录或其下级目录中。

“安装后未找到工具”——对于全局工具，请确认 ~/.dotnet/tools 位于 PATH 中。对于本地工具，请确保你位于包含清单的目录树中。

“CI 中的版本不匹配”——确认 .config/dotnet-tools.json 已提交，并且在使用任何工具之前运行了 dotnet tool restore。

---

全局工具与本地工具选择指南

方面	全局工具	本地工具
范围	系统级（按用户区分）	项目目录树内
安装位置	~/.dotnet/tools	.config/dotnet-tools.json 清单
版本管理	手动运行 dotnet tool update -g	在源代码管理中跟踪
CI/CD	使用前必须安装（不可复现）	dotnet tool restore 会还原所有工具（可复现）
团队一致性	每位开发者独立管理	清单可确保版本一致
适用场景	个人效率工具、一次性实用工具	特定项目的构建／开发工具

对于项目构建、测试或开发工作流中使用的任何工具，优先选择本地工具。 全局工具仅用于与特定项目无关的个人实用工具。

---

Agent 注意事项

1. 不要在 CI 中全局安装项目专用工具。 使用本地工具清单和 dotnet tool restore 来实现可复现的构建。全局安装可能会在并发 CI 作业之间产生冲突，也可能导致版本偏离团队固定的版本。
2. 不要在 CI 管道中跳过 dotnet tool restore。 CI Agent 上不会预先安装工具。在调用本地工具的任何步骤之前，都要先还原工具，否则构建会因“找不到工具”而失败。
3. 不要将 .config/dotnet-tools.json 排除在源代码管理之外。 清单是工具版本的唯一事实来源。没有它，dotnet tool restore 就没有内容可还原，而且每位开发者获得的版本也会不同。
4. 以使用者身份安装工具时，不要指定 RID 标志。 .NET CLI 会自动为你的平台选择正确的特定 RID 软件包。手动选择 RID 没有必要，还可能导致安装失败。
5. 不要混淆工具命令名称和软件包 ID。 软件包 ID（例如 dotnet-ef）可能与命令名称（例如 dotnet ef）不同。使用 dotnet tool list 查看软件包 ID 与命令之间的对应关系。

---

参考资料

• .NET 工具概述
• 如何管理 .NET 本地工具
• dotnet tool install 命令
• dotnet tool restore 命令
• 特定 RID 的 .NET 工具
• 排查 .NET 工具使用问题