パッケージの復元Package Restore

開発環境をいっそうクリーンにしてリポジトリのサイズを減らすため、NuGet のパッケージの復元では、プロジェクト ファイルまたは packages.configのいずれかに一覧表示されたすべてのプロジェクトの依存関係をインストールします。To promote a cleaner development environment and to reduce repository size, NuGet Package Restore installs all a project's dependencies as listed in either the project file or packages.config. Visual Studio では、プロジェクトがビルドされるときに、パッケージを自動的に復元できます。Visual Studio can restore packages automatically when a project is built. dotnet build および dotnet run コマンド (.NET Core 2.0 以降) でも、自動復元を実行します。The dotnet build and dotnet run commands (.NET Core 2.0+) also perform an automatic restore. また、Visual Studio、nuget restoredotnet restore、および Mono の xbuild を利用すると、パッケージをいつでも復元できます。You can also restore packages at any time through Visual Studio, nuget restore, dotnet restore, and xbuild on Mono.

パッケージの復元によって、ソース コントロール内にそれらのパッケージを格納しなくても、確実にすべてのプロジェクトの依存関係が使用できるようになります。Package restore makes sure that all a project's dependencies are available without storing those packages in source control. パッケージ バイナリを除外するようにリポジトリを構成する方法については、パッケージとソースの管理に関するページをご覧ください。See Packages and Source Control on how to configure your repository to exclude package binaries.

パッケージの復元の概要Package restore overview

パッケージの復元では、最初に、必要に応じて、プロジェクトの直接的な依存関係がインストールされます。この後、依存関係グラフ全体にパッケージの依存関係がインストールされます。Restoring packages first installs the direct dependencies of a project as needed, then installs any dependencies of those packages throughout the entire dependency graph.

パッケージがまだインストールされていない場合、NuGet は最初に、パッケージをキャッシュからのパッケージの取得を試みます。If a package is not already installed, NuGet first attempts to retrieve it from the cache. パッケージがキャッシュにない場合、NuGet は有効なすべてのソースからパッケージをダウンロードしようとします (「Configuring NuGet behavior」(NuGet の動作を構成する) を参照してください。ソースは Visual Studio の [ツール] > [オプション] > [NuGet パッケージ マネージャー] > [パッケージ ソース] リストにも表示されます)。If the package is not in the cache, NuGet then attempts to download the package from all enabled sources (see Configuring NuGet behavior; sources also appear in the Tools > Options > NuGet Package Manager > Package Sources list in Visual Studio). 復元時には、NuGet は、要求に最初に応答するソースのパッケージを使用して、パッケージ ソースの順序を無視します。During restore, NuGet ignores the order of package sources, using the package from whichever source is first to respond to requests.

注意

NuGet では、すべてのソースがチェックされるまで、パッケージの復元の失敗が表示されません。NuGet does not indicate a failure to restore a package until all the sources have been checked. このとき、NuGet では一覧の最後のソースについてのみ障害が報告されます。At that time, NuGet reports a failure for only the last source in the list. このエラーは、ソースごとに個別にエラーが表示されていなくても、パッケージが他のソースのいずれにも存在しないことを意味します。The error implies that the package wasn't present on any of the other sources, even though errors are not shown for each of those sources individually.

パッケージの復元は、次の方法でトリガーされます。Package restore is triggered in the following ways:

  • dotnet CLI: dotnet restore コマンドを使用します。このコマンドは、プロジェクト ファイルに列記されたパッケージを復元します (「PackageReference」 を参照してください)。dotnet CLI: use the dotnet restore command, which restores packages listed in the project file (see PackageReference). .NET Core 2.0 以降では、復元は、dotnet builddotnet run で自動的に実行されます。With .NET Core 2.0 and later, restore is done automatically with dotnet build and dotnet run.

  • パッケージ マネージャー UI (Windows 上の Visual Studio): プロジェクトは、テンプレートから作成されとき、およびビルドされたときに自動的に復元されます (ただし、「パッケージの復元の有効化と無効化」で説明するオプションに基づきます)。Package Manager UI (Visual Studio on Windows): Packages are restored automatically when creating a project from a template and when building a project (subject to the option described in Enabling and disabling package restore). NuGet 4.0 以降では、NET Core SDK ベースのプロジェクトを変更した場合も復元が自動的に発生します。In NuGet 4.0+, restore also happens automatically when changes are made to a .NET Core SDK-based project.

    手動で復元するには、ソリューション エクスプローラーでソリューションを右クリックして、[NuGet パッケージの復元] を選択します。To restore manually, right-click the solution in Solution Explorer and select Restore NuGet Packages. 1 つ以上の個別のパッケージが、まだ適切にインストールされない場合 (ソリューション エクスプローラーにエラー アイコンが表示されます)、パッケージ マネージャー UI を使用して、影響を受けるパッケージをアンインストールし、再インストールします。If one or more individual packages are still not installed properly (meaning that Solution Explorer shows an error icon), then use the Package Manager UI to uninstall and reinstall the affected packages. パッケージの再インストールと更新」を参照してください。See Reinstalling and updating packages

    "このプロジェクトは、このコンピューター上にない NuGet パッケージを参照しています" または "1 つ以上の NuGet パッケージを復元する必要がありますが、同意が与えられていないため、復元できませんでした" というエラーが表示される場合は、「パッケージの復元の有効化と無効化」の手順に従って、自動復元を有効にしてください。If you see the error "This project references NuGet package(s) that are missing on this computer" or "One or more NuGet packages need to be restored but couldn't be because consent has not been granted," turn on automatic restore by following the instructions under Enabling and disabling package restore. パッケージの復元のトラブルシューティングに関するページもご覧ください。Also see Package restore troubleshooting.

  • NuGet CLI: nuget restore コマンドを使用します。このコマンドは、プロジェクト ファイルまたは packages.configに列記されたパッケージを復元します。NuGet CLI: use the nuget restore command, which restores packages listed in the project file or in packages.config. ソリューション ファイルを指定することもできます。You can also specify a solution file.

  • MSBuild: msbuild -t:restore コマンドを使用します。このコマンドは、プロジェクト ファイル (PackageReference のみ) に列記されたパッケージを復元します。MSBuild: use the msbuild -t:restore command, which restores packages packages listed in the project file (PackageReference only). NuGet 4.x 以降および MSBuild 15.1 以降でのみ使用できます。これらは、Visual Studio 2017 に含まれています。Available only in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017. nuget restoredotnet restore はどちらも、このコマンドを該当するプロジェクトに使います。nuget restore and dotnet restore both use this command for applicable projects.

  • Visual Studio Team Services: Team Services でビルド定義を作成する場合、ビルド タスクの前に、NuGet の復元 タスクまたは .NET Core の復元タスクが定義に追加されます。Visual Studio Team Services: When creating a build definition on Team Services, include the NuGet restore or .NET Core Restore task in the definition before any build task. このタスクは、多くのビルド テンプレートに既定で含まれます。This task is included by default in a number of build templates.

  • Team Foundation Server: TFS 2013 以降では、TFS 2013 以降用のチーム ビルド テンプレートを使用していれば、ビルド時にパッケージが自動的に復元されます。Team Foundation Server: TFS 2013 and later automatically restores packages during build, provided that you're using a Team Build Template for TFS 2013 or later. 以前のバージョンの TFS では、前に説明したように、ビルド ステップを含めるだけでコマンド ラインの復元オプションのいずれかを呼び出すことができます。For earlier version of TFS, you can include a build step to invoke one of the command-line restore options above. 必要に応じて、ビルド テンプレートを TFS 2013 に移行できます。You can optionally migrate the build template to TFS 2013. 詳細については、Team Foundation ビルドでのパッケージの復元に関するチュートリアルをご覧ください。For more information, see the Walkthrough of package restore with Team Foundation Build.

パッケージの復元の有効化と無効化Enabling and disabling package restore

パッケージの復元を有効にするには、主に Visual Studio の [ツール] > [オプション] > [NuGet パッケージ マネージャー] を使います。Package restore is primarily enabled through Tools > Options > NuGet Package Manager in Visual Studio:

NuGet パッケージ マネージャーのオプションによるパッケージ復元動作の制御

  • 見つからないパッケージのダウンロードを NuGet に許可: 次に示すように、NuGet.Config ファイル (Windows では %AppData%\NuGet\NuGet.Config、Mac/Linux では ~/.nuget/NuGet/NuGet.Config) の packageRestore/enabled の設定を変更することによって、パッケージ復元のすべての形式を制御します。Allow NuGet to download missing packages: controls all forms of package restore by changing the packageRestore/enabled setting in the NuGet.Config file as shown below (%AppData%\NuGet\NuGet.Config on Windows, ~/.nuget/NuGet/NuGet.Config on Mac/Linux). Visual Studio では、この設定を使用して、ソリューションのコンテキスト メニューの [NuGet パッケージの復元] コマンドを実行できるようになります。In Visual Studio, this setting allows the Restore NuGet Packages command on the solution's context menu to work.

    <configuration>
        <packageRestore>
            <!-- The 'enabled' key is True when the "Allow NuGet to download missing packages" checkbox is set.
                 Clearing the box sets this to False, disabling command-line, automatic, and MSBuild-Integrated restore. -->
            <add key="enabled" value="True" />
        </packageRestore>
    </configuration>
    

注意

packageRestore/enabled の設定は、Visual Studio の起動前またはビルドの開始前に環境変数 EnableNuGetPackageRestore の値を TRUE または FALSE に設定することにより、グローバルにオーバーライドできます。The packageRestore/enabled setting can be overridden globally by setting an environment variable called EnableNuGetPackageRestore with a value of TRUE or FALSE before launching Visual Studio or starting a build.

  • Visual Studio でのビルド中に見つからないパッケージを自動的に確認: 次に示すように、NuGet.Config ファイル (Windows では %AppData%\NuGet\NuGet.Config、Mac/Linux では ~/.nuget/NuGet/NuGet.Config) の packageRestore/automatic 設定を変更することにより、自動復元を制御します。Automatically check for missing packages during build in Visual Studio: controls automatic restore by changing the packageRestore/automatic setting in the NuGet.Config file as shown below (%AppData%\NuGet\NuGet.Config on Windows, ~/.nuget/NuGet/NuGet.Config on Mac/Linux). このオプションをオンにして Visual Studio からビルドを実行すると、欠落しているパッケージが自動的に復元されます。When this option is set, running a build from Visual Studio automatically restores any missing packages. このオプションは、MSBuild を使用してコマンド ラインから実行されるビルドには影響しません。The option does not affect builds run from the command line using MSBuild.

    ...
    <configuration>
        <packageRestore>
            <!-- The 'automatic' key is set to True when the "Automatically check for missing packages during
                 build in Visual Studio" checkbox is set. Clearing the box sets this to False and disables
                 automatic restore. -->
            <add key="automatic" value="True" />
        </packageRestore>
    </configuration>
    

詳しくは、「NuGet config file」(NuGet config ファイル) の「packageRestore section」(packageRestore セクション) をご覧ください。For reference, see the NuGet config file - packageRestore section.

開発者や会社が、すべてのユーザーに対して、コンピューターでのパッケージの復元を有効または無効にすることが必要になる場合があります。In some cases, a developer or company might want to enable or disable package restore for all users on a computer. これを行うには、%ProgramData%\NuGet\Config (Windows、潜在的に Visual Studio 用の特定の \{IDE}\{Version}\{SKU}\ フォルダー下にある) または ~/.local/share (Mac/Linux) に配置されているグローバル NuGet 構成ファイルに上記の同じ設定を追加します。To do this, add the same settings above to the global NuGet configuration file located in %ProgramData%\NuGet\Config (Windows, potentially under a specific \{IDE}\{Version}\{SKU}\ folder for Visual Studio) or ~/.local/share (Mac/Linux). その場合、個々のユーザーは、必要に応じてプロジェクト レベルで選択的に復元を有効にできます。Individual users can then selectively enable restore as needed on a project level. NuGet が複数の構成ファイルの優先順位を決定する方法の詳細については、「NuGet の動作を構成する」をご覧ください。See Configuring NuGet behavior for exact details on how NuGet prioritizes multiple config files.

重要

nuget.configpackageRestore 設定を直接編集する場合は、オプションのダイアログ ボックスに現在の値が表示されるように Visual Studio を再起動します。If you edit the packageRestore settings directly in nuget.config, restart Visual Studio so that the options dialog box shows the current values.

復元でのパッケージのバージョンの制約Constraining package versions with restore

NuGet は、いずれかの方法でパッケージを復元する際、packages.configまたはプロジェクト ファイルで指定されている制約に従います。When restoring packages through any method, NuGet honors any constraints specified in packages.config or the project file:

  • packages.config: 依存関係の allowedVersion プロパティでバージョンの範囲を指定します。packages.config: Specify a version range in the allowedVersion property of the dependency. パッケージの再インストールと更新」をご覧ください。See Reinstalling and updating packages. 例:For example:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
    
  • プロジェクト ファイル (PackageReference): 依存関係のバージョン番号でバージョンの範囲を直接指定します。Project file (PackageReference): Specify a version range directly with the dependency's version number. 例:For example:

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

いずれの場合も、「Package versioning」(パッケージのバージョン管理) で説明されている表記を使います。In all cases, use the notation described in Package versioning.

パッケージ ソースから強制的に復元するForcing restore from package sources

グローバル パッケージとキャッシュ フォルダーの管理に関するページで説明されているように、既定では、NuGet の復元操作では、"グローバル パッケージ" および "HTTP キャッシュ" フォルダーのパッケージを使用します。By default, NuGet restore operations use packages from the global-packages and http-cache folders, which are described on Managing the global packages and cache folders.

"グローバル パッケージ" フォルダーの使用を回避するには、次のいずれかの操作を行います。To avoid using the global-packages folder, do one of the following:

  • nuget locals global-packages -clear または dotnet nuget locals global-packages --clear を使用して、フォルダーをクリアするClear the folder using nuget locals global-packages -clear or dotnet nuget locals global-packages --clear
  • 次のいずれかの方法を使った復元操作の前に、"グローバル パッケージ" フォルダーの場所を一時的に変更するTemporarily change the location of the global-packages folder before the restore operation using one of the following methods:
    • NUGET_PACKAGES 環境変数を別のフォルダーに設定する。Set the NUGET_PACKAGES environment variable to a different folder.
    • globalPackagesFolder (PackageReference を使用している場合) または repositoryPath (packages.config を使用している場合) を別のフォルダーに設定した NuGet.Config ファイルを作成する (構成設定に関するページを参照してください)。Create a NuGet.Config file that sets globalPackagesFolder (if using PackageReference) or repositoryPath (if using packages.config) to a different folder (see configuration settings
    • MSBuild のみ: RestorePackagesPath プロパティで別のフォルダーを指定する。MSBuild only: specify a different folder with the RestorePackagesPath property.

HTTP ソースのキャッシュの使用を回避するには、次のいずれかの操作を行います。To avoid using the cache for HTTP sources, do one of the following:

  • nuget restore-NoCache オプションを使用するか、または dotnet restore--no-cache オプションを使用する。Use the -NoCache option with nuget restore or the --no-cache option with dotnet restore. これらのオプションは、Visual Studio パッケージ マネージャーの UI またはコンソールを経由した復元操作には影響しません。These options do not affect restore operations through the Visual Studio Package Manager UI or Console.
  • nuget locals http-cache -clear または dotnet nuget locals http-cache --clear を使用してキャッシュをクリアする。Clear the cache using nuget locals http-cache -clear or dotnet nuget locals http-cache --clear.
  • 一時的に、NUGET_HTTP_CACHE_PATH 環境変数を別のフォルダーに設定する。Temporarily set of the NUGET_HTTP_CACHE_PATH environment variable to a different folder.

トラブルシューティングTroubleshooting

パッケージの復元のトラブルシューティングに関するページを参照してください。See Troubleshooting package restore.