dotnet-local-tools
Managing local .NET tools with dotnet-tools.json for consistent tooling across development environments and CI/CD pipelines.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- dotnet-local-tools
- description
- Managing local .NET tools with dotnet-tools.json for consistent tooling across development environments and CI/CD pipelines.
03 SKILL.md 正文
.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 |
Allow newer versions (usually false for reproducibility) |
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.jsonin 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
04 同仓库更多 Skills
writing-tunit-tests
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.
dotnet-walls
Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.
csharp-15
Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.
verified-waves
Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.
harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
delegating-to-worker-models
Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.