.NET ツールを管理する方法

この記事は、 ✔️.NET Core 2.1 SDK 以降のバージョンに適用されます。

.NET ツールは、コンソール アプリケーションを含む特別な NuGet パッケージです。 次の方法で、コンピューターにツールをインストールできます。

• グローバル ツールとして。

  ツール バイナリは、PATH 環境変数に追加された既定のディレクトリにインストールされます。 場所を指定せずに、コンピューター上の任意のディレクトリからツールを呼び出すことができます。 1 つのバージョンのツールが、コンピューター上のすべてのディレクトリに使用されます。

• カスタムの場所のグローバル ツール (ツール パス ツールとも呼ばれます)。

  ツール バイナリは、指定した場所にインストールされます。 インストール ディレクトリからツールを呼び出すには、コマンド名でディレクトリを指定するか、PATH 環境変数にディレクトリを追加します。 1 つのバージョンのツールが、コンピューター上のすべてのディレクトリに使用されます。

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

  ツール バイナリは既定のディレクトリにインストールされます。 このツールは、インストール ディレクトリまたはそのサブディレクトリから呼び出すことができます。 異なるディレクトリで、同じツールの異なるバージョンを使用できます。

  .NET CLI では、マニフェスト ファイルを使用して、ディレクトリにローカルとしてインストールされているツールを追跡します。 マニフェスト ファイルがソース コード リポジトリのルート ディレクトリに保存されている場合、共同作成者はリポジトリを複製し、1 つの .NET CLI コマンドを呼び出して、マニフェスト ファイルに一覧表示されているすべてのツールをインストールできます。

ツールを検索する

ツールを見つける方法を次に示します。

• dotnet ツールの検索コマンドを使用して、NuGet.org に発行されたツールを見つけます。
• NuGet Web サイトを検索するには、".NET ツール" パッケージの種類フィルターを使用します。 詳細については、「パッケージの検索と選択」を参照してください。
• dotnet/aspnetcore GitHub リポジトリの Tools ディレクトリに作成された ASP.NET Core チームのツールのソース コードを参照してください。
• .NET 診断ツールの診断ツールについて説明します。

作成者と統計を確認する

.NET ツールは完全信頼で実行され、グローバル ツールは PATH 環境変数に追加されるため、強力です。 信頼できないユーザーからツールをダウンロードしないでください。

ツールが NuGet でホストされている場合は、ツールを検索して作成者と統計を確認できます。

グローバル ツールをインストールする

ツールをグローバル ツールとしてインストールするには、次の例に示すように、dotnet tool install の -g または --global オプションを使用します。

dotnet tool install -g dotnetsay

出力には、次の例のように、ツールの呼び出しに使用されたコマンドと、インストールされているバージョンが表示されます。

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

ツールのバイナリの既定の場所は、オペレーティング システムによって異なります。

この場所は、SDK が最初に実行されるときにユーザーのパスに追加されます。 したがって、グローバル ツールは、ツールの場所を指定せずに、任意のディレクトリから呼び出すことができます。

ツールへのアクセスは、マシン全体ではなくユーザー固有です。 グローバル ツールは、そのツールをインストールしたユーザーのみが使用できます。

カスタムの場所にグローバル ツールをインストールする

ツールをグローバル ツールとしてカスタムの場所にインストールするには、次の例に示すように、dotnet tool install の --tool-path オプションを使用します。

Windows の場合:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

Linux または macOS の場合:

dotnet tool install dotnetsay --tool-path ~/bin

.NET SDK は、PATH 環境変数にこの場所を自動的に追加しません。 ツール パス ツールを呼び出すには、次のいずれかの方法を使用してコマンドを使用できることを確認する必要があります。

• インストール ディレクトリを PATH 環境変数に追加します。
• ツールを呼び出すときに、ツールへの完全なパスを指定します。
• インストール ディレクトリ内からツールを呼び出します。

ローカル ツールをインストールする

.NET Core 3.0 SDK 以降に適用されます。

ローカル アクセス専用のツール (現在のディレクトリとサブディレクトリ用) をインストールする場合は、ツール マニフェスト ファイルにツールを追加する必要があります。 ツール マニフェスト ファイルを作成するには、 dotnet new tool-manifest コマンドを実行します。

dotnet new tool-manifest

このコマンドは、.configディレクトリの下にdotnet-tools.json という名前のマニフェスト ファイルを作成します。 マニフェスト ファイルにローカル ツールを追加するには、dotnet tool install コマンドを使用し、次の例に示すように、--globalオプションと--tool-path オプションを省略します。

dotnet tool install dotnetsay

コマンド出力には、次の例のように、新しくインストールされたツールが存在するマニフェスト ファイルが表示されます。

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

次の例は、2 つのローカル ツールがインストールされたマニフェスト ファイルを示しています。

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

通常は、リポジトリのルート ディレクトリにローカル ツールを追加します。 マニフェスト ファイルをリポジトリにチェックインすると、リポジトリからコードをチェックアウトした開発者は最新のマニフェスト ファイルを取得します。 マニフェスト ファイルに一覧表示されているすべてのツールをインストールするには、 dotnet tool restore コマンドを実行します。

dotnet tool restore

出力は、復元されたツールを示します。

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

特定のツール バージョンをインストールする

プレリリース バージョンまたは特定のバージョンのツールをインストールするには、次の例に示すように、 --version オプションを使用してバージョン番号を指定します。

dotnet tool install dotnetsay --version 2.1.3

正確なバージョン番号を指定せずにツールのプレリリース バージョンをインストールするには、次の例に示すように、 --version オプションを使用し、ワイルドカードを指定します。

dotnet tool install --global dotnetsay --version "*-rc*"

ツールを使用する

ツールの呼び出しに使用するコマンドは、インストールするパッケージの名前とは異なる場合があります。 現在のユーザーのコンピューターに現在インストールされているすべてのツールを表示するには、 dotnet tool list コマンドを使用します。

dotnet tool list

出力には、次の例のように、各ツールのバージョンとコマンドが表示されます。

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

前の例に示すように、一覧にはローカル ツールが表示されます。 グローバル ツールを表示するには、 --global オプションを使用します。 ツール パス ツールを表示するには、 --tool-path オプションを使用します。

特定のツールを一覧表示するには、 dotnet tool list <PACKAGE_ID> コマンドを使用します。

dotnet tool list dotnetsay

次の例のように、ツールがインストールされている場合にのみ、出力にそのツールが一覧表示されます。

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

グローバル ツールを呼び出す

グローバル ツールの場合は、ツール コマンドを単独で使用します。 たとえば、コマンドが dotnetsay または dotnet-docの場合は、グローバル ツールを呼び出すために使用します。

dotnetsay
dotnet-doc

コマンドがプレフィックス dotnet-で始まる場合、ツールを呼び出す別の方法は、 dotnet コマンドを使用し、ツール コマンド プレフィックスを省略することです。 たとえば、コマンドが dotnet-docされている場合、次のコマンドによってツールが呼び出されます。

dotnet doc

ただし、次のシナリオでは、 dotnet コマンドを使用してグローバル ツールを呼び出すことはできません。

• グローバル ツールとローカル ツールには、同じコマンドの前に dotnet- が付いています。
• ローカル ツールのスコープ内にあるディレクトリからグローバル ツールを呼び出す必要があります。

このシナリオでは、ローカル ツールを dotnet doc して dotnet dotnet-doc 呼び出します。 グローバル ツールを呼び出すには、コマンドを単独で使用します。

dotnet-doc

ツール パス ツールを呼び出す

tool-path オプションを使用してインストールされたグローバル ツールを呼び出すには、この記事で前述したようにコマンドを使用できることを確認します。

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

ローカル ツールを呼び出すには、インストール ディレクトリ内から dotnet コマンドを使用する必要があります。 次の例に示すように、長い形式 (dotnet tool run <COMMAND_NAME>) または短い形式 (dotnet <COMMAND_NAME>) を使用できます。

dotnet tool run dotnetsay
dotnet dotnetsay

コマンドの前に dotnet- が付いている場合は、ツールを呼び出すときにプレフィックスを含めたり省略したりできます。 たとえば、コマンドが dotnet-docされている場合、次のいずれかの例でローカル ツールが呼び出されます。

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

ツールを更新する

ツールを更新するには、最新の安定バージョンでアンインストールして再インストールする必要があります。 ツールを更新するには、ツールのインストールに使用したのと同じオプションで dotnet tool update コマンドを使用します。

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

ローカル ツールの場合、SDK は現在のディレクトリと親ディレクトリを検索して、パッケージ ID を含む最初のマニフェスト ファイルを検索します。 マニフェスト ファイルにそのようなパッケージ ID がない場合、SDK は最も近いマニフェスト ファイルに新しいエントリを追加します。

ツールをアンインストールする

ツールのインストールに使用したのと同じオプションを使用して 、dotnet tool uninstall コマンドを使用してツールをアンインストールします。

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

ローカル ツールの場合、SDK は現在のディレクトリと親ディレクトリを検索して、パッケージ ID を含む最初のマニフェスト ファイルを検索します。

ヘルプとトラブルシューティングを行う

ツールのインストールまたは実行に失敗した場合は、「 .NET ツールの使用に関する問題のトラブルシューティング」を参照してください。 --help パラメーターを使用して、使用可能なdotnet toolコマンドとパラメーターの一覧を取得できます。

dotnet tool --help

ツールの使用方法を取得するには、次のいずれかのコマンドを入力するか、ツールの Web サイトを参照してください。

<command> --help
dotnet <command> --help

こちらも参照ください

• チュートリアル: .NET CLI を使用して .NET ツールを作成する
• チュートリアル: .NET CLI を使って .NET グローバル ツールをインストールして使用する
• チュートリアル: .NET CLI を使って .NET ローカル ツールをインストールして使用する