.NET Core ツールの使用に関する問題のトラブルシューティングTroubleshoot .NET Core tool usage issues

グローバル ツールまたはローカル ツールとして .NET Core ツールをインストールまたは実行しようとすると、問題が発生することがあります。You might come across issues when trying to install or run a .NET Core tool, which can be a global tool or a local tool. この記事では、一般的な根本原因と考えられる解決策について説明します。This article describes the common root causes and some possible solutions.

インストールされている .NET Core ツールを実行できないInstalled .NET Core tool fails to run

.NET Core ツールの実行が失敗する場合、最も可能性が高いのは、次のいずれかの問題が発生していることです。When a .NET Core tool fails to run, most likely you ran into one of the following issues:

  • ツールの実行可能ファイルが見つかりませんでした。The executable file for the tool wasn't found.
  • 正しいバージョンの .NET Core ランタイムが見つかりませんでした。The correct version of the .NET Core runtime wasn't found.

実行可能ファイルが見つからないExecutable file not found

実行可能ファイルが見つからない場合は、次のようなメッセージが表示されます。If the executable file isn't found, you'll see a message similar to the following:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET Core program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

実行可能ファイルの名前によって、ツールの呼び出し方法が決まります。The name of the executable determines how you invoke the tool. 次の表ではその形式について説明します。The following table describes the format:

実行可能ファイル名の形式Executable name format 呼び出し方式Invocation format
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>
  • グローバル ツールGlobal tools

    グローバル ツールは、既定のディレクトリ内または特定の場所にインストールすることができます。Global tools can be installed in the default directory or in a specific location. 既定のディレクトリは次のとおりです。The default directories are:

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

    グローバル ツールを実行しようとしている場合は、コンピューター上の PATH 環境変数にグローバル ツールをインストールしたパスが含まれること、およびそのパスに実行可能ファイルが存在することを確認してください。If you're trying to run a global tool, check that the PATH environment variable on your machine contains the path where you installed the global tool and that the executable is in that path.

    .NET Core CLI は、初めて使用したときに既定の場所を PATH 環境変数に追加しようとします。The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. ただし、場所が PATH に自動的に追加されないシナリオがいくつかあるため、次のような場合は PATH を編集して構成する必要があります。However, there are a couple of scenarios where the location might not be added to PATH automatically, so you'll have to edit PATH to configure it for the following cases:

    • Linux を使用していて、apt-get または rpm ではなく .tar.gz ファイルを使用して .NET Core SDK をインストールしている場合。If you're using Linux and you've installed the .NET Core SDK using .tar.gz files and not apt-get or rpm.
    • macOS 10.15 "Catalina" またはそれ以降のバージョンを使用している場合。If you're using macOS 10.15 "Catalina" or later versions.
    • macOS 10.14 "Mojave" 以前のバージョンを使用していて、 .pkg ではなく .tar.gz ファイルを使用して .NET Core SDK をインストールしている場合。If you're using macOS 10.14 "Mojave" or earlier versions, and you've installed the .NET Core SDK using .tar.gz files and not .pkg.
    • .NET Core 3.0 SDK をインストールしてあり、DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 環境変数を false に設定している場合。If you've installed the .NET Core 3.0 SDK and you've set the DOTNET_ADD_GLOBAL_TOOLS_TO_PATH environment variable to false.
    • .NET Core 2.2 SDK 以前のバージョンをインストールしてあり、DOTNET_SKIP_FIRST_TIME_EXPERIENCE 環境変数を true に設定している場合。If you've installed .NET Core 2.2 SDK or earlier versions, and you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable to true.

    グローバル ツールの詳細については、「.NET Core グローバル ツールの概要」を参照してください。For more information about global tools, see .NET Core Global Tools overview.

  • ローカル ツールLocal tools

    ローカル ツールを実行しようとしている場合は、dotnet-tools.json という名前のマニフェストファイルが、現在のディレクトリまたはそのいずれかの親ディレクトリにあることを確認します。If you're trying to run a local tool, verify that there's a manifest file called dotnet-tools.json in the current directory or any of its parent directories. このファイルは、ルート フォルダーではなく、プロジェクト フォルダー階層のどこかにある .config という名前のフォルダーに存在することもあります。This file can also live under a folder named .config anywhere in the project folder hierarchy, instead of the root folder. dotnet-tools.json が存在する場合は、それを開き、実行しようとしているツールを確認します。If dotnet-tools.json exists, open it and check for the tool you're trying to run. ファイルに "isRoot": true のエントリが含まれていない場合は、さらに上のファイル階層で他のツール マニフェスト ファイルを確認します。If the file doesn't contain an entry for "isRoot": true, then also check further up the file hierarchy for additional tool manifest files.

    指定されたパスにインストールされている .NET Core ツールを実行しようとしている場合は、ツールを使用するときにそのパスを含める必要があります。If you're trying to run a .NET Core tool that was installed with a specified path, you need to include that path when using the tool. ツールパスにインストールされたツールを使用する例を次に示します。An example of using a tool-path installed tool is:

    ..\<toolDirectory>\dotnet-<toolName>
    

ランタイムが見つからないRuntime not found

.NET Core ツールは、フレームワークに依存するアプリケーションです。つまり、お使いのマシンにインストールされている .NET Core ランタイムに依存します。.NET Core tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. 予定していたランタイムが見つからない場合、ツールは次のような通常の .NET Core ランタイムのロール フォワード ルールに従います。If the expected runtime isn't found, they follow normal .NET Core runtime roll-forward rules such as:

  • アプリケーションは、指定されたメジャー バージョンおよびマイナー バージョンの最上位の修正プログラム リリースにロール フォワードされます。An application rolls forward to the highest patch release of the specified major and minor version.
  • 一致するメジャー バージョン番号とマイナー バージョン番号と一致するランタイムがない場合は、次に高いマイナー バージョンが使用されます。If there's no matching runtime with a matching major and minor version number, the next higher minor version is used.
  • ランタイムのプレビュー バージョン間、またはプレビュー バージョンとリリース バージョン間では、ロール フォワードは発生しません。Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. したがって、プレビュー バージョンを使用して作成された .NET Core ツールは、作成者がリビルドして再パブリッシュしてから再インストールする必要があります。So, .NET Core tools created using preview versions must be rebuilt and republished by the author and reinstalled.

次の 2 つの一般的なシナリオでは、ロールフォワードは既定では実行されません。Roll-forward won't occur by default in two common scenarios:

  • 使用できるのが古いバージョンのランタイムだけの場合。Only lower versions of the runtime are available. ロールフォワードでは、ランタイムの新しいバージョンのみが選択されます。Roll-forward only selects later versions of the runtime.
  • 使用できるのが高いメジャー バージョンのランタイムだけの場合。Only higher major versions of the runtime are available. ロールフォワードでは、メジャー バージョンの境界を越えることはありません。Roll-forward doesn't cross major version boundaries.

アプリケーションで適切なランタイムが見つからない場合は、実行が失敗し、エラーが報告されます。If an application can't find an appropriate runtime, it fails to run and reports an error.

次のいずれかのコマンドを使用して、お使いのコンピューターにインストールされている .NET Core ランタイムを確認することができます。You can find out which .NET Core runtimes are installed on your machine using one of the following commands:

dotnet --list-runtimes
dotnet --info

現在インストールされているランタイム バージョンがツールでサポートされている必要があると思われる場合は、ツールの作成者に連絡して、バージョン番号またはマルチターゲットを更新できるかどうかを確認してください。If you think the tool should support the runtime version you currently have installed, you can contact the tool author and see if they can update the version number or multi-target. 更新されたバージョン番号でツール パッケージが再コンパイルされて NuGet に再発行された後、コピーを更新することができます。Once they've recompiled and republished their tool package to NuGet with an updated version number, you can update your copy. それまでの間の最も簡単な解決策は、実行しようとしているツールで動作するランタイムのバージョンをインストールすることです。While that doesn't happen, the quickest solution for you is to install a version of the runtime that would work with the tool you're trying to run. 特定の .NET Core ランタイム バージョンをダウンロードするには、.NET Core ダウンロード ページを参照してください。To download a specific .NET Core runtime version, visit the .NET Core download page.

既定以外の場所に .NET Core SDK をインストールする場合は、dotnet 実行可能ファイルが格納されているディレクトリに、環境変数 DOTNET_ROOT を設定する必要があります。If you install the .NET Core SDK to a non-default location, you need to set the environment variable DOTNET_ROOT to the directory that contains the dotnet executable.

.NET Core ツールのインストールが失敗する.NET Core tool installation fails

いろいろな理由で、.NET Core のグローバル ツールまたはローカル ツールのインストールが失敗する可能性があります。There are a number of reasons the installation of a .NET Core global or local tool may fail. ツールのインストールが失敗すると、次のようなメッセージが表示されます。When the tool installation fails, you'll see a message similar to following one:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET Core tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

これらのエラーの診断に役立つよう、上のメッセージと共に、NuGet のメッセージがユーザーに直接表示されます。To help diagnose these failures, NuGet messages are shown directly to the user, along with the previous message. NuGet のメッセージは、問題の特定に役立つ場合があります。The NuGet message may help you identify the problem.

パッケージの名前付けの適用Package naming enforcement

Microsoft では、ツールのパッケージ ID に関するガイダンスを変更したため、いくつかのツールが予測される名前で見つからなくなっています。Microsoft has changed its guidance on the Package ID for tools, resulting in a number of tools not being found with the predicted name. 新しいガイダンスでは、すべての Microsoft ツールに "Microsoft" というプレフィックスが付いています。The new guidance is that all Microsoft tools be prefixed with "Microsoft." このプレフィックスは予約されており、Microsoft が承認した証明書で署名されたパッケージにのみ使用できます。This prefix is reserved and can only be used for packages signed with a Microsoft authorized certificate.

移行の間は、古い形式のパッケージ ID を持つ Microsoft ツールと、新しい形式を持つツールが混在します。During the transition, some Microsoft tools will have the old form of the package ID, while others will have the new form:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

パッケージ ID が更新されると、最新の更新プログラムを取得するには、新しいパッケージ ID に変更する必要があります。As package IDs are updated, you'll need to change to the new package ID to get the latest updates. ツール名が簡略化されているパッケージは非推奨となります。Packages with the simplified tool name will be deprecated.

プレビュー リリースPreview releases

  • プレビュー リリースをインストールしようとして、--version オプションを使用してバージョンを指定しませんでした。You're attempting to install a preview release and didn't use the --version option to specify the version.

プレビュー段階にある .NET Core ツールは、プレビュー段階であることを、名前の一部で指定する必要があります。.NET Core tools that are in preview must be specified with a portion of the name to indicate that they are in preview. プレビュー全体を含める必要はありません。You don't need to include the entire preview. バージョン番号が想定される形式であると仮定すると、次の例のようなものを使用できます。Assuming the version numbers are in the expected format, you can use something like the following example:

dotnet tool install -g --version 1.1.0-pre <toolName>

注意

.NET Core CLI チームは、これを簡単にするために、今後のリリースで --preview スイッチを追加することを計画しています。The .NET Core CLI team is planning to add a --preview switch in a future release to make this easier.

パッケージが .NET Core ツールではないPackage isn't a .NET Core tool

  • この名前の NuGet パッケージは見つかりましたが、.NET Core ツールではありませんでした。A NuGet package by this name was found, but it wasn't a .NET Core tool.

.NET Core ツールではなく、通常の NuGet パッケージである NuGet パッケージをインストールしようとすると、次のようなエラーが表示されます。If you try to install a NuGet package that is a regular NuGet package and not a .NET Core tool, you'll see an error similar to the following:

NU1212:<ToolName> のプロジェクトとパッケージの組み合わせが無効です。NU1212: Invalid project-package combination for <ToolName>. DotnetToolReference プロジェクト形式には、DotnetTool タイプの参照のみ含めることができます。DotnetToolReference project style can only contain references of the DotnetTool type.

NuGet フィードにアクセスできないNuGet feed can't be accessed

  • おそらくインターネット接続に問題があるため、必要な NuGet フィードにアクセスできません。The required NuGet feed can't be accessed, perhaps because of an Internet connection problem.

ツールをインストールするには、ツール パッケージが含まれている NuGet フィードにアクセスする必要があります。Tool installation requires access to the NuGet feed that contains the tool package. フィードが使用できない場合は失敗します。It fails if the feed isn't available. nuget.config でフィードを変更するか、特定の nuget.config ファイルを要求するか、--add-source スイッチを使用して追加のフィードを指定することができます。You can alter feeds with nuget.config, request a specific nuget.config file, or specify additional feeds with the --add-source switch. 既定では、NuGet では接続できないフィードに対してエラーがスローされます。By default, NuGet throws an error for any feed that can't connect. フラグ --ignore-failed-sources を指定すると、これらの到達できないソースをスキップできます。The flag --ignore-failed-sources can skip these non-reachable sources.

パッケージ ID が正しくないPackage ID incorrect

  • ツールの名前が間違って入力されています。You mistyped the name of the tool.

失敗でよくある理由は、ツール名が正しくないことです。A common reason for failure is that the tool name isn't correct. これは、入力ミスや、ツールが移動されたか非推奨になったために、発生する可能性があります。This can happen because of mistyping, or because the tool has moved or been deprecated. NuGet.org のツールで、確実に正しい名前を使用する方法の 1 つは、NuGet.org でツールを検索し、インストール コマンドをコピーすることです。For tools on NuGet.org, one way to ensure you have the name correct is to search for the tool at NuGet.org and copy the installation command.

関連項目See also