Migrer de packages.config vers PackageReference

Article
03/19/2024

Visual Studio 2017 15.7 ou version ultérieure prend en charge la migration d'un projet du format de gestion packages.config vers le format PackageReference.

Avantages de l’utilisation de PackageReference

Gestion de toutes les dépendances du projet depuis un même endroit : Tout comme les références de projet à projet et les références d’assembly, les références de packages NuGet (utilisant le nœud PackageReference) sont gérées directement dans des fichiers de projet plutôt que dans un fichier packages.config distinct.
Vue épurée des dépendances de niveau supérieur : Contrairement au format packages.config, PackageReference répertorie uniquement les packages NuGet que vous avez installés directement dans le projet. Ainsi, l'interface utilisateur de NuGet Package Manager et le fichier projet ne sont pas encombrés de dépendances de niveau inférieur.
Optimisation des performances : Si le format PackageReference est utilisé, les packages sont conservés dans le dossier global-packages (comme l’explique l’article Gérer les dossiers de packages globaux et de cache) plutôt que dans un dossier packages au sein de la solution. En conséquence, PackageReference est plus rapide et consomme moins d'espace disque.
Contrôle précis des dépendances et du flux de contenu : L’utilisation des fonctionnalités existantes de MSBuild vous permet de référencer conditionnellement un package NuGet et de choisir des références de packages par version cible de .Net Framework, configuration, plate-forme ou autres pivots.

Limites

NuGet PackageReference n'est pas disponible dans Visual Studio 2015 et versions antérieures. Les projets migrés ne peuvent être ouverts que dans Visual Studio 2017 et versions ultérieures.
La migration n’est actuellement pas possible pour les projets C++ et ASP.NET.
Certains packages peuvent ne pas être entièrement compatibles avec PackageReference. Pour plus d’informations, voir la section Problèmes de compatibilité des packages.

En outre, il existe des différences dans le fonctionnement de PackageReferences par rapport à packages.config. Par exemple, Contraintes sur les versions de mise à niveau ne sont pas prises en charge par PackageReference, mais PackageReference ajoute la prise en charge des versions flottantes.

Problèmes connus

L’option Migrate packages.config to PackageReference... n’est pas disponible dans le menu contextuel

Problème

À la première ouverture d’un projet, il peut arriver que NuGet ne s’initialise pas tant qu’aucune opération NuGet n’a été réalisée. Dans ce cas, l’option de migration ne s’affiche pas dans le menu contextuel sur packages.config ou References.

Solution de contournement

Effectuez l’une des actions NuGet suivantes :

Ouvrez l’interface utilisateur du Gestionnaire de package : cliquez avec le bouton droit sur References et sélectionnez Manage NuGet Packages....
Ouvrez la console du Gestionnaire de package : dans Tools > NuGet Package Manager, sélectionnez Package Manager Console.
Exécutez la restauration NuGet : cliquez avec le bouton droit sur le nœud de la solution dans l’Explorateur de solutions, puis sélectionnez Restore NuGet Packages.
Générez le projet qui déclenche également la restauration NuGet.

L’option de migration devrait apparaître. Notez qu’elle n’est pas prise en charge et ne s’affiche pas pour les types de projets ASP.NET et C++.

Étapes de la migration

Remarque

Avant le début de la migration, Visual Studio crée une sauvegarde du projet pour vous permettre de retourner au format packages.config si nécessaire.

Ouvrez une solution contenant un projet en utilisant packages.config.
Dans Explorateur de solutions, cliquez avec le bouton droit de la souris sur le nœud Références ou sur le fichier packages.config, puis sélectionnez Migrer packages.config vers PackageReference.
Le migrateur analyse les références des packages NuGet du projet et tente de les classer dans la catégorie des dépendances de niveau supérieur (packages NuGet que vous avez installés directement) et des dépendances transitoires (packages qui ont été installés en tant que dépendances de packages de niveau supérieur).

Remarque

PackageReference prend en charge la restauration des packages transitifs et résout les dépendances de manière dynamique, ce qui signifie que les dépendances transitives n'ont pas à être installées explicitement.
(Facultatif) Vous pouvez traiter un package NuGet classé comme une dépendance transitive en tant que dépendance de niveau supérieur en sélectionnant l'option Top-Level (niveau supérieur) pour ce package. Cette option est automatiquement définie pour les packages contenant des ressources qui ne s'exécutent pas de manière transitoire (celles des dossiers build, buildCrossTargeting, contentFiles ou analyzers) et celles marquées comme des dépendances de développement (developmentDependency = "true").
Vérifiez les éventuels problèmes de compatibilité des packages.
Sélectionnez OK pour commencer la migration.
À la fin de la migration, Visual Studio fournit un rapport indiquant un chemin d'accès à la sauvegarde, la liste des packages installés (dépendances de niveau supérieur), une liste des packages référencés comme dépendances transitives, et une liste des problèmes de compatibilité identifiés au début de la migration. Le rapport est enregistré dans le dossier de sauvegarde.
Vérifiez la génération et l’exécution de la solution. Si vous rencontrez des problèmes, signalez-les sur GitHub.

Revenir à packages.config

Fermez le projet migré.
Copiez le fichier projet et packages.config de la sauvegarde (généralement <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) dans le dossier du projet. Supprimez le dossier obj s'il existe dans le répertoire racine du projet.
Ouvrez le projet.
Ouvrez la Console du Gestionnaire de package à partir de la commande de menu Outils > Gestionnaire de package NuGet > Console du Gestionnaire de package.
Exécutez la commande suivante dans la console :
```
update-package -reinstall
```

Créer un package après la migration

Une fois la migration terminée, nous vous recommandons d'ajouter une référence au package nuget nuget.build.tasks.pack, puis d'utiliser msbuild -t:pack pour créer le package. Bien que certains scénarios vous permettent d’utiliser dotnet.exe pack au lieu de msbuild -t:pack, cette méthode n'est pas recommandée.

Problèmes de compatibilité des packages

Certains aspects autrefois pris en charge dans packages.config ne le sont plus dans PackageReference. Le migrateur analyse et détecte ces problèmes. Tout package présentant un ou plusieurs des problèmes suivants risque de ne pas se comporter comme prévu après la migration.

Les scripts « install.ps1 » sont ignorés lorsque le package est installé après la migration

Description : Avec PackageReference, les scripts PowerShell install.ps1 et uninstall.ps1 ne sont pas exécutés pendant l’installation ou la désinstallation d’un package.
Impact potentiel : Les packages qui dépendent de ces scripts pour configurer certains comportements dans le projet de destination peuvent ne pas fonctionner comme prévu.

Les ressources « content » sont ignorées lorsque le package est installé après la migration

Description : Les ressources du dossier content d’un package ne sont pas prises en charge par PackageReference et sont ignorées. PackageReference ajoute la prise en charge de contentFiles pour permettre une meilleure prise en charge transitive et le partage de contenu.
impact potentiel : Les ressources dans content ne sont pas copiées dans le projet et le code de projet qui dépend de la présence de ces ressources nécessite une refactorisation.

Les transformations XDT ne sont pas appliquées lorsque le package est installé après la mise à niveau

Description : Les transformations XDT ne sont pas prises en charge avec PackageReference et les fichiers .xdt sont ignorés lors de l’installation ou de la désinstallation d’un package.
Impact potentiel : Les transformations XDT ne sont appliquées à aucun fichier XML du projet, le plus souvent, web.config.install.xdt et web.config.uninstall.xdt, ce qui signifie que le fichier web.config du projet n’est pas mis à jour lorsque le package est installé ou désinstallé.

Les assemblys à la racine de la bibliothèque sont ignorés lorsque le package est installé après la migration

Description : Avec PackageReference, les assemblys présents à la racine du dossier lib sans sous-dossier spécifique à la version cible de .Net Framework sont ignorés. NuGet recherche un sous-dossier correspondant au moniker de framework cible (TFM) pour le framework cible du projet, puis installe les assemblys correspondants dans le projet.
Impact potentiel : Les packages sans sous-dossier correspondant au moniker de framework cible (TFM) pour la version cible de .Net Framework du projet peuvent ne pas se comporter comme prévu après la transition, ou l’installation peut échouer pendant la migration.

Vous avez rencontré un problème ? Signalez-le !

Si vous rencontrez un problème avec l'expérience de migration, veuillez signaler ce problème sur le référentiel NuGet GitHub.