dotnet-tool-management

dotnet-tool-management

.NET CLI ツールを使用する側で管理するための内容です。グローバルツールとローカルツールのインストール、.config/dotnet-tools.json マニフェストの作成と管理、チーム内で再現性を確保するためのバージョン固定、CI パイプラインでの dotnet tool restore、ツールの更新とアンインストール、一般的なツールの問題のトラブルシューティングについて説明します。

バージョンの前提： .NET 8.0 以降を基準とします。ローカルツールとツールマニフェストは .NET Core 3.0 以降で利用できます。RID 固有のツールパッケージングは .NET 10 以降で利用できます。

対象外： ツールの作成とパッケージング（PackAsTool、NuGet パッケージング、ToolCommandName）については、[skill:dotnet-cli-packaging] を参照してください。配布戦略（AOT、フレームワーク依存、dotnet tool のいずれを選択するか）については、[skill:dotnet-cli-distribution] を参照してください。リリース CI/CD パイプラインについては、[skill:dotnet-cli-release-pipeline] を参照してください。

相互参照：[skill:dotnet-cli-packaging] はツールの作成と NuGet パッケージング、[skill:dotnet-cli-distribution] は配布戦略と RID マトリックス、[skill:dotnet-cli-release-pipeline] はリリースワークフローの自動化、[skill:dotnet-project-analysis] は既存のツールマニフェストの検出について説明しています。

---

グローバルツールのインストール

グローバルツールはユーザーごとにインストールされ、どのディレクトリからでも利用できます。ツールのバイナリは、ユーザーの PATH に含まれるディレクトリに追加されます。

# Install a global tool
dotnet tool install -g <package-id>

# Install a specific version
dotnet tool install -g <package-id> --version 1.2.3

# Install a pre-release version
dotnet tool install -g <package-id> --version "*-rc*"

# List installed global tools
dotnet tool list -g

# Update a global tool to the latest stable version
dotnet tool update -g <package-id>

# Uninstall a global tool
dotnet tool uninstall -g <package-id>

既定のインストール場所：

OS	パス
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

グローバルツールはユーザー単位で管理され、マシン全体では共有されません。各ユーザーがそれぞれ独立してツールをインストールします。

カスタムインストール場所

--tool-path を使うと、任意のディレクトリにインストールできます。このディレクトリは PATH に自動追加されないため、PATH は自分で管理する必要があります。

dotnet tool install <package-id> --tool-path ~/my-tools

---

ローカルツールのインストール

ローカルツールはディレクトリツリーに紐づき、マニフェストファイルで管理されます。ディレクトリごとに、同じツールの異なるバージョンを使用できます。

ツールマニフェストの作成

マニフェストファイル .config/dotnet-tools.json では、ローカルツールのバージョンを管理します。リポジトリのルートに作成します。

# Create the manifest (first time only, at repo root)
dotnet new tool-manifest

これにより、次のファイルが生成されます。

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

チームメンバー全員が同じツールバージョンを使用できるよう、このファイルをソース管理にコミットしてください。

ローカルツールのインストール

ツールをローカルにインストールするには、-g フラグを省略します。ツールは最も近いマニフェストファイルに記録されます。

# Install a local tool (recorded in .config/dotnet-tools.json)
dotnet tool install <package-id>

# Install a specific version
dotnet tool install <package-id> --version 2.0.1

# List local tools
dotnet tool list

# Update a local tool
dotnet tool update <package-id>

# Uninstall a local tool
dotnet tool uninstall <package-id>

ツールを 2 つインストールすると、マニフェストは次のようになります。

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-ef": {
      "version": "9.0.3",
      "commands": [
        "dotnet-ef"
      ]
    },
    "nbgv": {
      "version": "3.7.112",
      "commands": [
        "nbgv"
      ]
    }
  }
}

ローカルツールの実行

# Run a local tool (long form)
dotnet tool run <command-name>

# Run a local tool (short form, when command starts with dotnet-)
dotnet <command-name>

# Examples
dotnet tool run dotnet-ef migrations add Init
dotnet ef migrations add Init  # equivalent short form

---

バージョン固定とチームのワークフロー

ツールマニフェストを使うと、チーム全体で再現可能なツールバージョンを使用できます。

バージョン固定の戦略

1. チームメンバー 1 人が マニフェストを作成し、特定のバージョンを指定してツールをインストールします
2. .config/dotnet-tools.json をソース管理に コミット します
3. チームメンバー全員が クローンまたはプルの後に dotnet tool restore を実行します
4. 更新は明示的に行います。 1 人が dotnet tool update <package-id> を実行し、更新されたマニフェストをコミットします

バージョン範囲

--version オプションで NuGet のバージョン範囲を指定すると、柔軟性を適切に管理できます。

# Exact version (strictest)
dotnet tool install <package-id> --version 2.0.1

# Allow patch updates (recommended for most tools)
dotnet tool install <package-id> --version "2.0.*"

# Pre-release versions
dotnet tool install <package-id> --version "*-preview*"

マニフェストには解決済みの正確なバージョンが常に記録されるため、復元後はチームメンバー全員が同一のバージョンを使用できます。

---

CI との統合

ビルド前のツールの復元

CI パイプラインでは、ツールに依存するビルドステップより前にツールを復元します。ツールの復元は高速で、繰り返し実行しても安全です。

GitHub Actions：

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '8.0.x'
  - name: Restore tools
    run: dotnet tool restore
  - name: Build
    run: dotnet build
  - name: Run EF migrations check
    run: dotnet ef migrations has-pending-changes

Azure DevOps Pipelines：

steps:
  - task: UseDotNet@2
    inputs:
      packageType: sdk
      version: '8.0.x'
  - script: dotnet tool restore
    displayName: 'Restore tools'
  - script: dotnet build
    displayName: 'Build'

CI のベストプラクティス

• ビルド前に必ず dotnet tool restore を実行してください。 CI エージェントにツールが事前インストールされていることを前提にしないでください
• .config/dotnet-tools.json をコミットしてください。 マニフェストにより、CI でもローカル開発と同じツールバージョンが使用されます
• CI ではツールをグローバルにインストールしないでください。 再現性を確保するにはローカルツールマニフェストを使用してください。グローバルインストールは、同時実行されるジョブ間で競合する可能性があります
• NuGet パッケージをキャッシュして ツールの復元を高速化してください（Linux/macOS では ~/.nuget/packages、Windows では %USERPROFILE%\.nuget\packages）

RID 固有のツール

.NET 10 以降では、ツールの作成者は RID 固有のバージョン、自己完結型のバージョン、または Native AOT バージョンのツールを公開できます。利用者から見ると、この仕組みは透過的です。dotnet tool install コマンドが、プラットフォームに最適なパッケージを自動的に選択します。

# RID selection is automatic -- no extra flags needed
dotnet tool install -g <package-id>

.NET CLI はプラットフォームを検出し、適切な RID 固有パッケージをダウンロードします。プラットフォームに一致する RID 固有パッケージがない場合、CLI はフレームワーク依存パッケージにフォールバックします（ツールの作成者が用意している場合）。

RID 固有ツールの作成とパッケージ化について詳しくは、[skill:dotnet-cli-packaging] を参照してください。

---

トラブルシューティング

よくある問題

「ツールはすでにインストールされています」 — 先にアンインストールするか、dotnet tool update を使用してください。

dotnet tool update -g <package-id>

「マニフェストファイルが見つかりません」 — dotnet new tool-manifest を実行して作成するか、マニフェストの場所と同じディレクトリ、またはその配下のディレクトリにいることを確認してください。

「インストール後にツールが見つかりません」 — グローバルツールの場合は、~/.dotnet/tools が PATH に含まれていることを確認してください。ローカルツールの場合は、マニフェストを含むディレクトリツリー内にいることを確認してください。

「CI でバージョンが一致しません」 — .config/dotnet-tools.json がコミットされていることと、ツールを使用する前に dotnet tool restore が実行されることを確認してください。

---

グローバルツールとローカルツールの選択ガイド

項目	グローバルツール	ローカルツール
適用範囲	システム全体（ユーザーごと）	プロジェクトのディレクトリツリーごと
インストール場所	~/.dotnet/tools	.config/dotnet-tools.json マニフェスト
バージョン管理	手動で dotnet tool update -g	ソース管理で追跡
CI/CD	使用前にインストールが必要（再現性がありません）	dotnet tool restore ですべてを復元（再現可能）
チームでの一貫性	各開発者が個別に管理	マニフェストにより同じバージョンを使用
最適な用途	個人用の生産性向上ツール、一度限りのユーティリティ	プロジェクト固有のビルド／開発ツール

プロジェクトのビルド、テスト、開発ワークフローで使用するものには、ローカルツールを優先してください。グローバルツールは、特定のプロジェクトに結び付かない個人用ユーティリティに限定してください。

---

エージェントが注意すべき点

1. CI でプロジェクト固有のツールをグローバルにインストールしないでください。 再現可能なビルドにするには、ローカルツールマニフェストと dotnet tool restore を使用してください。グローバルインストールは、並行して実行される CI ジョブ間で競合したり、チームで固定したバージョンから逸脱したりする可能性があります。
2. CI パイプラインで dotnet tool restore を省略しないでください。 CI エージェントにはツールがあらかじめインストールされていません。ローカルツールを呼び出すステップの前に必ず復元してください。そうしないと、「ツールが見つかりません」というエラーでビルドが失敗します。
3. .config/dotnet-tools.json をソース管理から除外しないでください。 マニフェストはツールのバージョンに関する唯一の信頼できる情報源です。マニフェストがなければ、dotnet tool restore で復元するものがなく、開発者ごとに異なるバージョンが使われます。
4. 利用者としてツールをインストールする際に RID フラグを指定しないでください。 .NET CLI がプラットフォームに適した RID 固有パッケージを自動的に選択します。RID を手動で選択する必要はなく、インストールに失敗する原因になることもあります。
5. ツールのコマンド名とパッケージ ID を混同しないでください。 パッケージ ID（例：dotnet-ef）は、コマンド名（例：dotnet ef）と異なる場合があります。dotnet tool list を使用して、パッケージ ID とコマンドの対応を確認してください。

---

参考資料

• .NET ツールの概要
• .NET ローカルツールの管理方法
• dotnet tool install コマンド
• dotnet tool restore コマンド
• RID 固有の .NET ツール
• .NET ツールの使用に関する問題のトラブルシューティング