.NET ツールの管理方法

この記事の対象: ✔️ .NET Core 2.1 SDK 以降のバージョン。

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

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

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

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

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

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

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

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

ツールを検索する

ツールを見つける方法をいくつか紹介します。

• NuGet.org に発行されているツールを検索するには、dotnet tool search コマンドを使用します。
• ".NET ツール" パッケージの種類のフィルターを使用して NuGet の Web サイトを検索します。 詳細については、「パッケージの検索と選択」を参照してください。
• ASP.NET Core チームが作成したツールのソース コードについては、dotnet/aspnetcore GitHub リポジトリの Tools ディレクトリを参照してください。
• 診断ツールについては、.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 環境変数に自動的には追加しません。 tool-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 ツールを表示する場合は、--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- で始まる場合、ツールを呼び出すもう 1 つの方法は、dotnet コマンドを使用して、ツール コマンド プレフィックスを省略することです。 たとえば、コマンドが dotnet-doc の場合、次のコマンドを使ってツールを呼び出します。

dotnet doc

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

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

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

dotnet-doc

tool-path ツールを呼び出す

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 ローカル ツールをインストールして使用する