.NET 本地工具使用指南：管理项目特定CLI工具，确保开发与CI/CD环境一致

dotnet-local-tools by aaronontheweb/dotnet-skills

148 周安装量

735 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aaronontheweb/dotnet-skills --skill dotnet-local-tools

.NET 命令行工具工程/构建系统

🇨🇳中文介绍

.NET 本地工具

何时使用此技能

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

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

什么是本地工具？

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

本地工具与全局工具对比

方面	全局工具	本地工具
安装方式	`dotnet tool install -g`	`dotnet tool restore`
作用范围	整个计算机

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

初始化清单文件

# 创建 .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
}

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

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'

# 更新到最新版本
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

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

全局工具版本不同：dotnet tool list -g
多个工具清单：在父目录中查找 .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

🇺🇸English

.NET Local Tools

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

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.

Local vs Global Tools

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

Setting Up Local Tools

Initialize the Manifest

# Create .config/dotnet-tools.json
dotnet new tool-manifest

This creates:

.config/
└── dotnet-tools.json

Install Tools Locally

# 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

Restore Tools

# Restore all tools from manifest
dotnet tool restore

dotnet-tools.json Format

{
  "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`

Common Tools

Documentation

# DocFX - API documentation generator
dotnet tool install docfx



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

Usage:

dotnet docfx docfx.json
dotnet docfx serve _site

Entity Framework Core

# EF Core CLI for migrations
dotnet tool install dotnet-ef



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

Usage:

dotnet ef migrations add InitialCreate
dotnet ef database update

Code Coverage

# ReportGenerator for coverage reports
dotnet tool install dotnet-reportgenerator-globaltool



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

Usage:

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

Incremental Builds

# Incrementalist - build only changed projects
dotnet tool install incrementalist.cmd



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

Usage:

# Get projects affected by changes since main branch
incrementalist --branch main

Code Formatting

# CSharpier - opinionated C# formatter
dotnet tool install csharpier



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

Usage:

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

Code Analysis

# JB dotnet-inspect (requires license)
dotnet tool install jb



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

CI/CD Integration

GitHub Actions

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

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'

Managing Tool Versions

Update a Tool

# Update to latest version
dotnet tool update docfx

# Update to specific version
dotnet tool update docfx --version 2.79.0

List Installed Tools

# List local tools
dotnet tool list

# List with outdated check
dotnet tool list --outdated

Remove a Tool

dotnet tool uninstall docfx

Best Practices

1. Always Set `isRoot: true`

Prevents MSBuild from searching parent directories for tool manifests:

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

2. Pin Exact Versions

Use "rollForward": false for reproducible builds:

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

3. Restore in CI Before Use

Always run dotnet tool restore before using any local tool:

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

4. Document Tool Requirements

Add a comment or section in README:

## Development Setup

1. Restore tools: `dotnet tool restore`
2. Build: `dotnet build`
3. Test: `dotnet test`

5. Use Dependabot for Updates

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    # Includes local tools in .config/dotnet-tools.json

Troubleshooting

Tool Not Found After Restore

Ensure you're running from the repository root:

# Wrong - running from subdirectory
cd src/MyApp
dotnet docfx  # Error: tool not found

# Correct - run from solution root
cd ../..
dotnet docfx docs/docfx.json

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

Clearing Tool Cache

# Clear NuGet tool cache
dotnet nuget locals all --clear

# Re-restore tools
dotnet tool restore

Example: Complete Development Setup

{
  "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:

# 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

Weekly Installs

Repository

aaronontheweb/d…t-skills

GitHub Stars

488

First Seen

Jan 29, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code65

codex62

opencode59

github-copilot58

gemini-cli55

kimi-cli53

Lark Skill Maker 教程：基于飞书CLI创建AI技能，自动化工作流与API调用指南

32,800 周安装

.NET 本地工具使用指南：管理项目特定CLI工具，确保开发与CI/CD环境一致

🇨🇳中文介绍

.NET 本地工具

何时使用此技能

什么是本地工具？

本地工具与全局工具对比

相关 Skills

设置本地工具

初始化清单文件

本地安装工具

恢复工具

dotnet-tools.json 格式

字段说明

常用工具

文档生成

Entity Framework Core

代码覆盖率

增量构建

代码格式化

代码分析

CI/CD 集成

GitHub Actions

Azure Pipelines

管理工具版本

更新工具

列出已安装的工具

移除工具

最佳实践

1. 始终设置 isRoot: true

2. 固定确切版本

3. 在 CI 中使用前先恢复

4. 记录工具要求

5. 使用 Dependabot 进行更新

故障排除

恢复后找不到工具

版本冲突

清除工具缓存

示例：完整的开发设置

🇺🇸English

.NET Local Tools

When to Use This Skill

What Are Local Tools?

Local vs Global Tools

Setting Up Local Tools

Initialize the Manifest

Install Tools Locally

Restore Tools

dotnet-tools.json Format

Fields

Common Tools

Documentation

Entity Framework Core

Code Coverage

Incremental Builds

Code Formatting

Code Analysis

CI/CD Integration

GitHub Actions

Azure Pipelines

Managing Tool Versions

Update a Tool

List Installed Tools

Remove a Tool

Best Practices

1. Always Set isRoot: true

2. Pin Exact Versions

3. Restore in CI Before Use

4. Document Tool Requirements

5. Use Dependabot for Updates

Troubleshooting

Tool Not Found After Restore

Version Conflicts

Clearing Tool Cache

Example: Complete Development Setup

最新 Skills

1. 始终设置 `isRoot: true`

1. Always Set `isRoot: true`