dotnet-local-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

.NET Local Tools

.NET 本地工具

When to Use This Skill

何时使用该技能

Use this skill when:

Setting up consistent tooling across a development team
Ensuring CI/CD pipelines use the same tool versions as local development
Managing project-specific CLI tools (docfx, incrementalist, dotnet-ef, etc.)
Avoiding global tool version conflicts between projects

在以下场景使用该技能：

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

What Are Local Tools?

什么是本地工具？

Local tools are .NET CLI tools that are installed and versioned per-repository rather than globally. They're defined in

.config/dotnet-tools.json

and restored with

dotnet tool restore

本地工具是按仓库安装和版本控制的.NET CLI工具，而非全局安装。它们在

.config/dotnet-tools.json

中定义，可通过

dotnet tool restore

命令恢复。

Local vs Global Tools

本地工具 vs 全局工具

Aspect	Global Tools	Local Tools
Installation	`dotnet tool install -g`	`dotnet tool restore`
Scope	Machine-wide	Per-repository
Version control	Manual	In `.config/dotnet-tools.json`
CI/CD	Must install each tool	Single restore command
Conflicts	Can have version conflicts	Isolated per project

维度	全局工具	本地工具
安装方式	`dotnet tool install -g`	`dotnet tool restore`
作用范围	整机范围	单仓库范围
版本控制	手动管理	存储于 `.config/dotnet-tools.json`
CI/CD集成	需逐个安装工具	单条恢复命令即可
版本冲突	可能存在版本冲突	按项目隔离，无冲突

Setting Up Local Tools

搭建本地工具

Initialize the Manifest

初始化清单

bash

undefined

bash

undefined

Create .config/dotnet-tools.json

创建 .config/dotnet-tools.json

dotnet new tool-manifest


This creates:

.config/ └── dotnet-tools.json

undefined

dotnet new tool-manifest


该命令会生成如下目录结构：

.config/ └── dotnet-tools.json

undefined

Install Tools Locally

本地安装工具

bash

undefined

bash

undefined

Install a tool locally

本地安装工具

dotnet tool install docfx

Install specific version

安装指定版本

dotnet tool install docfx --version 2.78.3

Install from a specific source

从指定源安装工具

dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json

undefined

dotnet tool install MyTool --add-source https://mycompany.pkgs.visualstudio.com/_packaging/feed/nuget/v3/index.json

undefined

Restore Tools

恢复工具

bash

undefined

bash

undefined

Restore all tools from manifest

从清单恢复所有工具

dotnet tool restore

---

dotnet tool restore

---

dotnet-tools.json Format

dotnet-tools.json 格式

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
    }
  }
}

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
    }
  }
}

Fields

字段说明

Field	Description
`version`	Manifest schema version (always 1)
`isRoot`	Marks this as the root manifest (prevents searching parent directories)
`tools`	Dictionary of tool configurations
`tools.<name>.version`	Exact version to install
`tools.<name>.commands`	CLI commands the tool provides
`tools.<name>.rollForward`	Allow newer versions (usually false for reproducibility)

字段	描述
`version`	清单架构版本（固定为1）
`isRoot`	标记此清单为根清单（避免搜索父目录）
`tools`	工具配置字典
`tools.<name>.version`	要安装的精确版本
`tools.<name>.commands`	工具提供的CLI命令
`tools.<name>.rollForward`	是否允许使用更新版本（为了可复现构建，通常设为false）

Common Tools

常用工具

Documentation

文档生成

bash

undefined

bash

undefined

DocFX - API documentation generator

DocFX - API文档生成工具

dotnet tool install docfx


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

Usage:

bash

dotnet docfx docfx.json
dotnet docfx serve _site

dotnet tool install docfx


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

使用方式：

bash

dotnet docfx docfx.json
dotnet docfx serve _site

Entity Framework Core

bash

undefined

bash

undefined

EF Core CLI for migrations

EF Core CLI，用于数据库迁移

dotnet tool install dotnet-ef


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

Usage:

bash

dotnet ef migrations add InitialCreate
dotnet ef database update

dotnet tool install dotnet-ef


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

使用方式：

bash

dotnet ef migrations add InitialCreate
dotnet ef database update

Code Coverage

代码覆盖率

bash

undefined

bash

undefined

ReportGenerator for coverage reports

ReportGenerator，用于生成覆盖率报告

dotnet tool install dotnet-reportgenerator-globaltool


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

Usage:

bash

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

dotnet tool install dotnet-reportgenerator-globaltool


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

使用方式：

bash

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

Incremental Builds

增量构建

bash

undefined

bash

undefined

Incrementalist - build only changed projects

Incrementalist - 仅构建变更项目

dotnet tool install incrementalist.cmd


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

Usage:

bash

undefined

dotnet tool install incrementalist.cmd


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

使用方式：

bash

undefined

Get projects affected by changes since main branch

获取与main分支相比有变更的项目

incrementalist --branch main

undefined

incrementalist --branch main

undefined

Code Formatting

代码格式化

bash

undefined

bash

undefined

CSharpier - opinionated C# formatter

CSharpier - 风格固定的C#格式化工具

dotnet tool install csharpier


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

Usage:

bash

dotnet csharpier .
dotnet csharpier --check .  # CI mode - fails if changes needed

dotnet tool install csharpier


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

使用方式：

bash

dotnet csharpier .
dotnet csharpier --check .  # CI模式 - 若需要格式化则失败

Code Analysis

代码分析

bash

undefined

bash

undefined

JB dotnet-inspect (requires license)

JB dotnet-inspect（需要许可证）

dotnet tool install jb


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

dotnet tool install jb


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

CI/CD Integration

CI/CD 集成

GitHub Actions

yaml

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

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

      - name: Restore tools
        run: dotnet tool restore

      - name: Build
        run: dotnet build

      - name: Test with coverage
        run: dotnet test --collect:"XPlat Code Coverage"

      - name: Generate coverage report
        run: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport

      - name: Build documentation
        run: dotnet docfx docs/docfx.json

yaml

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

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

      - name: Restore tools
        run: dotnet tool restore

      - name: Build
        run: dotnet build

      - name: Test with coverage
        run: dotnet test --collect:"XPlat Code Coverage"

      - name: Generate coverage report
        run: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport

      - name: Build documentation
        run: dotnet docfx docs/docfx.json

Azure Pipelines

yaml

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

  - script: dotnet tool restore
    displayName: 'Restore .NET tools'

  - script: dotnet build -c Release
    displayName: 'Build'

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

  - script: dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:$(Build.ArtifactStagingDirectory)/coverage
    displayName: 'Generate coverage report'

yaml

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: '生成覆盖率报告'

Managing Tool Versions

管理工具版本

Update a Tool

更新工具

bash

undefined

bash

undefined

Update to latest version

更新到最新版本

dotnet tool update docfx

Update to specific version

更新到指定版本

dotnet tool update docfx --version 2.79.0

undefined

dotnet tool update docfx --version 2.79.0

undefined

List Installed Tools

列出已安装工具

bash

undefined

bash

undefined

List local tools

列出本地工具

dotnet tool list

List with outdated check

列出本地工具并检查是否有更新

dotnet tool list --outdated

undefined

dotnet tool list --outdated

undefined

Remove a Tool

卸载工具

bash

dotnet tool uninstall docfx

bash

dotnet tool uninstall docfx

Best Practices

最佳实践

1. Always Set

isRoot: true

1. 始终设置

isRoot: true

Prevents MSBuild from searching parent directories for tool manifests:

json

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

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

json

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

2. Pin Exact Versions

2. 固定精确版本

Use

"rollForward": false

for reproducible builds:

json

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

设置

"rollForward": false

以确保构建可复现：

json

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

3. Restore in CI Before Use

3. 在CI中先恢复再使用

Always run

dotnet tool restore

before using any local tool:

yaml

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

使用任何本地工具前，务必运行

dotnet tool restore

：

yaml

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

4. Document Tool Requirements

4. 记录工具要求

Add a comment or section in README:

markdown

undefined

在README中添加注释或章节：

markdown

undefined

Development Setup

开发环境搭建

Restore tools:
```
dotnet tool restore
```
Build:
```
dotnet build
```
Test:
```
dotnet test
```

undefined

恢复工具：
```
dotnet tool restore
```
构建项目：
```
dotnet build
```
运行测试：
```
dotnet test
```

undefined

5. Use Dependabot for Updates

5. 使用Dependabot自动更新

yaml

undefined

yaml

undefined

.github/dependabot.yml

version: 2 updates:

package-ecosystem: "nuget" directory: "/" schedule: interval: "weekly"
Includes local tools in .config/dotnet-tools.json

---

version: 2 updates:

package-ecosystem: "nuget" directory: "/" schedule: interval: "weekly"
包含.config/dotnet-tools.json中的本地工具

---

Troubleshooting

故障排除

Tool Not Found After Restore

恢复后找不到工具

Ensure you're running from the repository root:

bash

undefined

确保在仓库根目录运行命令：

bash

undefined

Wrong - running from subdirectory

错误示例 - 在子目录运行

cd src/MyApp dotnet docfx # Error: tool not found

cd src/MyApp dotnet docfx # 错误：找不到工具

Correct - run from solution root

正确示例 - 在解决方案根目录运行

cd ../.. dotnet docfx docs/docfx.json

undefined

cd ../.. dotnet docfx docs/docfx.json

undefined

Version Conflicts

版本冲突

If you see version conflicts, check for:

Global tool with different version:
```
dotnet tool list -g
```
Multiple tool manifests: Look for
```
.config/dotnet-tools.json
```
in parent directories

若遇到版本冲突，请检查：

是否存在版本不同的全局工具：
```
dotnet tool list -g
```
是否存在多个工具清单：检查父目录中是否有
```
.config/dotnet-tools.json
```

Clearing Tool Cache

清除工具缓存

bash

undefined

bash

undefined

Clear NuGet tool cache

清除NuGet工具缓存

dotnet nuget locals all --clear

Re-restore tools

重新恢复工具

dotnet tool restore

---

dotnet tool restore

---

Example: Complete Development Setup

示例：完整开发环境配置

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
    },
    "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
    }
  }
}

Development workflow:

bash

undefined

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
    },
    "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
    }
  }
}

开发工作流：

bash

undefined

Initial setup

初始环境搭建

dotnet tool restore

Format code before commit

提交前格式化代码

dotnet csharpier .

Run tests with coverage

运行测试并生成覆盖率报告

dotnet test --collect:"XPlat Code Coverage" dotnet reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage

Build documentation

构建文档

dotnet docfx docs/docfx.json

Check which projects changed (for large repos)

检查变更项目（适用于大型仓库）

incrementalist --branch main

undefined

incrementalist --branch main

undefined