.NET本地工具管理Skill dotnet-local-tools

---

name: dotnet-local-tools description: 通过 dotnet-tools.json 管理本地 .NET 工具，确保开发环境和 CI/CD 流水线中的工具一致性。 invocable: false

.NET 本地工具

何时使用此技能

在以下情况下使用此技能：

• 为开发团队设置一致的工具环境
• 确保 CI/CD 流水线使用与本地开发相同的工具版本
• 管理项目特定的 CLI 工具（如 docfx、incrementalist、dotnet-ef 等）
• 避免项目间的全局工具版本冲突

什么是本地工具？

本地工具是按仓库安装和版本控制的 .NET CLI 工具，而非全局安装。它们在 .config/dotnet-tools.json 中定义，并通过 dotnet tool restore 命令恢复。

本地工具与全局工具对比

方面	全局工具	本地工具
安装方式	dotnet tool install -g	dotnet tool restore
作用范围	整个机器	每个仓库
版本控制	手动	在 .config/dotnet-tools.json 中
CI/CD	必须安装每个工具	单个恢复命令
冲突	可能存在版本冲突	按项目隔离

---

设置本地工具

初始化清单

# 创建 .config/dotnet-tools.json
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": true,
  "tools": {
    "docfx": {
      "version": "2.78.3",
      "commands": [
        "docfx"
      ],
      "rollForward": false
    },
    "dotnet-ef": {
      "version": "9.0.0",
      "commands": [
        "dotnet-ef"
      ],
      "rollForward": false
    },
    "incrementalist.cmd": {
      "version": "1.2.0",
      "commands": [
        "incrementalist"
      ],
      "rollForward": false
    },
    "dotnet-reportgenerator-globaltool": {
      "version": "5.4.1",
      "commands": [
        "reportgenerator"
      ],
      "rollForward": false
    }
  }
}

字段说明

字段	描述
version	清单模式版本（始终为 1）
isRoot	标记此清单为根清单（防止搜索父目录）
tools	工具配置字典
tools.<name>.version	要安装的确切版本
tools.<name>.commands	工具提供的 CLI 命令
tools.<name>.rollForward	允许使用更新的版本（通常为 false 以确保可重现性）

---

常用工具

文档生成

# DocFX - API 文档生成器
dotnet tool install docfx

"docfx": {
  "version": "2.78.3",
  "commands": ["docfx"],
  "rollForward": false
}

用法：

dotnet docfx docfx.json
dotnet docfx serve _site

Entity Framework Core

# 用于迁移的 EF Core CLI
dotnet tool install dotnet-ef

"dotnet-ef": {
  "version": "9.0.0",
  "commands": ["dotnet-ef"],
  "rollForward": false
}

用法：

dotnet ef migrations add InitialCreate
dotnet ef database update

代码覆盖率

# 用于覆盖率报告的 ReportGenerator
dotnet tool install dotnet-reportgenerator-globaltool

"dotnet-reportgenerator-globaltool": {
  "version": "5.4.1",
  "commands": ["reportgenerator"],
  "rollForward": false
}

用法：

dotnet reportgenerator -reports:coverage.cobertura.xml -targetdir:coveragereport -reporttypes:Html

增量构建

# Incrementalist - 仅构建更改的项目
dotnet tool install incrementalist.cmd

"incrementalist.cmd": {
  "version": "1.2.0",
  "commands": ["incrementalist"],
  "rollForward": false
}

用法：

# 获取自 main 分支以来受更改影响的项目
incrementalist --branch main

代码格式化

# CSharpier - 有主见的 C# 格式化工具
dotnet tool install csharpier

"csharpier": {
  "version": "0.30.3",
  "commands": ["dotnet-csharpier"],
  "rollForward": false
}

用法：

dotnet csharpier .
dotnet csharpier --check .  # CI 模式 - 如果需要更改则失败

代码分析

# JB dotnet-inspect（需要许可证）
dotnet tool install jb

"jb": {
  "version": "2024.3.4",
  "commands": ["jb"],
  "rollForward": false
}

---

CI/CD 集成

GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 设置 .NET
        uses: actions/setup-dotnet@v4
        with:
          global-json-file: global.json

      - name: 恢复工具
        run: dotnet tool restore

      - name: 构建
        run: dotnet build

      - name: 带覆盖率的测试
        run: dotnet test --collect:"XPlat Code Coverage"

      - name: 生成覆盖率报告
        run: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport

      - name: 构建文档
        run: dotnet docfx docs/docfx.json

Azure Pipelines

steps:
  - task: UseDotNet@2
    inputs:
      useGlobalJson: true

  - script: dotnet tool restore
    displayName: '恢复 .NET 工具'

  - script: dotnet build -c Release
    displayName: '构建'

  - script: dotnet test -c Release --collect:"XPlat Code Coverage"
    displayName: '测试'

  - script: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:$(Build.ArtifactStagingDirectory)/coverage
    displayName: '生成覆盖率报告'

---

管理工具版本

更新工具

# 更新到最新版本
dotnet tool update docfx

# 更新到特定版本
dotnet tool update docfx --version 2.79.0

列出已安装的工具

# 列出本地工具
dotnet tool list

# 列出并检查过时工具
dotnet tool list --outdated

移除工具

dotnet tool uninstall docfx

---

最佳实践

1. 始终设置 isRoot: true

防止 MSBuild 在父目录中搜索工具清单：

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

2. 固定确切版本

使用 "rollForward": false 以确保可重现的构建：

"docfx": {
  "version": "2.78.3",
  "rollForward": false
}

3. 在 CI 中使用前先恢复

在使用任何本地工具之前，始终运行 dotnet tool restore：

- run: dotnet tool restore
- run: dotnet docfx docs/docfx.json

4. 记录工具要求

在 README 中添加注释或部分：

## 开发设置

1. 恢复工具：`dotnet tool restore`
2. 构建：`dotnet build`
3. 测试：`dotnet test`

5. 使用 Dependabot 进行更新

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    # 包括 .config/dotnet-tools.json 中的本地工具

---

故障排除

恢复后找不到工具

确保从仓库根目录运行：

# 错误 - 从子目录运行
cd src/MyApp
dotnet docfx  # 错误：找不到工具

# 正确 - 从解决方案根目录运行
cd ../..
dotnet docfx docs/docfx.json

版本冲突

如果看到版本冲突，请检查：

1. 具有不同版本的全局工具：dotnet tool list -g
2. 多个工具清单：查找父目录中的 .config/dotnet-tools.json

清除工具缓存

# 清除 NuGet 工具缓存
dotnet nuget locals all --clear

# 重新恢复工具
dotnet tool restore

---

示例：完整的开发设置

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "docfx": {
      "version": "2.78.3",
      "commands": ["docfx"],
      "rollForward": false
    },
    "dotnet-ef": {
      "version": "9.0.0",
      "commands": ["dotnet-ef"],
      "rollForward": false
    },
    "dotnet-reportgenerator-globaltool": {
      "version": "5.4.1",
      "commands": ["reportgenerator"],
      "rollForward": false
    },
    "csharpier": {
      "version": "0.30.3",
      "commands": ["dotnet-csharpier"],
      "rollForward": false
    },
    "incrementalist.cmd": {
      "version": "1.2.0",
      "commands": ["incrementalist"],
      "rollForward": false
    }
  }
}

开发工作流：

# 初始设置
dotnet tool restore

# 提交前格式化代码
dotnet csharpier .

# 运行带覆盖率的测试
dotnet test --collect:"XPlat Code Coverage"
dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage

# 构建文档
dotnet docfx docs/docfx.json

# 检查哪些项目发生了更改（适用于大型仓库）
incrementalist --branch main