Restaurer des packages grâce à la restauration de package NuGet

  • Article

La restauration des packages NuGet restaure toutes les dépendances d’un projet répertoriées dans un fichier projet ou un fichier packages.config. Vous pouvez restaurer manuellement des packages avec nuget restore, dotnet restore, msbuild -t:restore ou via Visual Studio. Les commandes dotnet build et dotnet run restaurent automatiquement les packages, et vous pouvez configurer Visual Studio de sorte à restaurer automatiquement les packages lorsqu’il génère un projet.

Pour promouvoir un environnement de développement propre et réduire la taille du référentiel, la restauration de package rend toutes les dépendances d’un projet disponibles sans avoir à les stocker dans le contrôle de code source. Pour configurer votre référentiel de contrôle de code source afin d’exclure les binaires des packages, consultez Packages et contrôle de code source.

Comportement de restauration de package

La restauration du package tente d’installer toutes les dépendances de package dans l’état correspondant aux <PackageReference> dans un fichier projet .csproj ou aux <package> dans un fichier packages.config. La restauration des packages installe tout d’abord les dépendances directes nécessaires d’un projet, puis toutes les dépendances du graphe des dépendances de ces packages.

Si un package souhaité n’est pas déjà installé, NuGet essaie d’abord de le récupérer à partir du cache des dossiers locaux des packages universels ou HTTP. Si le package ne se trouve pas dans les dossiers locaux, NuGet tente de le télécharger à partir de toutes les sources configurées dans Visual Studio sous Outils>Options>Gestionnaire de package NuGet>Package.

Lors de la restauration, NuGet ignore l’ordre des sources de packages et utilise le package provenant de la première source qui répond aux requêtes. Si la restauration échoue, NuGet n’indique pas l’échec tant qu’il n’a pas vérifié toutes les sources. NuGet ne signale de défaillance que pour la dernière source de la liste. L’erreur implique que le package n’était présent sur aucune des sources, même s’il ne répertorie pas les autres échecs individuellement.

Pour plus d’informations sur le comportement de NuGet, consultez Configurations courantes de NuGet.

Restaurer des packages

Si les références du package dans votre fichier projet ou packages.config sont correctes, utilisez votre outil préféré pour restaurer les packages :

Après une restauration réussie :

  • Pour les projets qui utilisent <PackageReference>, le package est présent dans le dossier local global-packages et le fichier de projet obj/project.assets.json est recréé.
  • Pour les projets qui utilisent packages.config, le package apparaît dans le dossier packages du projet.
  • Le projet doit à présent être généré.

Si les références de package dans votre fichier projet ou votre fichier packages.config sont incorrectes et ne correspondent pas à l’état que vous souhaitez, installez ou mettez à jour les bons packages plutôt que d’utiliser la restauration de packages.

Si vous avez des packages manquants ou rencontrez des erreurs liées aux packages, comme des icônes d’erreur dans l’Explorateur de solutions, suivez les instructions fournies dans Résolution des erreurs de restauration des packages ou bien réinstallez et mettez à jour les packages. Dans Visual Studio, la console Gestionnaire de package fournit plusieurs options pour la réinstallation des packages. Pour plus d’informations, consultez Mise à jour des packages.

Restaurer des packages avec Visual Studio

Dans Visual Studio sur Windows, vous pouvez restaurer des packages automatiquement ou manuellement. Configurez d’abord la restauration de package dans Outils>Options>Gestionnaire de package NuGet.

Configurer les options de restauration de package Visual Studio

Configurez les options de restauration de package suivantes dans Outils>Options>Gestionnaire de package NuGet>Général.

Screenshot that shows the NuGet Package Manager options.

Autoriser NuGet à télécharger les packages manquants

Sélectionnez Autoriser NuGet à télécharger les packages manquants pour activer la restauration de package et la commande Restaurer les packages NuGet. Cette sélection définit le paramètre packageRestore/enabled sur True dans la section packageRestore du fichier NuGet.Config global, sur %AppData%\Roaming\NuGet sur Windows ou ~/.nuget/NuGet/ sur Mac ou Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Remarque

Pour remplacer le paramètre packageRestore/enabled globalement, vous pouvez définir la variable d’environnement EnableNuGetPackageRestore sur True ou False avant d’ouvrir Visual Studio ou de démarrer une build.

Pour activer ou désactiver la restauration de package pour tous les utilisateurs sur un ordinateur, vous pouvez ajouter les paramètres de configuration au fichier NuGet.Config global dans Windows sur %ProgramData%\NuGet\Config, parfois dans un dossier Visual Studio <IDE>\<Version>\<SKU> spécifique, ou dans Mac/Linux sur ~/.local/share. Chaque utilisateur peut ensuite activer la restauration au niveau d’un projet, si nécessaire. Pour plus d’informations sur la façon dont NuGet hiérarchise les fichiers de configuration, consultez Configurations courantes de NuGet.

Important

Si vous modifiez les paramètres packageRestore directement dans NuGet.Config, redémarrez Visual Studio pour que Options affiche les valeurs actuelles.

Vérifier automatiquement les packages manquants pendant la génération

Sélectionnez Vérifier automatiquement les packages manquants pendant la génération dans Visual Studio pour restaurer automatiquement les packages manquants lorsque vous exécutez une build à partir de Visual Studio. Ce paramètre ne s’applique pas aux builds exécutées à partir de la ligne de commande MSBuild. Cette sélection définit le paramètre packageRestore/automatic sur True dans la section packageRestore du fichier NuGet.Config.

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Pour les projets de style non SDK, vous devez sélectionner Autoriser NuGet à télécharger des packages manquants, ainsi que Vérifier automatiquement les packages manquants pendant la génération dans Visual Studio dans Options pour activer la restauration automatique.

Choisir le format de gestion de package par défaut

NuGet a deux formats de gestion de package, PackageReference et packages.config. Sélectionnez le format que vous souhaitez utiliser dans la liste déroulante sous Gestionnaire de package. Vous pouvez également choisir d’autoriser la sélection de format lors de la première installation du package.

Remarque

  • Si un projet ne prend pas en charge les deux formats de gestion de package, NuGet utilise le format de gestion de package compatible avec le projet, ce qui peut ne pas être la valeur par défaut que vous définissez dans les options. NuGet ne demandera pas de sélection lors de la première installation, même si vous avez sélectionné cette option.

  • Si vous utilisez la console du Gestionnaire de package pour installer le premier package dans un projet, NuGet ne demande pas de sélectionner de format, même si cette option est sélectionnée dans Options.

Restaurer des packages manuellement ou automatiquement

Après avoir activé la restauration des packages dans Options, vous pouvez faire un clic droit sur la solution dans Explorateur de solutions et sélectionner Restaurer des packages NuGet pour restaurer des packages à tout moment.

Si vous avez activé la restauration automatique dans Options, la restauration des packages est automatique quand vous créez un projet à partir d’un modèle ou que vous générez un projet. Pour NuGet 4.0+, la restauration se produit également automatiquement quand vous modifiez un projet de style SDK.

Pour les projets qui utilisent <PackageReference>, vous pouvez voir les références de package dans Explorateur de solutions de Visual Studio sous Dépendances>Packages. Les packages qui ne s’installent pas correctement lorsque vous restaurez ou exécutez manuellement une build affichent des icônes d’erreur dans Explorateur de solutions. Cliquez avec le bouton droit sur le projet, sélectionnez Gérer les packages NuGet et utilisez le Gestionnaire de package NuGet pour désinstaller et réinstaller les packages souhaités. Pour plus d’informations, consultez Réinstaller et mettre à jour des packages.

Si vous voyez l’erreur Ce projet référence un ou plusieurs packages NuGet qui sont introuvables sur cet ordinateur ou l’erreur Un ou plusieurs packages NuGet doivent être restaurés mais n’ont pas pu l’être, car le consentement n’a pas été octroyé, assurez-vous que la restauration automatique est activée. Pour les projets plus anciens, consultez Migrer vers la restauration automatique des packages. Consultez également Résolution des erreurs de restauration des packages.

Restaurer à l’aide de l’interface CLI dotnet

La commande dotnet restore restaure les packages que les fichier projet référencent comme <PackageReference>. Pour plus d’informations, consultez PackageReference dans les fichiers projet.

Dans .NET Core 2.0 et versions ultérieures, les commandes dotnet build et dotnet run restaurent les packages automatiquement. À partir de NuGet 4.0, dotnet restore exécute le même code que nuget restore.

Pour restaurer un package à l’aide de dotnet restore :

  1. Ouvrez une ligne de commande et accédez au répertoire contenant votre fichier projet.
  2. Exécutez dotnet restore.

Important

Pour ajouter une référence de package manquant au fichier projet, utilisez le package dotnet add, qui exécute également restore.

Restaurer à l’aide de l’interface CLI NuGet

La commande de restauration de l’interface CLI NuGet télécharge et installe les packages manquants. La commande fonctionne sur les projets qui utilisent PackageReference ou packages.config pour les références de package.

Comme install, la commande restore ajoute uniquement des packages au disque. Elle ne modifie pas le fichier projet ou packages.config. Pour ajouter des dépendances de projet, utilisez l’interface utilisateur du Gestionnaire de package de Visual Studio ou la console du gestionnaire de package.

Pour restaurer les packages, exécutez la commande suivante :

nuget restore <projectPath>

La commande restore utilise un fichier solution ou un fichier package.config dans le chemin d’accès du projet spécifié.

Par exemple, pour restaurer tous les packages de MySolution.sln dans le répertoire actif, exécutez :

nuget restore MySolution.sln

Remarque

Pour les projets de style non SDK qui utilisent PackageReference, utilisez msbuild -t:restore pour restaurer des packages à la place.

Restaurer à l’aide de MSBuild

Vous pouvez utiliser msbuild -t:restore pour restaurer des packages dans NuGet 4.x+ et MSBuild 15.1+, qui sont inclus dans Visual Studio 2017 et versions ultérieures.

Cette commande restaure les packages dans les projets qui utilisent PackageReference pour les références de package. À compter de MSBuild 16.5+, la commande prend également en charge les références de package packages.config, lorsqu’elles sont utilisées avec -p:RestorePackagesConfig=true.

Pour utiliser la restauration MSBuild :

  1. Ouvrez une invite de commandes développeur en recherchant l’invite de commandes développeur et en démarrant l’invite à partir du menu Démarrer de Windows, qui configure tous les chemins d’accès nécessaires pour MSBuild.

  2. Basculez vers le dossier du projet, puis saisissez msbuild -t:restore.

  3. Une fois la restauration terminée, saisissez msbuild pour reconstruire le projet. Assurez-vous que la sortie MSBuild indique que la génération s’est terminée avec succès.

Remarque

Vous pouvez utiliser msbuild -restore pour exécuter restore, recharger le projet et générer, car la build est la cible par défaut. Pour plus d’informations, consultez Restaurer et générer avec une commande MSBuild.

Restaurer avec Azure Pipelines ou Azure DevOps Server

Lorsque vous créez une définition de build dans Azure Pipelines, vous pouvez inclure la tâche de restauration de l’interface CLI NuGet ou la tâche restauration dotnet CLI dans la définition avant de lancer des tâches de build. Certains modèles de build incluent la tâche restore par défaut.

Azure DevOps Server et TFS 2013 et ultérieur restaurent automatiquement les packages au moment de la build, si vous utilisez un modèle Team Build de TFS 2013 ou ultérieur. Vous pouvez également inclure une étape de build qui exécute une option de restauration en ligne de commande, ou éventuellement migrer le modèle de build vers une version ultérieure. Pour plus d’informations, consultez Configurer la restauration de packages avec Team Foundation Build.

Limiter les versions du package

La restauration NuGet s’effectue avec l’une des méthodes et respecte toutes les contraintes de version que vous avez spécifiées dans packages.config ou dans le fichier projet.

  • Dans packages.config, vous pouvez spécifier une plage allowedVersions dans la dépendance. Pour plus d’informations, consultez Contraintes sur les versions de mise à niveau. Par exemple :

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • Dans un fichier projet, vous pouvez spécifier une plage de versions dans la propriété Version de la dépendance. Par exemple :

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

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

Forcer la restauration à partir de sources de packages distantes

Par défaut, les opérations de restauration NuGet utilisent des packages provenant des dossiers global-packages et http-cache locaux, comme décrits dans Gérer les dossiers de packages globaux et de cache. Pour éviter d’utiliser ces packages locaux, utilisez les options suivantes.

Pour effacer tous les caches locaux :

  • Dans Visual Studio, sélectionnez le bouton Effacer tous les caches NuGet dans Outils>Options>Gestionnaire de package NuGet>Général.
  • Dans l’interface CLI dotnet, utilisez dotnet nuget locals all --clear.
  • Dans l’interface CLI NuGet, utilisez nuget locals all -clear.

Pour éviter d’utiliser les packages dans le dossier global-packages :

  • Effacez le dossier en utilisant nuget locals global-packages -clear ou dotnet nuget locals global-packages --clear.
  • Définissez temporairement la variable d’environnement NUGET_PACKAGES sur un autre dossier.
  • Créez un fichier NuGet.Config qui définit globalPackagesFolder pour PackageReference, ou repositoryPath pour packages.config, dans un autre dossier. Pour plus d’informations, consultez les paramètres de configuration.
  • Uniquement pour MSBuild : spécifiez un autre dossier avec la propriété RestorePackagesPath.

Pour éviter d’utiliser des packages dans le cache HTTP :

  • Effacez le cache en utilisant nuget locals http-cache -clear ou dotnet nuget locals http-cache --clear.
  • Définissez temporairement la variable d’environnement NUGET_HTTP_CACHE_PATH sur un autre dossier.
  • Pour nuget restore, utilisez l’option -NoHttpCache ou pour dotnet restore, utilisez l’option --no-http-cache. Ces options ne s’appliquent pas aux opérations de restauration effectuées par le biais de la console ou du Gestionnaire de package dans Visual Studio.

Migrer vers la restauration automatique des packages

Les versions antérieures de NuGet ont pris en charge une restauration de package intégrée à MSBuild. Les projets qui utilisent la restauration de packages intégrée MSBuild dépréciée doivent migrer vers la restauration automatique des packages.

Ces projets contiennent généralement un dossier .nuget avec trois fichiers : NuGet.config, nuget.exe et NuGet.targets. Le fichier NuGet.targets force NuGet à utiliser l’approche intégrée MSBuild, il doit donc être supprimé.

Pour migrer vers la restauration automatique des packages :

  1. Activez la restauration automatique du package.
  2. Fermez Visual Studio.
  3. Supprimez .nuget/nuget.exe et .nuget/NuGet.targets.
  4. Pour chaque fichier projet, supprimez l’élément <RestorePackages> et supprimez toute référence à NuGet.targets.

Pour tester la restauration automatique des packages :

  1. Supprimez le dossier packages de la solution.
  2. Ouvrez la solution dans Visual Studio et démarrez une build. La restauration automatique des packages doit télécharger et installer chaque package de dépendances, sans les ajouter au contrôle de code source.

Étapes suivantes