.NET Core ツールの管理方法How to manage .NET Core tools

この記事の対象: ✔️ .NET Core 2.1 SDK 以降のバージョンThis article applies to: ✔️ .NET Core 2.1 SDK and later versions

.NET Core ツールは、コンソール アプリケーションを含む特殊な NuGet パッケージです。A .NET Core tool is a special NuGet package that contains a console application. ツールは、次の方法でコンピューターにインストールできます。A tool can be installed on your machine in the following ways:

  • グローバル ツールとして。As a global tool.

    ツールのバイナリは、PATH 環境変数に追加された既定のディレクトリにインストールされます。The tool binaries are installed in a default directory that is added to the PATH environment variable. その場所を指定しなくても、マシン上の任意のディレクトリからツールを呼び出すことができます。You can invoke the tool from any directory on the machine without specifying its location. 1 つのバージョンのツールがマシン上のすべてのディレクトリに使用されます。One version of a tool is used for all directories on the machine.

  • カスタムの場所のグローバル ツールとして (tool-path ツールとも呼ばれます)。As a global tool in a custom location (also known as a tool-path tool).

    ツールのバイナリは、指定した場所にインストールされます。The tool binaries are installed in a location that you specify. ツールを呼び出すには、インストール ディレクトリから実行するか、コマンド名と共にディレクトリを指定するか、ディレクトリを PATH 環境変数に追加します。You can invoke the tool from the installation directory or by providing the directory with the command name or by adding the directory to the PATH environment variable. 1 つのバージョンのツールがマシン上のすべてのディレクトリに使用されます。One version of a tool is used for all directories on the machine.

  • ローカル ツールとして (.NET Core SDK 3.0 以降に適用されます)。As a local tool (applies to .NET Core SDK 3.0 and later).

    ツールのバイナリは、既定のディレクトリにインストールされます。The tool binaries are installed in a default directory. ツールは、インストール ディレクトリまたはそのいずれかのサブディレクトリから起動します。You invoke the tool from the installation directory or any of its subdirectories. ディレクトリごとに、同じツールの異なるバージョンを使用できます。Different directories can use different versions of the same tool.

    .NET CLI では、マニフェスト ファイルを使用して、ディレクトリにローカルとしてインストールされているツールを追跡します。The .NET CLI uses manifest files to keep track of which tools are installed as local to a directory. マニフェスト ファイルがソース コード リポジトリのルート ディレクトリに保存されると、共同作成者は、リポジトリを複製し、1 つの .NET Core CLI コマンドを呼び出して、マニフェスト ファイルに一覧表示されているすべてのツールがインストールすることができます。When the manifest file is saved in the root directory of a source code repository, a contributor can clone the repository and invoke a single .NET Core CLI command that installs all of the tools listed in the manifest files.

重要

.NET Core ツールは完全な信頼で実行されます。.NET Core tools run in full trust. 作成者を信頼していない場合は、その .NET Core ツールをインストールしないでください。Do not install a .NET Core tool unless you trust the author.

ツールを検索するFind a tool

現在、.NET Core にはツールの検索機能がありません。Currently, .NET Core doesn't have a tool search feature. ツールを見つける方法をいくつか紹介します。Here are some ways to find tools:

作成者と統計情報の確認Check the author and statistics

.NET Core ツールは完全な信頼で実行され、グローバル ツールが PATH 環境変数に追加されるため、非常に強力です。Since .NET Core tools run in full trust, and global tools are added to the PATH environment variable, they can be very powerful. 信頼できないユーザーからツールをダウンロードしないでください。Don't download tools from people you don't trust.

ツールが NuGet でホストされている場合は、ツールを検索することで作成者と統計情報を確認できます。If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

グローバル ツールをインストールするInstall a global tool

ツールをグローバル ツールとしてインストールするには、次の例に示すように、dotnet tool install-g または --global オプションを使用します。To install a tool as a global tool, use the -g or --global option of dotnet tool install, as shown in the following example:

dotnet tool install -g dotnetsay

出力には、次の例のように、ツールの起動に使用されたコマンドとインストールされているバージョンが表示されます。The output shows the command used to invoke the tool and the version installed, similar to the following example:

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

ツールのバイナリの既定の場所は、オペレーティング システムによって異なります。The default location for a tool's binaries depends on the operating system:

OSOS パスPath
Linux/macOSLinux/macOS $HOME/.dotnet/tools
WindowsWindows %USERPROFILE%\.dotnet\tools

この場所は、SDK を初めて実行したときにユーザーのパスに追加されるため、ツールの場所を指定せずに任意のディレクトリからグローバル ツールを呼び出すことができます。This location is added to the user's path when the SDK is first run, so global tools can be invoked from any directory without specifying the tool location.

ツールへのアクセスはユーザー固有であり、マシン グローバルではありません。Tool access is user-specific, not machine global. グローバル ツールは、ツールをインストールしたユーザーのみが使用できます。A global tool is only available to the user that installed the tool.

カスタムの場所にグローバル ツールをインストールするInstall a global tool in a custom location

カスタムの場所にグローバル ツールとしてツールをインストールするには、次の例に示すように、dotnet tool install--tool-path オプションを使用します。To install a tool as a global tool in a custom location, use the --tool-path option of dotnet tool install, as shown in the following examples.

Windows の場合:On Windows:

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

Linux または macOS の場合:On Linux or macOS:

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

この場所は、.NET Core SDK によって PATH 環境変数に自動的に追加されません。The .NET Core SDK doesn't add this location automatically to the PATH environment variable. tool-path ツールを呼び出すには、次のいずれかの方法を使用して、コマンドを使用できることを確認する必要があります。To invoke a tool-path tool, you have to make sure the command is available by using one of the following methods:

  • インストール ディレクトリを PATH 環境変数に追加します。Add the installation directory to the PATH environment variable.
  • ツールを起動するときは完全なパスを指定します。Specify the full path to the tool when you invoke it.
  • インストール ディレクトリ内からツールを呼び出します。Invoke the tool from within the installation directory.

ローカル ツールをインストールするInstall a local tool

.NET Core 3.0 SDK 以降に適用されます。Applies to .NET Core 3.0 SDK and later.

ローカル アクセス専用のツール (現在のディレクトリとサブディレクトリ用) をインストールするには、ツール マニフェスト ファイルに追加する必要があります。To install a tool for local access only (for the current directory and subdirectories), it has to be added to a tool manifest file. ツール マニフェスト ファイルを作成するには、dotnet new tool-manifest コマンドを実行します。To create a tool manifest file, run the dotnet new tool-manifest command:

dotnet new tool-manifest

このコマンドにより、 .config ディレクトリ以下に dotnet-tools.json というマニフェスト ファイルが作成されます。This command creates a manifest file named dotnet-tools.json under the .config directory. ローカル ツールをマニフェスト ファイルに追加するには、次の例に示すように、dotnet tool install コマンドを使用し、--global および --tool-path オプションを省略します。To add a local tool to the manifest file, use the dotnet tool install command and omit the --global and --tool-path options, as shown in the following example:

dotnet tool install dotnetsay

コマンド出力には、次の例のように、新しくインストールされたツールが含まれるマニフェスト ファイルが表示されます。The command output shows which manifest file the newly installed tool is in, similar to the following example:

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 つのローカル ツールがインストールされたマニフェスト ファイルの例を次に示します。The following example shows a manifest file with two local tools installed:

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

通常、ローカル ツールは、リポジトリのルート ディレクトリに追加します。You typically add a local tool to the root directory of the repository. マニフェスト ファイルをリポジトリにチェックインした後は、リポジトリからコードをチェック アウトした開発者が最新のマニフェスト ファイルを取得します。After you check in the manifest file to the repository, developers who check out code from the repository get the latest manifest file. マニフェスト ファイルに記載されているすべてのツールをインストールするには、dotnet tool restore コマンドを実行します。To install all of the tools listed in the manifest file, they run the dotnet tool restore command:

dotnet tool restore

出力には、復元されたツールが示されます。The output indicates which tools were restored:

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.

特定のツールバー ジョンをインストールするInstall a specific tool version

プレリリース バージョンまたは特定バージョンのツールをインストールするには、次の例に示すように、--version オプションを使用してバージョン番号を指定します。To install a pre-release version or a specific version of a tool, specify the version number by using the --version option, as shown in the following example:

dotnet tool install dotnetsay --version 2.1.3

ツールを使用するUse a tool

ツールを呼び出すために使用するコマンドは、インストールするパッケージの名前と異なる場合があります。The command that you use to invoke a tool may be different from the name of the package that you install. 現在のユーザーのマシンに現在インストールされているすべてのツールを表示するには、dotnet tool list コマンドを使用します。To display all of the tools currently installed on the machine for the current user, use the dotnet tool list command:

dotnet tool list

出力には、次の例のように、各ツールのバージョンとコマンドが表示されます。The output shows each tool's version and command, similar to the following example:

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

この例に示すように、一覧にはローカル ツールが表示されます。As shown in this example, the list shows local tools. グローバル ツールを表示するには、--global オプションを使用します。また、tool-path ツールを表示するには、--tool-path オプションを使用します。To see global tools, use the --global option, and to see tool-path tools, use the --tool-path option.

グローバル ツールを呼び出すInvoke a global tool

グローバル ツールの場合は、ツール コマンドを単独で使用します。For global tools, use the tool command by itself. たとえば、コマンドが dotnetsay または dotnet-doc の場合は、そのコマンドを使用してコマンドを呼び出します。For example, if the command is dotnetsay or dotnet-doc, that's what you use to invoke the command:

dotnetsay
dotnet-doc

コマンドがプレフィックス dotnet- で始まる場合、ツールを呼び出すもう 1 つの方法は、dotnet コマンドを使用して、ツール コマンド プレフィックスを省略することです。If the command begins with the prefix dotnet-, an alternative way to invoke the tool is to use the dotnet command and omit the tool command prefix. たとえば、コマンドが dotnet-doc の場合、次のコマンドを使ってツールを呼び出します。For example, if the command is dotnet-doc, the following command invokes the tool:

dotnet doc

ただし、次のシナリオでは、dotnet コマンドを使ってグローバル ツールを呼び出すことはできません。However, in the following scenario you can't use the dotnet command to invoke a global tool:

  • グローバル ツールとローカル ツールには、同じコマンドの先頭に dotnet- が付きます。A global tool and a local tool have the same command prefixed by dotnet-.
  • ローカル ツールのスコープ内にあるディレクトリからグローバル ツールを呼び出します。You want to invoke the global tool from a directory that is in scope for the local tool.

このシナリオでは、dotnet doc および dotnet dotnet-doc によってローカル ツールが呼び出されます。In this scenario, dotnet doc and dotnet dotnet-doc invoke the local tool. グローバル ツールを呼び出すには、コマンドを単独で使用します。To invoke the global tool, use the command by itself:

dotnet-doc

tool-path ツールを呼び出すInvoke a tool-path tool

tool-path オプションを使用してインストールされたグローバル ツールを呼び出すには、この記事で前述したように、コマンドを使用できることを確認します。To invoke a global tool that is installed by using the tool-path option, make sure the command is available, as explained earlier in this article.

ローカル ツールを呼び出すInvoke a local tool

ローカル ツールを呼び出すには、インストール ディレクトリ内から dotnet コマンドを使用する必要があります。To invoke a local tool, you have to use the dotnet command from within the installation directory. 次の例に示すように、長い形式 (dotnet tool run <COMMAND_NAME>) または短い形式 (dotnet <COMMAND_NAME>) を使用できます。You can use the long form (dotnet tool run <COMMAND_NAME>) or the short form (dotnet <COMMAND_NAME>), as shown in the following examples:

dotnet tool run dotnetsay
dotnet dotnetsay

コマンドの先頭に dotnet- が付いている場合、ツールを呼び出すときにプレフィックスを含めるか省略することができます。If the command is prefixed by dotnet-, you can include or omit the prefix when you invoke the tool. たとえば、コマンドが dotnet-doc の場合、次の例のいずれかを使ってローカル ツールを呼び出します。For example, if the command is dotnet-doc, any of the following examples invokes the local tool:

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

ツールを更新するUpdate a tool

ツールを更新するには、ツールをアンインストールしてから、最新の安定バージョンで再インストールする必要があります。Updating a tool involves uninstalling and reinstalling it with the latest stable version. ツールを更新するには、ツールのインストールに使用したものと同じオプションを指定して dotnet tool update コマンドを使用します。To update a tool, use the dotnet tool update command with the same option that you used to install the tool:

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

ローカル ツールの場合、SDK を使うと、現在のディレクトリと親ディレクトリを検索してパッケージ ID を含む最初のマニフェスト ファイルを見つけることができます。For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories. マニフェスト ファイルにそのようなパッケージ ID がない場合は、SDK によって、最も近いマニフェスト ファイルに新しいエントリが追加されます。If there is no such package ID in any manifest file, the SDK adds a new entry to the closest manifest file.

ツールをアンインストールするUninstall a tool

dotnet tool uninstall コマンドを使用して、ツールのインストールに使用したものと同じオプションを使用してツールを削除します。Remove a tool by using the dotnet tool uninstall command with the same option that you used to install the tool:

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

ローカル ツールの場合、SDK を使うと、現在のディレクトリと親ディレクトリを検索してパッケージ ID を含む最初のマニフェスト ファイルを見つけることができます。For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories.

ヘルプとトラブルシューティングを取得するGet help and troubleshoot

使用できる dotnet tool コマンドの一覧を取得するには、次のコマンドを入力します。To get a list of available dotnet tool commands, enter the following command:

dotnet tool --help

ツールの使用手順を取得するには、次のコマンドのいずれかを入力するか、ツールの Web サイトを参照してください。To get tool usage instructions, enter one of the following commands or see the tool's website:

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

ツールのインストールまたは実行に失敗した場合は、「.NET Core ツールの使用に関する問題のトラブルシューティング」を参照してください。If a tool fails to install or run, see Troubleshoot .NET Core tool usage issues.

関連項目See also