NuGet パッケージの復元を使用してパッケージを復元する

NuGet パッケージの復元では、プロジェクト ファイルまたは packages.config ファイルに一覧表示されているすべてのプロジェクトの依存関係が復元されます。 パッケージは、nuget restore、dotnet restore、msbuild -t:restore を使用して手動で、または Visual Studio を使用して復元できます。 dotnet build および dotnet run コマンドはパッケージを自動的に復元し、プロジェクトのビルド時にパッケージを自動的に復元するように Visual Studio を構成できます。

よりクリーンな開発環境を促進し、リポジトリのサイズを小さくするために、パッケージの復元では、プロジェクトのすべての依存関係をソース管理に格納しなくても使用できるようになります。 パッケージ バイナリを除外するようにソース管理リポジトリを構成するには、パッケージとソースの管理に関するページをご覧ください。

パッケージの復元の動作

パッケージの復元では、プロジェクト ファイル (.csproj) の <PackageReference> か packages.config ファイルの <package> に一致する状態になるよう、すべてのパッケージの依存関係のインストールを試みます。 パッケージの復元では、最初に、必要に応じて、プロジェクトの直接的な依存関係がインストールされます。この後、依存関係グラフ全体にパッケージの依存関係がインストールされます。

必要なパッケージがまだインストールされていない場合、NuGet は最初に、ローカルのグローバルパッケージまたは HTTP キャッシュ フォルダーからパッケージの取得を試みます。 パッケージがローカル フォルダーにない場合、NuGet は、Visual Studio で [ツール]>[オプション]>[NuGet パッケージ マネージャー]>[パッケージ ソース] で構成されたすべてのソースからパッケージのダウンロードを試みます。

復元時には、NuGet はパッケージ ソースの順序を無視し、最初に要求に応じたソースのパッケージを使用します。 復元に失敗した場合、NuGet はすべてのソースをチェックするまでエラーを示しません。 その後で、NuGet は一覧の最後のソースについてのみ障害を報告します。 このエラーは、他のエラーが個別に一覧表示されなくても、どのソースにもパッケージが存在しなかったことを意味します。

NuGet の動作については、「一般的な NuGet 構成」を参照してください。

パッケージの復元

プロジェクト ファイルまたは packages.config ファイルのパッケージ参照が正しい場合は、好みのツールを使用してパッケージを復元します。

• Visual Studio
• dotnet CLI
• nuget.exe CLI
• MSBuild
• Azure Pipelines または Azure DevOps Server

復元が成功した後:

• <PackageReference> を使用するプロジェクトの場合、パッケージはローカルの global-packages フォルダーに存在し、プロジェクト obj/project.assets.json ファイルが再作成されます。
• packages.config を使用するプロジェクトの場合、パッケージはプロジェクトの packages フォルダーに表示されます。
• この場合、プロジェクトを正常にビルドできるようになります。

プロジェクト ファイルまたは packages.config ファイルのパッケージ参照が正しくない、および必要な状態と一致しない場合は、パッケージの復元を使用する代わりに正しいパッケージをインストールまたは更新する必要があります。

[パッケージの復元] を実行した後も、パッケージの不足やパッケージに関連するエラー (ソリューション エクスプローラーのエラー アイコンなど) が発生する場合は、「パッケージの復元エラーのトラブルシューティング」に記載の手順に従うか、あるいはパッケージを再インストールまたは更新します。 Visual Studio のパッケージ マネージャー コンソールには、パッケージを再インストールするためのオプションがいくつか用意されています。 詳細については、「Use Package-Update(パッケージ更新の使用)」を参照してください。

Visual Studio でのパッケージの復元

Windows 上の Visual Studio では、パッケージを自動または手動で復元できます。 まず、[ツール]>[オプション]>[NuGet パッケージ マネージャー] で、パッケージの復元を構成します。

Visual Studio のパッケージの復元オプションを構成する

[ツール]>[オプション]>[NuGet パッケージ マネージャー]>[全般] で、次のパッケージ復元オプションを構成します。

見つからないパッケージのダウンロードを NuGet に許可

[見つからないパッケージのダウンロードを NuGet に許可] を選択して、パッケージの復元と NuGet パッケージの復元コマンドを有効にします。 この選択により、packageRestore/enabled 設定は、グローバル NuGet.Config ファイルの packageRestore セクション (Windows では %AppData%\Roaming\NuGet、Mac または Linux では ~/.nuget/NuGet/) で True に設定されます。

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Note

packageRestore/enabled 設定をグローバルにオーバーライドするには、Visual Studio の起動前またはビルドの開始前に環境変数 EnableNuGetPackageRestore の値を True または False に設定します。

コンピューター上のすべてのユーザーに対してパッケージの復元を有効または無効にするには、構成設定をグローバル NuGet.Config ファイル (Windows の %ProgramData%\NuGet\Config、特定の <IDE>\<Version>\<SKU> Visual Studio フォルダーの下の場合もあり、または Mac/Linux の ~/.local/share) に追加できます。 その場合、個々のユーザーは、必要に応じてプロジェクト レベルで選択的に復元を有効にできます。 NuGet で複数の構成ファイルに優先順位を付けるしくみについては、共通 NuGet 構成に関するページを参照してください。

重要

NuGet.Config で直接 packageRestore 設定を編集する場合、[オプション] に現在の値が表示されるように Visual Studio を再起動します。

ビルド中に見つからないパッケージを自動的に確認

[Visual Studio でのビルド中に見つからないパッケージを自動的に確認] を選択すると、Visual Studio からビルドを実行するときに見つからないパッケージが自動的に復元されます。 この設定が MSBuild コマンド ラインから実行されるビルドに影響を与えることはありません。 この選択により、packageRestore/automatic 設定は NuGet.Config ファイルの packageRestore セクションで True に設定されます。

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

SDK スタイル以外のプロジェクトの場合、自動復元を有効にするには、[見つからないパッケージのダウンロードを NuGet に許可] と、[オプション] の [Visual Studio でのビルド中に見つからないパッケージを自動的に確認] を選択する必要があります。

既定のパッケージ管理形式を選択する

NuGet には、PackageReference と packages.config という 2 つのパッケージ管理形式があります。[パッケージ管理] のドロップダウン リストから、使用する形式を選択します。 また、最初のパッケージインストールで形式の選択を許可するかどうかを選択することもできます。

Note

• プロジェクトで両方のパッケージ管理形式がサポートされていない場合は、プロジェクトと互換性があるパッケージ管理形式が NuGet で使用されるため、オプションで設定した既定ではない可能性があります。 そのオプションを選択したとしても、NuGet では、最初のインストール時に選択を求めるメッセージは表示されません。

• パッケージ マネージャー コンソールを使用してプロジェクトの最初のパッケージをインストールする場合、[オプション] でオプションが選択されていても、NuGet で形式の選択が要求されることはありません。

パッケージを手動または自動で復元する

[オプション] でパッケージの復元を有効にした後、ソリューション エクスプローラーでソリューションを右クリックし、[NuGet パッケージの復元] を選択してパッケージをいつでも復元できます。

[オプション] で自動復元を有効にした場合、パッケージの復元は、テンプレートからプロジェクトを作成するとき、またはプロジェクトをビルドするときに自動的に行われます。 NuGet 4.0 以降では、SDK スタイルのプロジェクトの変更時にも復元は自動的に行われます。

<PackageReference> を使用するプロジェクトの場合は、Visual Studio ソリューション エクスプローラーの [依存関係]>[パッケージ] でパッケージ参照を確認できます。 ビルドを手動で復元または実行するときに正しくインストールされないパッケージには、ソリューション エクスプローラーにエラー アイコンが表示されます。 プロジェクトを右クリックして [NuGet パッケージの管理] を選択し、NuGet パッケージ マネージャーを使用して、影響を受けるパッケージのアンインストールと再インストールを行います。 詳細については、「パッケージを再インストールして更新する」を参照してください。

「このプロジェクトは、このコンピューター上にない NuGet パッケージを参照しています」または「1 つ以上の NuGet パッケージを復元する必要がありますが、同意が与えられていないため、復元できませんでした」というエラーが表示される場合は、自動復元を有効にしてください。 以前のプロジェクトについては、「パッケージの自動復元への移行」をご覧ください。 「パッケージの復元エラーのトラブルシューティング」もご覧ください。

dotnet CLI を使用した復元

dotnet restore コマンドは、プロジェクト ファイルで <PackageReference> と表示されるパッケージを復元します。 詳細については、プロジェクト ファイルのパッケージ 参照に関するページを参照してください。

.NET Core 2.0 以降は、dotnet build コマンドと dotnet run コマンドで、パッケージが自動的に復元されます。 NuGet 4.0 以降、dotnet restore と同じコードの nuget restore が実行されます。

dotnet restore でパッケージを復元するには:

1. コマンド ラインを開き、プロジェクト ファイルが含まれるディレクトリに切り替えます。
2. dotnet restore を実行します。

重要

不足しているパッケージ参照をプロジェクト ファイルに追加するには、dotnet add package を使います。これによって restore も実行されます。

NuGet CLI を使用した復元

NuGet CLI 復元 コマンドを使用すると、不足しているパッケージをダウンロードしてインストールします。 このコマンドは、パッケージ参照に PackageReference や packages.config を使用するプロジェクトで機能します。

install や restore のようなコマンドはパッケージをディスクにのみ追加し、プロジェクト ファイルや packages.config は変更されません。プロジェクトの依存関係を追加するには、Visual Studio パッケージ マネージャー UI かパッケージ マネージャー コンソールを使用します。

パッケージを復元するには、次のコマンドを実行します。

nuget restore <projectPath>

restore コマンドを使用すると、指定されたプロジェクト パス内の ソリューション ファイルか package.config ファイルを使用します。

たとえば、MySolution.sln のすべてのパッケージを現在のディレクトリに復元するには、次のコマンドを実行します。

nuget restore MySolution.sln

Note

非SDK スタイルのプロジェクトを使用する場合は、代わりに PackageReference か msbuild -t:restore を使用してパッケージを復元します。

MSBuild を使用した復元

msbuild -t:restore を使用して、Visual Studio 2017 以降に含まれている NuGet 4.x 以降および MSBuild 15.1 以降のパッケージを復元できます。

このコマンドは、パッケージ参照に PackageReference を使用するプロジェクトでパッケージを復元します。 MSBuild 16.5 以降では、-p:RestorePackagesConfig=true で使用される場合、このコマンドは packages.config パッケージ参照もサポートします。

MSBuild 復元を使用するには:

1. 開発者コマンド プロンプトを検索し、Windows の [スタート] メニューからプロンプトを開始して、開発者コマンド プロンプトを開き、MSBuild に必要なすべてのパスを構成します。

2. プロジェクト フォルダーに切り替えて、msbuild -t:restore を入力します。

3. 復元が完了したら、msbuild を入力し、プロジェクトをリビルドします。 MSBuild の出力にビルドが正常に完了したことが示されていることを確認します。

Note

ビルドは既定のターゲットであるため、msbuild -restore を使用して restore を実行し、プロジェクトを再読み込みしてビルドできます。 詳細については、「Restore and build with one MSBuild command(1 つの MSBuild コマンドを使用した復元とビルド)」を参照してください。

Azure Pipelines または Azure DevOps Server で復元する

Azure Pipelines でビルド定義を作成するとき、定義の中でビルド タスクの前に NuGet CLI 復元または dotnet CLI 復元タスクを含めます。 一部のビルド テンプレートには、既定で復元タスクが含まれています。

Azure DevOps Server と TFS 2013 以降では、TFS 2013 以降のチーム ビルド テンプレートを使用している場合、ビルド時にパッケージが自動的に復元されます。 コマンドラインで復元オプションを実行するビルド ステップを含めたり、任意で、ビルド テンプレートを後続のバージョンに移行したりできます。 詳細については、Team Foundation ビルドでパッケージ復元を設定する方法に関するページをご覧ください。

パッケージのバージョンを制約する

NuGet で何らかの方法で復元するとき、packages.config またはプロジェクト ファイルに指定したバージョンの制約が適用されます。

• packages.config では、依存関係に allowedVersions の範囲を指定できます。 詳細については、「アップグレード バージョンの制約」を参照してください。 次に例を示します。

  <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
  

• プロジェクト ファイルでは、依存関係の Version プロパティでバージョン範囲を指定できます。 次に例を示します。

  <PackageReference Include="Newtonsoft.json" Version="[6,7)" />
  

いずれの場合も、「パッケージのバージョン管理」で説明されている表記を使います。

リモート パッケージ ソースから強制的に復元する

グローバル パッケージとキャッシュ フォルダーの管理に関するページで説明されているように、既定では、NuGet の復元操作では、グローバル パッケージ フォルダーと HTTP キャッシュ フォルダーのパッケージを使用します。 これらのローカル パッケージを使用しないようにするには、次のオプションを使用します。

すべてのローカル キャッシュをクリアするには:

• Visual Studio で、[ツール]>[オプション]>[NuGet パッケージ マネージャー]>[全般] の [すべての NuGet キャッシュをクリア] ボタンを選択します。
• dotnet CLI の場合は、dotnet nuget locals all --clear を使用します。
• NuGet CLI の場合は、nuget locals all -clear を使用します。

グローバル パッケージ フォルダーのパッケージの使用を回避するには:

• nuget locals global-packages -clear または dotnet nuget locals global-packages --clear を使用して、フォルダーをクリアします。
• 一時的に、NUGET_PACKAGES 環境変数を別のフォルダーに設定します。
• globalPackagesFolder の PackageReference、または packages.config の repositoryPath を別のフォルダーに設定する NuGet.Config ファイルを作成します。 構成設定に関するページを参照してください。
• MSBuild のみ: RestorePackagesPath プロパティで別のフォルダーを指定する。

HTTP キャッシュのパッケージの使用を回避するには:

• nuget locals http-cache -clear または dotnet nuget locals http-cache --clear を使用してキャッシュをクリアします。
• 一時的に NUGET_HTTP_CACHE_PATH 環境変数を別のフォルダーに設定します。
• nuget restore の場合は-NoHttpCache オプションを使用し、dotnet restore の場合は --no-http-cache オプションを使用します。 これらのオプションは、Visual Studio パッケージ マネージャーまたはコンソールを経由した復元操作には影響しません。

パッケージの自動復元への移行

以前のバージョンの NuGet では、MSBuild 統合パッケージの復元がサポートされていました。 非推奨の、MSBuild に統合されたパッケージの復元を使用するプロジェクトは、パッケージの自動復元に移行してください。

これらのプロジェクトには、通常、NuGet.config、nuget.exe、NuGet.targets の 3 つのファイルを含む .nuget フォルダーが含まれています。 NuGet.targets ファイルを使用すると、NuGet は MSBuild 統合アプローチを使用するため、削除する必要があります。

パッケージの自動復元に移行するには:

1. パッケージの自動復元を有効にします。
2. Visual Studio を閉じます。
3. .nuget/nuget.exe と .nuget/NuGet.targets を削除します。
4. 各プロジェクト ファイルごとに、<RestorePackages> 要素を削除し、NuGet.targets への参照をすべて削除します。

パッケージの自動復元をテストするには:

1. ソリューションから packages フォルダーを削除します。
2. Visual Studio でソリューションを開き、ビルドを開始します。 パッケージの自動復元によって、各依存関係パッケージがダウンロードおよびインストールされ、それらがソース管理に追加されることはありません。

次のステップ

• パッケージの復元のトラブルシューティング
• グローバル パッケージ、キャッシュ、および一時フォルダーを管理する