【C#】.NET CLIの"dotnet tool restore"と".config/dotnet-tools.json"でローカルで使用するツールのバージョンを固定する(t4のバージョンをプロジェクトごとに固定したり)

はじめに

今回はdotnet tool restoreとdotnet-tools.jsonを用いて"現在のディレクトリとサブディレクトリ"で使用するツールのバージョンを固定する方法を紹介したいと思います。

↓ マニフェストファイル(.config/dotnet-tools.json)のサンプル

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-t4": {
      "version": "2.2.1",
      "commands": [
        "t4"
      ]
    }
  }
}

learn.microsoft.com

概要

.NET CLIのツール管理コマンドを利用することでNuGet パッケージからインストールされるコマンド プロンプトから呼び出されるコンソール アプリケーション(.NETツール)のインストール・アンインストール・更新・実行をすることができます。

今回は.NETツールの中でもインストール ディレクトリまたはそのいずれかのサブディレクトリから起動できるローカルツールに焦点を当てて紹介します。

例えばマニフェストファイル(dotnet-tools.json)を他の人と共有することによって、dotnet-t4などの利用するツールのバージョンをプロジェクト単位で合わせることができるのでとても便利です。

ツールは、NuGet パッケージからインストールされ、コマンド プロンプトから呼び出されるコンソール アプリケーションです。 ツールは自分で作成することも、サードパーティによって作成されたツールをインストールすることもできます。

.NET CLI | Microsoft Learn

ローカル ツールとして (.NET Core SDK 3.0 以降のバージョンに適用されます)。

ツールのバイナリは、既定のディレクトリにインストールされます。 ツールは、インストール ディレクトリまたはそのいずれかのサブディレクトリから起動できます。 ディレクトリごとに、同じツールの異なるバージョンを使用できます。
.NET CLI では、マニフェスト ファイルを使用して、ディレクトリにローカルとしてインストールされているツールを追跡します。 マニフェスト ファイルがソース コード リポジトリのルート ディレクトリに保存され、そのリポジトリを共同作成者がクローンし、.NET の CLI コマンドを 1 つ呼び出すと、マニフェスト ファイルに記載されているツールをすべてインストールできます。

learn.microsoft.com

マニフェストファイルの作成

ローカル アクセス専用のツール (現在のディレクトリとサブディレクトリ用) を利用するためにマニフェストファイル(.config/dotnet-tools.json)を生成する必要があります。

$ dotnet new tool-manifest
テンプレート "dotnet ローカル ツール マニフェスト ファイル" が正常に作成されました。

↓ 生成された.config/dotnet-tools.jsonのサンプル

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

インストールするパッケージ情報をマニフェストファイルに記載する

パッケージをインストールするときにはdotne tool install <パッケージ名>というコマンドを打ちます。するとインストールが開始されるとともに、dotnet-tools.jsonに書き込まれます。

$ dotnet tool install dotnet-t4     
NuGet パッケージ署名の認証をスキップしています。
次のコマンドを使用してこのディレクトリからツールを呼び出すことができます: 'dotnet tool run t4' または 'dotnet t4'。
ツール 'dotnet-t4' (バージョン '2.3.1') が正常にインストールされました。マニフェスト ファイル ----/.config/dotnet-tools.json にエントリが追加されました

↓ dotnet-t4の情報を追記された.config/dotnet-tools.jsonのサンプル

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-t4": {
      "version": "2.3.1",
      "commands": [
        "t4"
      ]
    }
  }
}

ちなみにバージョンを指定するときは--versionを追加します。

$  dotnet tool install dotnet-t4 --version 2.2.1
次のコマンドを使用してこのディレクトリからツールを呼び出すことができます: 'dotnet tool run t4' または 'dotnet t4'。
ツール 'dotnet-t4' (バージョン '2.2.1') が正常にインストールされました。マニフェスト ファイル ----/.config/dotnet-tools.json にエントリが追加されました。

↓ バージョンを指定した.config/dotnet-tools.jsonのサンプル

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-t4": {
      "version": "2.2.1",
      "commands": [
        "t4"
      ]
    }
  }
}

dotnet-tools.jsonに記載されているパッケージをインストールする

dotnet-tools.jsonに記載されているパッケージをインストールするには、dotnet tool restoreコマンドを実行します。

$  dotnet tool restore
ツール 'dotnet-t4' (バージョン '2.2.1') は復元されました。使用できるコマンド: t4

正常に復元されました。

ローカルツールを呼び出す

インストールディレクトリ内から以下のコマンドを実行します。

$ dotnet <コマンド名>

// dotnet-t4でのサンプル
$ dotnet t4 ./SampleProject/Hoge.tt -o ./SampleProject/Hoge.Generated.cs

おまけ(.NETツールの作成)

learn.microsoft.com