Преобразование packages.config в PackageReference

Статья
04/18/2023

Visual Studio 2017 версии 15.7 и более поздних поддерживает преобразование формата управления проекта с packages.config в формат PackageReference.

Преимущества использования PackageReference

Централизованное управление всеми зависимостями проекта. Как и в случае со ссылками на проекты и сборки, управление ссылками на пакеты NuGet (с помощью узла PackageReference) выполняется непосредственно в файлах проекта, а не в отдельном файле packages.config.
Неисключаемое представление зависимостей верхнего уровня: в отличие от packages.config, PackageReference перечисляет только те пакеты NuGet, которые вы установили непосредственно в проекте. В результате пользовательский интерфейс диспетчера пакетов NuGet и файл проекта не загромождены зависимостями нижнего уровня.
Улучшения производительности. При использовании PackageReference пакеты хранятся в папке global-packages (как описано в статье Управление папкой установки глобальных пакетов, кэшем и временными папками), а не в папке packages в решении. В результате PackageReference выполняется быстрее и занимает меньше дискового пространства.
Точное управление зависимостями и потоком содержимого. Использование существующих функций MSBuild позволяет условно ссылаться на пакет NuGet и выбирать ссылки на пакеты на целевую платформу, конфигурацию, платформу или другие сводные данные.

Ограничения

NuGet PackageReference недоступен в Visual Studio 2015 и более ранних версиях. Мигрированные проекты можно открыть только в Visual Studio 2017 и более поздних версиях.
На данный момент не поддерживается миграция для проектов C++ и ASP.NET.
Некоторые пакеты могут быть не полностью совместимы с PackageReference. Дополнительные сведения см.в разделе Проблемы совместимости пакетов.

Кроме того, существуют некоторые различия в работе PackageReferences по сравнению с package.config. Например, ограничения на версии обновления не поддерживаются PackageReference, но PackageReference добавляет поддержку с плавающей запятой версий.

Известные проблемы

Параметр Migrate packages.config to PackageReference... недоступен в контекстном меню, которое открывается по щелчку правой кнопкой мыши

Проблема

При первом открытии проект NuGet не удается инициализировать до выполнения операции NuGet. В результате параметр миграции не отображается в контекстном меню, которое открывается по щелчку правой кнопкой мыши packages.config или References.

Обходное решение

Выполните одно из следующих действий NuGet:

Откройте пользовательский интерфейс диспетчера пакетов. Для этого щелкните правой кнопкой мыши References и выберите Manage NuGet Packages....
Откройте консоль диспетчера пакетов. В Tools > NuGet Package Manager выберите Package Manager Console.
Запустите восстановление NuGet. Для этого щелкните правой кнопкой мыши узел решения в обозревателе решений и выберите Restore NuGet Packages.
Создайте проект, активизирующий восстановление NuGet.

Теперь параметр миграции должен отобразиться. Обратите внимание, что этот параметр не поддерживается и не будет отображаться для типов проектов ASP.NET и C++.

Шаги миграции

Примечание.

Перед началом миграции Visual Studio создает резервную копию проекта, чтобы при необходимости вы могли выполнить откат к packages.config.

Откройте решение, содержащее проект в формате packages.config.
В обозревателе решений щелкните правой кнопкой мыши узел ссылок или файл packages.config и выберите Перенести packages.config в PackageReference....
Средство миграции выполнит анализ ссылок на пакеты NuGet проекта и попытается разделить их на зависимости верхнего уровня (пакеты NuGet, которые вы установили напрямую) и переходные зависимости (пакеты, которые были установлены как зависимости пакетов верхнего уровня).

Примечание.

PackageReference поддерживает восстановление транзитивных пакетов и динамически разрешает зависимости, а это означает, что переходные зависимости не нужно устанавливать явно.
(Необязательно.) Вы можете настроить для пакета NuGet, классифицированного как переходная зависимость, обработку в качестве зависимости верхнего уровня, выбрав для пакета параметр Верхний уровень. Этот параметр автоматически устанавливается для пакетов, содержащих ресурсы, которые не передаются транзитивно (те, которые находятся в папках build, buildCrossTargeting, contentFiles или analyzers) и помечены как зависимость времени разработки (developmentDependency = "true").
Просмотрите все проблемы совместимости пакетов.
Нажмите кнопку ОК, чтобы начать миграцию.
По завершении миграции Visual Studio предоставляет отчет, содержащий путь к резервной копии, список установленных пакетов (зависимостей верхнего уровня), список пакетов, отмеченных как переходные зависимости, и список проблем совместимости, обнаруженных в начале миграции. Отчет будет сохранен в папку резервных копий.
Убедитесь, что решение выполняет сборку и запуск. Если у вас возникли проблемы, сообщите о них на сайте GitHub.

Выполнение отката к packages.config

Закройте перенесенный проект.
Скопируйте файл проекта и packages.config из резервной копии (обычно <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) в папку проекта. Удалите папку obj (при наличии) в корневой папке проекта.
Откройте проект.
Откройте консоль диспетчера пакетов с помощью команды меню Средства > Диспетчер пакетов NuGet > Консоль диспетчера пакетов.
В консоли выполните следующую команду:
```
update-package -reinstall
```

Создание пакета после миграции

После завершения миграции рекомендуем добавить ссылку на пакет NuGet nuget.build.tasks.pack, а затем с помощью msbuild -t:pack создать пакет. В некоторых случаях вы можете использовать dotnet.exe pack вместо msbuild -t:pack, однако это не рекомендуется.

Проблемы совместимости пакетов

Некоторые функции, поддерживаемые в package.config, не поддерживаются в PackageReference. Средство миграции анализирует и обнаруживает такие проблемы. Любой пакет с одной или несколькими из описанных ниже проблем может неправильно работать после миграции.

При установке пакета после миграции сценарии install.ps1 игнорируются

Описание. При использовании PackageReference сценарии PowerShell install.ps1 и uninstall.ps1 не выполняются во время установки или удаления пакета.
Возможные последствия. Пакеты, которые используют эти сценарии для настройки определенных действий в целевом проекте, могут не работать должным образом.

При установке пакета после миграции ресурсы content недоступны

Описание. Использование PackageReference с ресурсами в папке content пакета не поддерживается, и эти ресурсы пропускаются. PackageReference добавляет поддержку для contentFiles, обеспечивая лучший уровень транзитивности и общий доступ к содержимому.
Возможные последствия. Ресурсы из content не копируются в проект, а код проекта, который зависит от наличия этих ресурсов, требует рефакторинга.

При установке пакета после обновления преобразования XDT не применяются

Описание. Использование XDT-преобразований с PackageReference не поддерживается, и при установке или удалении пакета файлы .xdt пропускаются.
Потенциальное влияние: преобразования XDT не применяются к XML-файлам проекта, чаще всего, web.config.install.xdt и web.config.uninstall.xdtэто означает, что файл проекта web.config не обновляется при установке или удалении пакета.

При установке пакета после миграции сборки в корне lib игнорируются

Описание. При использовании PackageReference сборки, находящиеся в корне папки lib без определенной подпапки целевой платформы, будут пропускаться. NuGet ищет подпапку, соответствующую моникеру целевой платформы (TFM) с учетом целевой платформы проекта, и устанавливает необходимые сборки в проект.
Возможные последствия. Пакеты без подпапки, соответствующей моникеру целевой платформы (TFM) для целевой платформы проекта, могут не работать ожидаемым образом после перехода, или их установка завершится сбоем во время миграции.

Столкнулись с проблемой? Сообщите о ней.

Если у вас возникла проблема с миграцией, сообщите о ней в репозиторий NuGet на сайте GitHub.