Migrer de packages.config vers PackageReference

Visual Studio 2017 Version 15.7 et ultérieure prend en charge la migration d’un projet du format de gestionpackages.config au format PackageReference .

Avantages de l’utilisation de PackageReference

• Gérez toutes les dépendances de projet à un seul endroit : tout comme les références de projet à projet et les références d’assembly, les références de package NuGet (à l’aide du PackageReference nœud) sont gérées directement dans les fichiers projet plutôt que d’utiliser un fichier de packages.config distinct.
• Vue non détaillée des dépendances de niveau supérieur : contrairement à packages.config, PackageReference répertorie uniquement les packages NuGet que vous avez installés directement dans le projet. Par conséquent, l’interface utilisateur du Gestionnaire de package NuGet et le fichier projet ne sont pas encombrés de dépendances de bas niveau.
• Améliorations des performances : lors de l’utilisation de PackageReference, les packages sont conservés dans le dossier global-packages (comme décrit dans La gestion des packages globaux et des dossiers de cache plutôt que dans un packages dossier dans la solution. Par conséquent, PackageReference effectue plus rapidement 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 package par framework cible, configuration, plateforme ou d’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 disponible pour les projets C++ et ASP.NET.
• Certains packages peuvent ne pas être entièrement compatibles avec PackageReference. Pour plus d’informations, consultez les problèmes de compatibilité des packages.

En outre, il existe des différences dans la façon dont PackageReferences fonctionne par rapport à packages.config. Par exemple, les 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

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

Problème

Lorsqu’un projet est ouvert pour la première fois, NuGet n’a peut-être pas initialisé tant qu’une opération NuGet n’est pas effectuée. Cela entraîne le non-affichage de l'option de migration dans le menu contextuel lors d'un clic droit sur packages.config ou References.

Contournement

Effectuez l’une des actions NuGet suivantes :

• Ouvrir l’interface utilisateur du Gestionnaire de package - Cliquez avec le bouton droit sur References et sélectionnez Manage NuGet Packages...
• Ouvrir la console du Gestionnaire de paquets - À partir de Tools > NuGet Package Manager, sélectionnez Package Manager Console
• Exécuter la restauration NuGet - Cliquez avec le bouton droit sur le nœud de solution dans l’Explorateur de solutions, puis sélectionnez Restore NuGet Packages
• Générer le projet qui déclenche également la restauration NuGet

Vous devez maintenant être en mesure de voir l’option de migration. Notez que cette option n’est pas prise en charge et ne s’affiche pas pour les types de projet ASP.NET et C++.

Étapes de migration

1. Ouvrez une solution contenant un projet à l’aide de packages.config.

2. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud Références ou le packages.config fichier, puis sélectionnez Migrer packages.config vers PackageReference....

3. Le migration analyse les références de package NuGet du projet et tente de les classer en dépendances de niveau supérieur (packages NuGet que vous avez installés directement) et les dépendances transitives (packages installés en tant que dépendances de packages de niveau supérieur).

   Note

   PackageReference prend en charge la restauration de package transitive et résout dynamiquement les dépendances, ce qui signifie que les dépendances transitives n’ont pas besoin d’être installées explicitement.

4. (Facultatif) Vous pouvez choisir de traiter un package NuGet classé comme une dépendance transitive en tant que dépendance de niveau supérieur en sélectionnant l’option de niveau supérieur pour le package. Cette option est automatiquement définie pour les packages contenant des ressources qui ne circulent pas de manière transitive (celles figurant dans les build, buildCrossTargeting, contentFiles, ou analyzers dossiers) et celles qui sont marquées comme une dépendance de développement (developmentDependency = "true").

5. Passez en revue les problèmes de compatibilité des packages.

6. Sélectionnez OK pour commencer la migration.

7. À la fin de la migration, Visual Studio fournit un rapport avec un chemin d’accès à la sauvegarde, la liste des packages installés (dépendances de niveau supérieur), une liste de packages référencés en tant que dépendances transitives et une liste de problèmes de compatibilité identifiés au début de la migration. Le rapport est enregistré dans le dossier de sauvegarde.

8. Vérifiez que la solution génère et s’exécute. Si vous rencontrez des problèmes, créez un problème sur GitHub.

Comment revenir à packages.config

1. Fermez le projet migré.

2. Copiez le fichier projet et packages.config à partir de la sauvegarde (généralement <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) vers le dossier du projet. Supprimez le dossier obj s’il existe dans le répertoire racine du projet.

3. Ouvrez le projet.

4. Ouvrez la console du Gestionnaire de packages à l’aide de la commande de menu Outils > Gestionnaire de packages NuGet > Console du gestionnaire de packages.

5. 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 de copier les métadonnées de votre package à partir d’un .nuspec fichier vers les propriétés MSBuild, puis vous pouvez l’utiliser msbuild -t:pack pour créer le package. Si vous utilisez Visual Studio 2022 ou version antérieure, vous devez également installer le package NuGet.Build.Tasks.Pack. À partir de Visual Studio 2026, le pack est intégré à MSBuild.

Problèmes de compatibilité des packages

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

Les scripts d'installation "install.ps1" sont ignorés lorsque le paquet est installé après la migration.

• Description : Avec PackageReference, install.ps1 et uninstall.ps1 scripts PowerShell ne sont pas exécutés lors de l’installation ou de la désinstallation d’un package.

• Impact potentiel : les packages qui dépendent de ces scripts pour configurer un comportement dans le projet de destination peuvent ne pas fonctionner comme prévu.

Les ressources « content » ne sont pas disponibles lorsque le package est installé après la migration

• Description : les ressources dans le dossier d’un content package ne sont pas prises en charge avec PackageReference et sont ignorées. PackageReference améliore la prise en charge de contentFiles pour offrir une meilleure prise en charge transitive et du contenu partagé.

• Impact potentiel : Les ressources dans content ne sont pas copiées dans le projet, et le code du 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 .xdt les fichiers 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 de projet, le plus souvent web.config.install.xdt et web.config.uninstall.xdt, ce qui signifie que le fichier du web.config projet n’est pas mis à jour lorsque le package est installé ou désinstallé.

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

• Description : Avec PackageReference, les assemblys présents à la racine du lib dossier sans sous-dossier spécifique au framework cible sont ignorés. NuGet recherche un sous-dossier correspondant au moniker du framework cible (TFM) correspondant à l’infrastructure cible du projet et installe les assemblies correspondants dans le projet.

• Impact potentiel : les packages qui n’ont pas de sous-dossier correspondant au moniker de framework cible (TFM) correspondant à l’infrastructure cible du projet peuvent ne pas se comporter comme prévu après la transition ou l’échec de l’installation pendant la migration.

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

Si vous rencontrez un problème avec l’expérience de migration, veuillez signaler un problème dans le dépôt GitHub NuGet.