dotnet-local-tools

.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	各ツールをインストールする必要あり	単一の restore コマンド
競合	バージョン競合の可能性あり	プロジェクトごとに分離

---

ローカルツールの設定

マニフェストの初期化

# .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: 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'

---

ツールバージョンの管理

ツールの更新

# 最新バージョンに更新
 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