次の方法で共有

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

  • [アーティクル]

.NET ツール (グローバル ツールまたはローカル ツール) をインストールまたは実行しようとすると、問題が発生する可能性があります。 この記事では、一般的な根本原因と考えられる解決策について説明します。

インストールされている .NET ツールの実行に失敗する

.NET ツールの実行に失敗した場合、ほとんどの場合、次のいずれかの問題が発生しました。

実行可能ファイルが見つかりません

実行可能ファイルが見つからない場合は、次のようなメッセージが表示されます。

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 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.

実行可能ファイルの名前によって、ツールの呼び出し方法が決まります。 次の表では、形式について説明します。

実行可能ファイル名の形式 呼び出し形式
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

グローバル ツール

グローバル ツールは、既定のディレクトリまたは特定の場所にインストールできます。 既定のディレクトリは次のとおりです。

OS パス
Linux/macOS $HOME/.dotnet/tools
ウィンドウズ %USERPROFILE%\.dotnet\tools

グローバル ツールを実行しようとしている場合は、コンピューター上の PATH 環境変数にグローバル ツールをインストールしたパスが含まれており、実行可能ファイルがそのパスにあることを確認します。

.NET CLI は、最初の使用時に PATH 環境変数に既定の場所を追加しようとします。 ただし、場所が PATH に自動的に追加されないシナリオがいくつかあります。

  • Linux を使用していて、apt-get や rpm ではなく、.tar.gz ファイルを使用して .NET SDK をインストールしている場合。
  • macOS 10.15 "Catalina" 以降のバージョンを使用している場合。
  • macOS 10.14 "Mojave" 以前のバージョンを使用していて、.pkgではなく .tar.gz ファイルを使用して .NET SDK をインストールしている場合。
  • .NET Core 3.0 SDK をインストールし、DOTNET_ADD_GLOBAL_TOOLS_TO_PATH 環境変数を falseに設定している場合。
  • .NET Core 2.2 SDK 以前のバージョンをインストールし、DOTNET_SKIP_FIRST_TIME_EXPERIENCE 環境変数を trueに設定している場合。

これらのシナリオでは、または dotnet ツール のインストール中に--tool-path オプションを指定した場合、コンピューター上の PATH 環境変数には、グローバル ツールをインストールしたパスが自動的に含まれません。 その場合は、シェルが環境変数を更新するために提供する任意のメソッドを使用して、ツールの場所 ($HOME/.dotnet/toolsなど) を PATH 環境変数に追加します。 詳細については、「.NET ツールの 」を参照してください。

ローカル ツール

ローカル ツールを実行しようとしている場合は、現在のディレクトリまたはその親ディレクトリに dotnet-tools.json というマニフェスト ファイルがあることを確認します。 このファイルは、ルート フォルダーではなく、プロジェクト フォルダー階層内の任意の場所 .config という名前のフォルダーの下に存在することもできます。 dotnet-tools.json が存在する場合は、それを開き、実行しようとしているツールを確認します。 ファイルに "isRoot": trueのエントリが含まれていない場合は、さらにファイル階層で追加のツール マニフェスト ファイルを確認します。

指定したパスでインストールされた .NET ツールを実行する場合は、ツールを使用するときにそのパスを含める必要があります。 ツール パスのインストール済みツールの使用例を次に示します。

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

ランタイムが見つかりません

.NET ツールは フレームワークに依存するアプリケーションです。つまり、コンピューターにインストールされている .NET ランタイムに依存します。 想定されるランタイムが見つからない場合は、次のような通常の .NET ランタイムロールフォワードルールに従います。

  • アプリケーションは、指定されたメジャー バージョンとマイナー バージョンの最高のパッチ リリースにロールフォワードします。
  • メジャー バージョン番号とマイナー バージョン番号が一致するランタイムがない場合は、次に上位のマイナー バージョンが使用されます。
  • ロールフォワードは、ランタイムのプレビュー バージョン間、またはプレビュー バージョンとリリース バージョンの間では発生しません。 そのため、プレビュー バージョンを使用して作成された .NET ツールは、作成者が再構築して再発行し、再インストールする必要があります。

ロールフォワードは、次の 2 つの一般的なシナリオでは既定では発生しません。

  • 使用できるのは、下位バージョンのランタイムのみです。 ロールフォワードでは、以降のバージョンのランタイムのみが選択されます。
  • ランタイムの上位のメジャー バージョンのみを使用できます。 ロールフォワードはメジャー バージョンの境界を越えません。

アプリケーションで適切なランタイムが見つからない場合は、実行に失敗し、エラーが報告されます。

次のいずれかのコマンドを使用して、コンピューターにインストールされている .NET ランタイムを確認できます。

dotnet --list-runtimes
dotnet --info

現在インストールされているランタイム バージョンをツールでサポートする必要があると思う場合は、ツールの作成者に問い合わせて、バージョン番号またはマルチターゲットを更新できるかどうかを確認できます。 ツール パッケージを再コンパイルし、バージョン番号を更新して NuGet に再発行したら、コピーを更新できます。 それは起こりませんが、最も簡単な解決策は、実行しようとしているツールで動作するランタイムのバージョンをインストールすることです。 特定の .NET ランタイム バージョンをダウンロードするには、.NET ダウンロード ページを参照してください。

既定以外の場所に .NET SDK をインストールする場合は、dotnet 実行可能ファイルを含むディレクトリに DOTNET_ROOT 環境変数を設定する必要があります。

.NET ツールのインストールが失敗する

.NET グローバル ツールまたはローカル ツールのインストールが失敗する理由は多数あります。 ツールのインストールが失敗すると、次のようなメッセージが表示されます。

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 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 メッセージは、前のメッセージと共にユーザーに直接表示されます。 NuGet メッセージは、問題の特定に役立つ場合があります。

パッケージ命名規則の強制

Microsoft は、ツールのパッケージ ID に関するガイダンスを変更したため、予測された名前で多数のツールが見つかりません。 新しいガイダンスでは、すべての Microsoft ツールの先頭に "Microsoft" が付きます。このプレフィックスは予約済みであり、Microsoft 認定証明書で署名されたパッケージにのみ使用できます。

移行中、一部の Microsoft ツールは古い形式のパッケージ ID を持ち、他のツールは新しい形式になります。

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

パッケージ ID が更新されたら、最新の更新プログラムを取得するには、新しいパッケージ ID に変更する必要があります。 簡略化されたツール名を持つパッケージは非推奨になります。

プレビュー リリース

  • プレビュー リリースをインストールしようとしているが、--version オプションを使用してバージョンを指定しなかった。

プレビュー段階の .NET ツールは、プレビュー段階であることを示すために、名前の一部で指定する必要があります。 プレビュー全体を含める必要はありません。 バージョン番号が想定される形式であると仮定すると、次の例のように使用できます。

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

パッケージが .NET ツールではない

  • この名前の NuGet パッケージが見つかりましたが、.NET ツールではありませんでした。

.NET ツールではなく通常の NuGet パッケージである NuGet パッケージをインストールしようとすると、次のようなエラーが表示されます。

NU1212: <toolName>のプロジェクト パッケージの組み合わせが無効です。 DotnetToolReference プロジェクト スタイルには、DotnetTool 型の参照のみを含めることができます。

NuGet フィードにアクセスできない

  • インターネット接続の問題が原因で、必要な NuGet フィードにアクセスできません。

ツールのインストールには、ツール パッケージを含む NuGet フィードへのアクセスが必要です。 フィードが使用できない場合は失敗します。 nuget.configを使用してフィードを変更したり、特定の nuget.config ファイルを要求したり、--add-source スイッチで追加のフィードを指定したりできます。 既定では、接続できないフィードに対して NuGet はエラーをスローします。 フラグ --ignore-failed-sources は、これらの到達不能なソースをスキップできます。

パッケージ ID が正しくありません

  • ツールの名前を誤って入力しました。

エラーの一般的な理由は、ツール名が正しくないということです。 これは、誤った処理が原因で発生する可能性があります。または、ツールが移動または非推奨になったために発生する可能性があります。 NuGet.org 上のツールの場合、名前が正しいことを確認する 1 つの方法は、NuGet.org でツールを検索し、インストール コマンドをコピーすることです。

401 (未認証)

ほとんどの場合、代替の NuGet フィードを指定しており、そのフィードには認証が必要です。 これを解決するには、いくつかの異なる方法があります。

  • --ignore-failed-sources パラメーターを追加して、プライベート フィードからのエラーをバイパスし、パブリック Microsoft フィードを使用します。

    Microsoft NuGet フィードからツールをインストールする場合、Microsoft の NuGet フィードが結果を返す前に、カスタム フィードからこのエラーが返されます。 このエラーは要求を終了し、保留中の他のフィード要求 (Microsoft の NuGet フィード) を取り消します。 --ignore-failed-sources オプションを追加すると、コマンドはこのエラーを警告として扱い、他のフィードが要求を処理できるようにします。

    dotnet tool install -g --ignore-failed-sources <toolName>

  • --add-source パラメーターを使用して Microsoft NuGet フィードを強制します。

    グローバルまたはローカルの NuGet 構成ファイルに、パブリック Microsoft NuGet フィードがない可能性があります。 誤ったフィードを回避し、パブリック Microsoft フィードに依存するには、--add-source パラメーターと --ignore-failed-sources パラメーターの組み合わせを使用します。

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • カスタム NuGet 構成 --configfile <FILE> パラメーターを使用します。

    パブリック Microsoft NuGet フィードのみを含むローカル nuget.config ファイルを作成し、--configfile パラメーターで参照します。

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    構成ファイルの例を次に示します。

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    詳細については、nuget.config リファレンスを参照してください。

  • 構成ファイルに必要な資格情報を追加します。

    構成済みのフィードにパッケージが存在することがわかっている場合は、NuGet 構成ファイルにログイン資格情報を指定します。 nuget 構成ファイル内の資格情報の詳細については、nuget.config リファレンスの packageSourceCredentials セクションを参照してください。

関連項目