Réinstaller et mettre à jour des packages NuGet dans Visual Studio

  • Article

Parfois, les références de package peuvent se rompre dans un projet Visual Studio. Désinstaller et réinstaller la même version du package permet parfois de restaurer les références en état de fonctionnement. La mise à jour d’un package, qui installe une version mise à jour, peut également résoudre le problème. Cet article explique comment réinstaller et mettre à jour des packages NuGet pour traiter les références de package rompues et les projets interrompus.

Remarque

Les instructions de cet article s’appliquent uniquement aux projets qui utilisent le format de gestion packages.config. Pour les projets PackageReference, une opération de restauration corrige automatiquement les références rompues.

Scénarios courants

Ci-après, vous trouverez quelques scénarios courants dans lesquels vous pourriez rencontrer des références de package rompues dans votre projet Visual Studio.

Scénario Description Résolution
Références rompues après restauration des package Vous ouvrez votre projet Visual Studio et restaurez des packages NuGet, mais les références de package rompues demeurent. Pour corriger les références, essayez de réinstaller chaque package séparément.
Projet interrompu après une suppression de fichiers Les fichiers de package supprimés (manquants) entraînent l’arrêt de votre projet. NuGet n’empêche pas la suppression d’éléments que vous ajoutez à partir de packages. Il peut être facile de modifier par inadvertance le contenu installé à partir d’un package et d’arrêter votre projet. Pour restaurer votre projet, essayez de réinstaller les packages concernés.
Projet interrompu après la mise à jour du package Une mise à jour du package interrompt votre projet. Les mises à jour complémentaires d’un package de dépendance provoquent généralement ce type de défaillance. Pour restaurer l’état de la dépendance dans son ordre de travail précédent, essayez de réinstaller le package dépendant spécifique.
Références rompues après reciblage ou mise à niveau du projet Un processus de reciblage ou de mise à niveau d’un projet provoque la rupture des références de package. Après avoir réalisé le reciblage de votre projet, NuGet affiche une erreur de build. Les avertissements de versions répertorient les packages qui doivent peut-être être réinstallés. Il est également possible qu’après la mise à niveau du projet, NuGet affiche une erreur dans le journal de mise à niveau du projet. Le fichier journal répertorie les packages qui peuvent avoir besoin d’être réinstallés. Pour résoudre les problèmes qui émanent d’un changement dans la version cible de .Net Framework, essayez de réinstaller un ou plusieurs packages.
Modifications de package en cours de développement Les auteurs de packages doivent parfois réinstaller la même version d’un package qu’ils développent afin de tester les modifications apportées. La console Gestionnaire de package NuGet de Visual Studio fournit de nombreuses options flexibles pour la mise à jour et la réinstallation des packages. Pour réinstaller un package en cours de développement, vous pouvez utiliser la commande Update-Package -reinstall.

Options d’implémentation

Vous avez plusieurs possibilités pour mettre à jour et réinstaller des packages NuGet. Les méthodes courantes incluent les options d’interface utilisateur du gestionnaire de package NuGet, la console Gestionnaire de package NuGet, et la CLI (interface de ligne de commande) NuGet.

Interface utilisateur du gestionnaire de package

En plus de l’interface de la console, l’interface utilisateur du gestionnaire de package fournit également des options de menu pour installer, mettre à jour et désinstaller des packages.

  • Pour mettre à jour un package, ouvrez l’onglet Mises à jour, choisissez un ou plusieurs packages, puis sélectionnez Mettre à jour.

  • Pour réinstaller un package, désinstallez d’abord le package, puis réinstallez-le. Ouvrez l’onglet Installé, sélectionnez un package, enregistrez son nom, puis sélectionnez Désinstaller. Basculez vers l’onglet Parcourir et recherchez le nom du package, sélectionnez-le, puis sélectionnez Installer.

Console Gestionnaire de package

Vous pouvez accéder à la console Gestionnaire de package sous Outils>Gestionnaire de package NuGet>Console Gestionnaire de package.

  • Pour mettre à jour un package, la console Gestionnaire de package fournit la commande Update-Package.

  • Pour réinstaller un package, vous pouvez utiliser la même commande avec le paramètre -reinstall. Cette approche représente l’option la plus simple, si elle est compatible avec votre configuration.

Pour plus d’informations, consultez les sections Commande de mise à jour de package et Considérations relatives à la réinstallation de packages.

CLI NuGet

La CLI NuGet est nuget.exel’utilitaire de ligne de commande de Windows qui fournit toutes les capacités NuGet.

  • Pour mettre à jour les packages installés, exécutez la commande nuget update.

  • Pour réinstaller tous les packages NuGet, supprimez le dossier du package, puis exécutez la commande nuget install.

  • Pour réinstaller un package unique, supprimez le dossier du package, puis exécutez la commande nuget install <id>, où l’argument <id> est l’ID du package spécifique.

Remarque

En ce qui concerne la CLI dotnet, la procédure équivalente n’est pas nécessaire. Lorsque vous exécutez la commande dotnet restore, la CLI dotnet utilise NuGet pour déterminer les dépendances et télécharger les packages NuGet nécessaires. Pour plus d'informations, consultez le document Restauration des packages NuGet à l’aide de la CLI dotnet.

Contraintes relatives aux versions de mise à niveau

Par défaut, la réinstallation et la mise à jour d’un package installent toujours la dernière version disponible dans la source du package. Toutefois, les projets qui utilisent le format de gestion packages.config peuvent limiter spécifiquement la plage de versions de package NuGet autorisée.

Supposons que votre application fonctionne uniquement avec la version 1.x d’un package, mais pas avec la version 2.0 ou ultérieure, en raison d’une modification majeure de l’API du package. Pour vous assurer que votre application fonctionne comme prévu, il conviendra de limiter les mises à niveau du package NuGet à la version 1.x uniquement. La limitation permet d’éviter les mises à jour accidentelles susceptibles d’interrompre votre application.

Pour définir une contrainte, ouvrez le fichier packages.config dans un éditeur de texte. Localisez la dépendance que vous souhaitez limiter et ajoutez l’attribut allowedVersions avec votre plage de versions souhaitée.

L’exemple suivant montre comment limiter les mises à jour à la version 1.x en définissant l’attribut allowedVersions sur [1,2) :

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="ExamplePackage" version="1.1.0" allowedVersions="[1,2)" />

    <!-- ... -->
</packages>

Dans tous les cas, utilisez la notation décrite dans Gestion des versions du package.

Commande de mise à jour de package

La commande de mise à jour de package dans la console Gestionnaire de package est le moyen le plus simple de réinstaller un package et d’adresser des références rompues. Toutefois, cette approche n’est pas utilisable dans tous les scénarios. Vous pouvez utiliser la commande pour mettre à jour un package installé, mais pas pour effectuer une installation initiale. Si vous essayez de mettre à jour ou réinstaller un package qui n’est pas déjà installé dans la configuration, la commande retourne une erreur. Assurez-vous de consulter la section Considérations relatives à la réinstallation du package avant d’utiliser la commande.

La mise à jour des packages d’un projet ou d’une solution à l’aide de PackageReference est toujours effectuée vers la version la plus récente du package (sauf des packages de préversion). Les projets qui utilisent le format de gestion packages.config peuvent limiter les versions de mise à jour, comme décrit ci-dessous dans Restrictions des versions de mise à niveau.

Les sections suivantes fournissent des exemples d’utilisation de la commande.

Réinstaller les options de package

Nous présentons ci-après une utilisation basique de la commande pour effectuer une réinstallation. Pour identifier un package NuGet spécifique, vous pouvez utiliser le paramètre facultatif -Id.

# Reinstall the package named <package_name>
Update-Package -Id <package_name> –reinstall

L’utilisation de la commande Update-Package est plus facile que de supprimer un package et de localiser ce même package dans la galerie NuGet avec la même version.

Mettre à jour les options de package

La même commande sans le paramètre -reinstall met à jour un package vers une version plus récente, si nécessaire. La commande retourne une erreur si le package spécifié n’est pas déjà installé dans un projet.

# Update the package named <package_name>
Update-Package <package_name>

Options des projets et des solutions

Par défaut, la commande Update-Package affecte tous les projets d’une solution. Pour limiter l’action à un projet spécifique, utilisez le paramètre -ProjectName. Indiquez le nom du projet tel qu’il apparaît dans l’explorateur de solutions Visual Studio.

La commande suivante réinstalle un package NuGet pour un projet spécifique dans votre solution. Le nom du package NuGet spécifique à réinstaller est fourni dans le paramètre <package_name>.

# Reinstall the package named <package_name> in MyProject only
Update-Package <package_name> -ProjectName MyProject -reinstall

Si vous souhaitez réinstaller tous les packages dans votre projet, utilisez le paramètre -ProjectName en ne spécifiant aucun package particulier. Vous pouvez suivre cette même approche pour mettre à jour les packages dans votre projet, comme illustré dans cet exemple :

# Update all packages in MyProject only
Update-Package -ProjectName MyProject

Pour mettre à jour tous les packages d’une solution, utilisez Update-Package tout seul, sans aucun autre argument ni paramètre.

Important

Veillez à utiliser attentivement la forme suivante de la commande. Le processus de commande peut prendre beaucoup de temps pour effectuer toutes les mises à jour.

# Update all packages in all projects in the solution
Update-Package

Considérations relatives à la réinstallation du package

Si vous envisagez d’utiliser la commande Update-Package pour réinstaller des packages, passez en revue les considérations suivantes pour garantir la compatibilité avec votre scénario de configuration.

  • Les packages et leurs dépendances peuvent ne pas prendre en charge une version cible de .Net Framework du projet reciblé.
  • Lorsque l’attribut requireReinstallation est défini sur true, Visual Studio émet des avertissements de versions pour les packages affectés.
  • La réinstallation d’un package et de contraintes de version peut introduire des problèmes de compatibilité de version de dépendance.
  • La réinstallation d’un package spécifique peut entraîner l’arrêt des packages de dépendance.

Le package ne prend pas en charge la version cible de .NET Framework du projet

Si vous reciblez la version cible de .NET Framework de votre projet, un ou plusieurs packages peuvent ne pas prendre en charge la nouvelle configuration cible.

En règle générale, la réinstallation d’un package avec l’aide de la commande Update-Package –reinstall <package_name> fonctionne. Un package installé dans une ancienne version cible de .NET Framework est désinstallé, puis installé dans la nouvelle version cible de .NET Framework du projet.

Dans certains cas, il peut arriver qu’un package ne prenne pas en charge la nouvelle version cible de .NET Framework. Nous présentons ci-dessous quelques problèmes que vous pourriez rencontrer :

  • Si un package prend en charge des bibliothèques de classes portables (SPCH) et si vous reciblez le projet vers une combinaison de plateformes qui ne sont plus prises en charge par le package, les références au package seront manquantes après la réinstallation.

  • Ce problème peut se produire pour les packages que vous utilisez directement ou pour les packages installés en tant que dépendances. Tout package que vous utilisez directement peut prendre en charge le nouveau framework cible alors que leurs dépendances ne le font pas.

  • Si la réinstallation des packages après le reciblage de votre application entraîne des erreurs de build ou de runtime, vous devrez peut-être rétablir l’ancienne version cible de .NET Framework ou chercher d’autres packages prenant en charge votre nouvelle version cible.

Attribut requireReinstallation défini sur true

Après avoir reciblé la version cible de .NET Framework de votre projet ou mis à niveau des packages NuGet, NuGet peut ajouter l’attribut requireReinstallation au fichier packages.config de votre projet. Si NuGet détecte que des packages ont été affectés lors du reciblage ou de la mise à niveau d’un projet, il ajoute un attribut requireReinstallation="true" dans packages.config pour toutes les références de package affectées. Par conséquent, chaque version suivante de votre projet dans Visual Studio déclenche des avertissements de versions pour ces packages. Les avertissements sont présentés comme rappel pour réinstaller le package concerné.

Incompatibilité de version de dépendance de package

La commande Update-Package –reinstall réinstalle la même version d’un package installé et la dernière version de toutes les dépendances. Pour résoudre les problèmes d’incompatibilité de version, vous pouvez définir des contraintes de plage de versions pour contrôler la configuration. NuGet respecte les contraintes et met à jour les dépendances de package vers des versions plus récentes uniquement si nécessaire pour résoudre un problème.

  • Si vos paramètres de contrainte entraînent un rétablissement d’une dépendance vers une version antérieure pendant la réinstallation du package, vous pouvez résoudre le problème à l’aide de la commande Update-Package <dependency_name>. Cette commande réinstalle la dépendance spécifiée sans affecter le package de dépendance.

  • Vous pouvez également utiliser la commande Update-Package –reinstall <packageName> -ignoreDependencies. Cette option permet de réinstaller la même version du package d’origine, mais ne réinstalle pas les dépendances. Utiliser cette approche lors de la mise à jour des dépendances de package peut endommager l’état des configuration.

Package dépendant rompu

Lorsque vous réinstallez un package spécifique, tous les packages installés qui dépendent du package réinstallé ne sont pas mis à jour. Les versions de ces autres packages installés restent identiques. Par conséquent, la réinstallation d’une dépendance peut interrompre un package dépendant.