用途
本技能用于在 .NET 项目中管理本地工具（Local Tools）。本地工具是按仓库而非全局安装和版本化的 .NET CLI 工具，定义在 .config/dotnet-tools.json 中，通过 dotnet tool restore 还原。适用于：为开发团队建立一致的工具链；确保 CI/CD 流水线使用与本地开发相同的工具版本；管理项目专属 CLI 工具（如 docfx、incrementalist、dotnet-ef 等）；避免不同项目之间的全局工具版本冲突。
本地工具与全局工具对比
- 安装方式：全局工具使用 dotnet tool install -g，本地工具使用 dotnet tool restore。
- 作用范围：全局工具作用于整台机器，本地工具按仓库隔离。
- 版本控制：全局工具需手动管理，本地工具记录在 .config/dotnet-tools.json 中。
- CI/CD：全局工具需逐个安装，本地工具只需一条还原命令。
- 冲突：全局工具可能产生版本冲突，本地工具按项目隔离。
主要能力
初始化清单
执行 dotnet new tool-manifest 创建 .config/dotnet-tools.json。
本地安装工具
- 安装工具：
dotnet tool install docfx - 安装指定版本：
dotnet tool install docfx --version 2.78.3 - 从指定源安装：
dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json
还原工具
dotnet tool restore 会从清单还原全部工具。
dotnet-tools.json 格式
清单包含 version（架构版本，固定为 1）、isRoot（标记为根清单，阻止向上级目录搜索）、tools（工具配置字典）。每个工具包含 version（精确安装版本）、commands（工具提供的 CLI 命令）、rollForward（是否允许更新版本，为保证可复现通常为 false）。
常用工具
- DocFX（API 文档生成）：
dotnet tool install docfx，用法dotnet docfx docfx.json、dotnet docfx serve _site。 - EF Core CLI（迁移）：
dotnet tool install dotnet-ef，用法dotnet ef migrations add InitialCreate、dotnet ef database update。 - ReportGenerator（覆盖率报告）：
dotnet tool install dotnet-reportgenerator-globaltool，用法dotnet reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport -reporttypes:Html。 - Incrementalist（增量构建，只构建变更项目）：
dotnet tool install incrementalist.cmd，用法incrementalist --branch main。 - CSharpier（C# 格式化）：
dotnet tool install csharpier，用法dotnet csharpier .、dotnet csharpier --check .（CI 模式，需要修改时失败）。 - JB dotnet-inspect（代码分析，需要许可证）：
dotnet tool install jb。
使用方式
CI/CD 集成
GitHub Actions 示例：检出代码后使用 actions/setup-dotnet@v4 并指定 global-json-file，然后依次执行 dotnet tool restore、dotnet build、dotnet test --collect:"XPlat Code Coverage"、dotnet reportgenerator ...、dotnet docfx docs/docfx.json。
Azure Pipelines 示例：使用 UseDotNet@2 任务并设置 useGlobalJson: true，然后执行 dotnet tool restore、dotnet build -c Release、dotnet test -c Release --collect:"XPlat Code Coverage"、dotnet reportgenerator ...。
版本管理
- 更新工具：
dotnet tool update docfx，或指定版本dotnet tool update docfx --version 2.79.0。 - 列出已安装工具：
dotnet tool list，检查过期：dotnet tool list --outdated。 - 移除工具：
dotnet tool uninstall docfx。
最佳实践
- 始终设置 isRoot: true，防止 MSBuild 向上级目录搜索工具清单。
- 固定精确版本，使用 "rollForward": false 保证可复现构建。
- 在 CI 中使用前先执行 dotnet tool restore。
- 在 README 中记录工具要求（还原、构建、测试步骤）。
- 使用 Dependabot 更新，配置 package-ecosystem 为 nuget，可包含 .config/dotnet-tools.json 中的本地工具。
限制与排查
- 还原后找不到工具：需从仓库根目录运行，子目录运行会报错。
- 版本冲突：检查是否存在不同版本的全局工具（dotnet tool list -g），或上级目录存在多个工具清单。
- 清理工具缓存：
dotnet nuget locals all --clear后重新dotnet tool restore。
完整示例
清单可同时包含 docfx、dotnet-ef、dotnet-reportgenerator-globaltool、csharpier、incrementalist.cmd 等工具，各自固定版本并设置 rollForward: false。典型开发流程为：初始设置执行 dotnet tool restore；提交前用 dotnet csharpier . 格式化；运行测试并生成覆盖率报告；构建文档；对大型仓库用 incrementalist --branch main 检查变更项目。