Восстановление пакетов с помощью восстановления пакетов NuGet

Восстановление пакетов NuGet восстанавливает все зависимости проекта, перечисленные в файле проекта или в packages.config. Пакеты можно восстановить вручную с помощью nuget restore, dotnet restore или msbuild -t:restore, или с помощью Visual Studio. Команды dotnet build и dotnet run автоматически восстанавливают пакеты, и вы можете настроить Visual Studio для автоматического восстановления пакетов при сборке проекта.

Чтобы повысить уровень более чистой среды разработки и уменьшить размер репозитория, восстановление пакетов делает все зависимости проекта доступными без необходимости хранить их в системе управления версиями. Сведения о настройке репозитория системы управления версиями для исключения двоичных файлов пакетов см. в разделе "Пакеты" и "Управление версиями".

Поведение восстановления пакета

Восстановление пакетов пытается установить все зависимости пакета в состояние, соответствующее <PackageReference>s в файле проекта, например CSPROJ или <package>s в файлеpackages.config . Восстановление пакета сначала устанавливает прямые зависимости проекта по мере необходимости, а затем устанавливает все зависимости этих пакетов на протяжении всего графа зависимостей.

Если необходимый пакет еще не установлен, NuGet сначала пытается получить его из локальных глобальных пакетов или папок кэша HTTP. Если пакет не в локальных папках, NuGet пытается загрузить его из всех источников, настроенных в Visual Studio в параметрах Tools>Options>Диспетчера пакетов NuGet>Источники пакетов.

Во время восстановления NuGet игнорирует порядок источников пакетов и использует пакет из первого источника, который отвечает на запросы. Если восстановление завершается ошибкой, NuGet не указывает на сбой до тех пор, пока не будет выполнена проверка всех источников. Затем NuGet сообщает об ошибке только для последнего источника в списке. Ошибка подразумевает, что пакет не был представлен ни в одном из источников, даже если он не перечисляет другие ошибки по отдельности.

Дополнительные сведения о поведении NuGet см. в разделе "Общие конфигурации NuGet".

Восстановление пакетов

Если ссылки на пакеты в файле проекта или packages.config файле верны, используйте предпочитаемое средство для восстановления пакетов:

• Visual Studio
• dotnet CLI
• CLI nuget.exe
• MSBuild
• Azure Pipelines или Azure DevOps Server

После успешного восстановления:

• Для проектов, использующих <PackageReference>, пакет присутствует в локальной папке глобальных пакетов , а файл проекта obj/project.assets.json повторно создается.
• Для проектов, использующих packages.config, пакет отображается в папке пакетов проекта.
• Теперь проект должен успешно выполнить сборку.

Если ссылки на пакет в файле проекта или файле packages.config неверны и не соответствуют требуемому состоянию, установите или обновите правильные пакеты вместо использования восстановления пакетов.

Если после запуска восстановления пакетов отсутствуют пакеты или ошибки, связанные с пакетом, например значки ошибок в обозревателе решений, следуйте инструкциям в разделе "Устранение ошибок восстановления пакетов" или переустановите или обновите пакеты. В Visual Studio консоль диспетчера пакетов предоставляет несколько вариантов переустановки пакетов. Дополнительные сведения см. в разделе "Использование пакета-обновления".

Восстановление пакетов в Visual Studio

В Visual Studio в Windows можно автоматически восстанавливать пакеты или вручную. Сначала настройте восстановление пакетов через Инструменты>Параметры>Диспетчер пакетов NuGet.

Настройка параметров восстановления пакетов Visual Studio

Настройте следующие параметры восстановления пакетов в разделе Инструменты>Параметры>Диспетчер пакетов NuGet>Общие.

Разрешить NuGet скачивать отсутствующие пакеты

Выберите Разрешить NuGet скачать отсутствующие пакеты , чтобы включить восстановление пакетов и команду "Восстановить пакеты NuGet ". Этот выбор задает packageRestore/enabled параметр True в разделе packageRestore глобального файла NuGet.Config по адресу%AppData%\Roaming\NuGet в Windows или ~/.nuget/NuGet/ на Mac или Linux.

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

Чтобы включить или отключить восстановление пакетов для всех пользователей на компьютере, можно добавить параметры конфигурации в глобальный файл NuGet.Config в Windows%ProgramData% \NuGet\Config, иногда в определенной <папке IDE>\Version<\><SKU> Visual Studio или в Mac/Linux в ~/.local/share. Затем отдельные пользователи могут выборочно включить восстановление по мере необходимости на уровне проекта. Дополнительные сведения о том, как NuGet определяет приоритеты нескольких файлов конфигураций конфигурации NuGet, см. в разделе "Общие конфигурации NuGet".

Автоматическая проверка отсутствия пакетов во время сборки

Выберите автоматически проверить наличие отсутствующих пакетов во время сборки в Visual Studio , чтобы автоматически восстановить отсутствующие пакеты при запуске сборки из Visual Studio. Этот параметр не влияет на сборки, выполняемые из командной строки MSBuild. Этот параметр packageRestore/automatic устанавливается в значение True в разделе packageRestore файла NuGet.Config.

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

Чтобы включить восстановление пакетов во время сборки, необходимо выбрать Разрешить NuGet скачать отсутствующие пакеты , а также автоматически проверить наличие отсутствующих пакетов во время сборки в Visual Studio в параметрах , чтобы включить восстановление пакетов во время сборки.

Выбор формата управления пакетами по умолчанию

NuGet имеет два формата управления пакетами, PackageReference и packages.config. Выберите формат, который вы хотите использовать в раскрывающемся списке в разделе "Управление пакетами". Вы также можете выбрать, следует ли разрешить выбор формата при первой установке пакета.

Восстановление пакетов вручную или автоматически

После включения восстановления пакета в параметрах можно щелкнуть решение правой кнопкой мыши в обозревателе решений и выбрать команду "Восстановить пакеты NuGet " для восстановления пакетов в любое время.

Если вы включили автоматическое восстановление в параметрах, восстановление пакетов происходит автоматически при создании проекта из шаблона или сборки проекта. Для NuGet 4.0 и более поздних версий восстановление также происходит автоматически при внесении изменений в проект стиля SDK.

Для проектов, которые используют<PackageReference>, можно просмотреть ссылки на пакеты в обозревателе решений Visual Studio в разделе Зависимости>Пакеты. Пакеты, которые не устанавливаются должным образом при ручном восстановлении или сборке, отображают значки ошибок в Обозревателе решений. Щелкните проект правой кнопкой мыши, выберите "Управление пакетами NuGet" и используйте диспетчер пакетов NuGet для удаления и переустановки затронутых пакетов. Дополнительные сведения см. в разделе "Переустановка и обновление пакетов".

Если вы увидите ошибку , когда проект ссылается на пакеты NuGet, отсутствующие на этом компьютере, или необходимо восстановить один или несколько пакетов NuGet, но не удалось, так как согласие не было предоставлено, убедитесь, что вы включили автоматическое восстановление. Сведения о старых проектах см. в разделе "Миграция на автоматическое восстановление пакетов". Также см. Устранение ошибок восстановления пакета.

Восстановление с помощью dotnet CLI

Команда dotnet restore восстанавливает пакеты, перечисленные в <PackageReference>файле проекта. Дополнительные сведения см. в разделе PackageReference в файлах проекта.

.NET Core 2.0 и более поздних версий автоматически восстанавливают пакеты с помощью команд dotnet build и dotnet run. По состоянию на NuGet 4.0, dotnet restore выполняет тот же код, что и nuget restore.

Восстановление пакета с помощью dotnet restore:

1. Откройте командную строку и перейдите в каталог, содержащий файл проекта.
2. Выполните dotnet restore.

Восстановление с помощью интерфейса командной строки NuGet

Команда восстановления Интерфейса командной строки NuGet скачивает и устанавливает отсутствующие пакеты. Команда работает над проектами, которые используют PackageReference или packages.config для ссылок на пакеты.

Например install, restore команда добавляет только пакеты на диск, но не изменяет файл проекта или packages.config. Чтобы добавить зависимости проекта, используйте пользовательский интерфейс или консоль диспетчера пакетов Visual Studio.

Чтобы восстановить пакеты, выполните следующую команду:

nuget restore <projectPath>

Команда restore использует файл решения или файл package.config в указанном пути проекта.

Например, чтобы восстановить все пакеты для MySolution.sln в текущем каталоге, выполните следующую команду:

nuget restore MySolution.sln

Восстановление с помощью MSBuild

Вы можете использовать msbuild -t:restore для восстановления пакетов в NuGet 4.x+ и MSBuild 15.1+, которые включены в Visual Studio 2017 и более поздних версий.

Эта команда восстанавливает пакеты в проектах, использующих PackageReference для ссылок на пакеты. Начиная с MSBuild 16.5+, команда также поддерживает packages.config ссылки на пакеты при использовании -p:RestorePackagesConfig=true.

Чтобы использовать восстановление MSBuild, выполните приведенные действия.

1. Откройте Developer Command Prompt, найдя его в меню Windows «Пуск», это настроит все необходимые пути для MSBuild.

2. Перейдите в папку проекта и введите msbuild -t:restore.

3. После завершения восстановления введите msbuild для перестроения проекта. Убедитесь, что выходные данные MSBuild указывают на успешное завершение сборки.

Восстановление с помощью Azure Pipelines или Azure DevOps Server

При создании определения сборки в Azure Pipelines вы можете включить задачу восстановления с помощью NuGet CLI или dotnet CLI перед выполнением любых задач сборки. Некоторые шаблоны сборки включают задачу восстановления по умолчанию.

Azure DevOps Server и TFS 2013 и более поздних версий автоматически восстанавливают пакеты во время сборки, если вы используете шаблон сборки команды TFS 2013 или более поздней версии. Можно также включить шаг сборки для запуска параметра восстановления командной строки или при необходимости перенести шаблон сборки в более позднюю версию. Дополнительные сведения см. в разделе "Настройка восстановления пакета с помощью Team Foundation Build".

Ограничение версий пакетов

Восстановление 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-cache , как описано в разделе "Управление глобальными пакетами и папками кэша". Чтобы избежать использования этих локальных пакетов, используйте следующие параметры.

Чтобы очистить все локальные кэши, выполните приведенные действия.

• В Visual Studio выберите кнопку «Очистить все кэши NuGet» в разделе Сервис>Параметры>Диспетчер пакетов NuGet>Общие.
• В интерфейсе командной строки dotnet используйте dotnet nuget locals all --clear.
• В интерфейсе командной строки NuGet используйте nuget locals all -clear.

Чтобы избежать использования пакетов в папке глобальных пакетов , выполните следующие действия.

• Очистите папку с помощью nuget locals global-packages -clear или dotnet nuget locals global-packages --clear.
• Временно задайте переменную среды NUGET_PACKAGES в другую папку.
• Создайте файл NuGet.Config, который задает globalPackagesFolder для PackageReference или repositoryPath для packages.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 с тремя файлами: NuGet.config, nuget.exeи NuGet.targets. Файл NuGet.targets приводит к тому, что NuGet использует интегрированный с MSBuild подход, поэтому его необходимо удалить.

Чтобы выполнить миграцию на автоматическое восстановление пакетов, выполните приведенные далее действия.

1. Включите автоматическое восстановление пакета.
2. Закройте Visual Studio.
3. Удалите nuget/nuget.exe и .nuget/NuGet.targets.
4. Для каждого файла проекта удалите <RestorePackages> элемент и удалите все ссылки на NuGet.targets.

Чтобы проверить автоматическое восстановление пакета, выполните приведенные действия.

1. Удалите папку пакетов из решения.
2. Откройте решение в Visual Studio и запустите сборку. Автоматическое восстановление пакетов должно скачать и установить каждый пакет зависимостей, не добавляя его в управление версиями.

Дальнейшие шаги

• Устранение неполадок при восстановлении пакета
• Управление глобальными пакетами, кэшем и временными папками