Миграция из packages.config в PackageReference

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

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

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

Ограничения

• Пакет 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++.

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

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

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

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

   Замечание

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

4. (Необязательно) Вы можете рассматривать пакет NuGet, классифицируемый как транзитивную зависимость, как зависимость верхнего уровня, выбрав параметр верхнего уровня для пакета. Этот параметр автоматически устанавливается для пакетов, содержащих ресурсы, которые не перетекают транзитивно (те, в которых есть build, buildCrossTargetingcontentFilesили 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
   

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

После завершения миграции рекомендуется скопировать метаданные пакета из .nuspec файла в свойства MSBuild, а затем msbuild -t:pack использовать для создания пакета. Если вы используете Visual Studio 2022 или более ранних версий, вам также потребуется установить пакет NuGet.Build.Tasks.Pack. Из Visual Studio 2026 пакет встроен в MSBuild.

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

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

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

• Описание. При использовании PackageReference install.ps1 и uninstall.ps1 скрипты PowerShell не выполняются при установке или удалении пакета.

• Потенциальное влияние: пакеты, зависящие от этих скриптов, для настройки некоторых действий в целевом проекте могут не работать должным образом.

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

• Описание. Ресурсы в папке пакета content не поддерживаются в PackageReference и игнорируются. PackageReference добавляет поддержку contentFiles для повышения поддержки транзитивности и совместного контента.

• Потенциальное влияние: активы в content не копируются в проект, и код проекта, который зависит от присутствия этих активов, требует рефакторинга.

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

• Описание. Преобразования XDT не поддерживаются в PackageReference и .xdt файлы игнорируются при установке или удалении пакета.

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

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

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

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

Обнаружена проблема? Сообщите об этом!

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