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

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 по сравнению с packages.config. Например, ограничение версий обновления не поддерживается в PackageReference, но PackageReference добавляет поддержку для плавающих версий.

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

  1. Параметр 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.

  1. Откройте решение, содержащее проект в формате packages.config.

  2. В обозревателе решений щелкните правой кнопкой мыши узел ссылок или файл packages.config и выберите Перенести packages.config в PackageReference... .

  3. Средство миграции выполнит анализ ссылок на пакеты NuGet проекта и попытается разделить их на зависимости верхнего уровня (пакеты NuGet, которые вы установили напрямую) и переходные зависимости (пакеты, которые были установлены как зависимости пакетов верхнего уровня).

    Примечание

    PackageReference поддерживает восстановление транзитивных пакетов и динамически разрешает зависимости, а это означает, что переходные зависимости не нужно устанавливать явно.

  4. (Необязательно.) Вы можете настроить для пакета NuGet, классифицированного как переходная зависимость, обработку в качестве зависимости верхнего уровня, выбрав для пакета параметр Верхний уровень. Этот параметр автоматически устанавливается для пакетов, содержащих ресурсы, которые не передаются транзитивно (те, которые находятся в папках build, buildCrossTargeting, contentFiles или analyzers) и помечены как зависимость времени разработки (developmentDependency = "true").

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

  6. Нажмите кнопку ОК, чтобы начать миграцию.

  7. По завершении миграции Visual Studio предоставляет отчет, содержащий путь к резервной копии, список установленных пакетов (зависимостей верхнего уровня), список пакетов, отмеченных как переходные зависимости, и список проблем совместимости, обнаруженных в начале миграции. Отчет будет сохранен в папку резервных копий.

  8. Убедитесь, что решение выполняет сборку и запуск. Если у вас возникли проблемы, сообщите о них на сайте GitHub.

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

  1. Закройте перенесенный проект.

  2. Скопируйте файл проекта и packages.config из резервной копии (обычно <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) в папку проекта. Удалите папку obj (при наличии) в корневой папке проекта.

  3. Откройте проект.

  4. Откройте консоль диспетчера пакетов с помощью команды меню Средства > Диспетчер пакетов NuGet > Консоль диспетчера пакетов.

  5. В консоли выполните следующую команду:

    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 (чаще всего web.config.install.xdt и web.config.uninstall.xdt) не применяются ни к каким XML-файлам проекта. Это означает, что файл web.config проекта не обновляется при установке или удалении пакета.

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

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

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

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

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