Restaurer des packages avec la restauration de package NuGet
NuGet Package Restore restaure toutes les dépendances d’un projet répertoriées dans un fichier projet ou un fichier packages.config . Vous pouvez restaurer des packages manuellement avecnuget restore
, dotnet restore
msbuild -t:restore
ou via Visual Studio. Les dotnet build
commandes et dotnet run
les commandes restaurent automatiquement les packages, et vous pouvez configurer Visual Studio pour restaurer automatiquement les packages lorsqu’il génère un projet.
Pour promouvoir un environnement de développement plus 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 pour exclure des fichiers binaires de package, consultez Packages et contrôle de code source.
Comportement de restauration de package
La restauration de package tente d’installer toutes les dépendances de package à l’état correspondant aux <PackageReference>
éléments d’un fichier projet, tels que .csproj ou <package>
s 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 nécessaire n’est pas déjà installé, NuGet tente d’abord de le récupérer à partir des packages globaux locaux ou des dossiers de cache HTTP. Si le package n’est pas dans les dossiers locaux, NuGet tente de le télécharger à partir de toutes les sources configurées dans Visual Studio at Tools>Options>NuGet Package Manager>Sources.
Lors de la restauration, NuGet ignore l’ordre des sources de package et utilise le package à partir de la première source qui répond aux demandes. Si la restauration échoue, NuGet n’indique pas l’échec tant qu’après avoir vérifié toutes les sources. NuGet signale ensuite un échec pour la dernière source de la liste. L’erreur implique que le package n’a pas été présent sur l’une 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 NuGet courantes.
Restaurer des packages
Si les références de package dans votre fichier projet ou packages.config fichier sont correctes, utilisez votre outil préféré pour restaurer des packages :
- Visual Studio
- Interface CLI .NET
- Interface CLI de nuget.exe
- MSBuild
- Azure Pipelines ou Azure DevOps Server
Après une restauration réussie :
- Pour les projets qui utilisent
<PackageReference>
, le package est présent dans le dossier global-packages local, et le fichier project obj/project.assets.json est recréé. - Pour les projets qui utilisent packages.config, le package apparaît dans le dossier des 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 à votre état souhaité, installez ou mettez à jour les packages appropriés au lieu d’utiliser la restauration de package.
Si vous avez manquant des packages ou des erreurs liées au package après l’exécution de la restauration de package, telles que les icônes d’erreur dans Explorateur de solutions, suivez les instructions de résolution des erreurs de restauration de package, ou réinstallez ou mettez à jour les packages. Dans Visual Studio, la console gestionnaire de package fournit plusieurs options pour réinstaller des packages. Pour plus d’informations, consultez Utiliser Package-Update.
Restaurer des packages dans Visual Studio
Dans Visual Studio sur Windows, vous pouvez restaurer automatiquement ou manuellement des packages. Tout d’abord, configurez la restauration de package par le biaisdes options>d’outils>Du Gestionnaire de package NuGet.
Configurer les options de restauration de package Visual Studio
Configurez les options de restauration de package suivantes à l’adresse Outils Options>>NuGet Package Manager>General.
Autoriser NuGet à télécharger des packages manquants
Sélectionnez Autoriser NuGet à télécharger des packages manquants pour activer la restauration de package et la commande Restaurer les packages NuGet . Cette sélection définit le packageRestore/enabled
paramètre dans True
la section packageRestore du fichier globalNuGet.Config , à l’adresse %AppData%\Roaming\NuGet sur Windows ou ~/.nuget/NuGet/ sur Mac ou Linux.
<configuration>
<packageRestore>
<add key="enabled" value="True" />
</packageRestore>
</configuration>
Notes
Pour remplacer globalement le packageRestore/enabled
paramètre, 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 globalNuGet.Config dans Windows à %ProgramData%\NuGet\Config, parfois sous un dossier IDE>\<Version>\<SKU> Visual Studio spécifique<, ou dans Mac/Linux à ~/.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 packageRestore
paramètres de NuGet.Config directement, redémarrez Visual Studio afin que les options affichent les valeurs actuelles.
Vérifier automatiquement les packages manquants pendant la génération
Sélectionnez Rechercher automatiquement les packages manquants pendant la build 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 packageRestore/automatic
paramètre dans True
la packageRestore
section 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 qu’à rechercher automatiquement les packages manquants pendant la génération dans Visual Studio dans Options pour activer la restauration automatique.
Choisir le format de gestion des packages 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 Gestion des packages. Vous pouvez également sélectionner s’il faut autoriser la sélection de format lors de la première installation du package.
Notes
Si un projet ne prend pas en charge les deux formats de gestion de package, NuGet utilise le format de gestion des packages compatible avec le projet, ce qui peut ne pas être la valeur par défaut que vous définissez dans les options. NuGet n’invite pas à sélectionner 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 n’invite pas à sélectionner la sélection de format, même si cette option est sélectionnée dans Options.
Restaurer manuellement ou automatiquement des packages
Après avoir activé la restauration de package dans Options, vous pouvez cliquer avec le bouton 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 de package se produit automatiquement lorsque vous créez un projet à partir d’un modèle ou générez un projet. Pour NuGet 4.0+, la restauration se produit également automatiquement lorsque vous apportez des modifications à un projet de style SDK.
Pour les projets qui utilisent<PackageReference>
, vous pouvez voir les références de package dans Visual Studio Explorateur de solutions sous Packages de dépendances>. Packages qui ne s’installent pas correctement lorsque vous restaurez ou exécutez manuellement des icônes d’erreur d’affichage de build dans Explorateur de solutions. Cliquez avec le bouton droit sur le projet, sélectionnez Gérer les packages NuGet, puis utilisez le Gestionnaire de package NuGet pour désinstaller et réinstaller les packages affectés. Pour plus d’informations, consultez Réinstaller et mettre à jour des packages.
Si vous voyez l’erreur que ce projet référence le ou les packages NuGet manquants sur cet ordinateur, ou un ou plusieurs packages NuGet doivent être restaurés, mais ne peuvent pas être car le consentement n’a pas été accordé, assurez-vous que vous avez activé la restauration automatique. Pour les projets plus anciens, consultez Migrer vers la restauration automatique des packages. Consultez également Résolution des erreurs de restauration de package.
Restaurer à l’aide de l’interface CLI dotnet
La commande dotnet restore restaure les packages avec utilisant les listes <PackageReference>
de fichiers projet. Pour plus d’informations, consultez PackageReference dans les fichiers projet.
.NET Core 2.0 et versions ultérieures dotnet build
et dotnet run
les commandes restaurent automatiquement les packages. À partir de NuGet 4.0, dotnet restore
exécute le même code que nuget restore
.
Pour restaurer un package avec dotnet restore
:
- Ouvrez une ligne de commande et accédez au répertoire contenant votre fichier projet.
- Exécutez
dotnet restore
.
Important
Pour ajouter une référence de package manquante au fichier projet, utilisez dotnet add package, qui s’exécute restore
également.
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 des projets qui utilisent PackageReference ou packages.config pour les références de package.
Comme install
, la restore
commande ajoute uniquement des packages au disque, mais ne modifie pas le fichier projet ou packages.config. Pour ajouter des dépendances de projet, utilisez l’interface utilisateur ou la console du Gestionnaire de package Visual Studio.
Pour restaurer des packages, exécutez la commande suivante :
nuget restore <projectPath>
La restore
commande utilise un fichier de solution ou un fichier package.config dans le chemin d’accès du projet spécifié.
Par exemple, pour restaurer tous les packages pour MySolution.sln dans le répertoire actuel, exécutez :
nuget restore MySolution.sln
Notes
Pour les projets de style non SDK qui utilisent PackageReference
, utilisez msbuild -t:restore pour restaurer les 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 packagepackages.config , lorsqu’elle est utilisée avec -p:RestorePackagesConfig=true
.
Pour utiliser la restauration MSBuild :
Ouvrez une invite de commandes développeur en recherchant l’invite de commandes développeur et en commençant l’invite à partir du menu Démarrer de Windows, qui configure tous les chemins nécessaires pour MSBuild.
Basculez vers le dossier du projet, puis entrez
msbuild -t:restore
.Une fois la restauration terminée, entrez
msbuild
pour reconstruire le projet. Vérifiez que la sortie MSBuild indique que la build s’est terminée correctement.
Notes
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 de restauration dotnet CLI dans la définition avant toutes les tâches de génération. Certains modèles de build incluent la tâche restore par défaut.
Azure DevOps Server et TFS 2013 et versions ultérieures restaurent automatiquement les packages pendant la build, si vous utilisez un modèle TFS 2013 ou version ultérieure. Vous pouvez également inclure une étape de génération pour exécuter une option de restauration de ligne de commande ou migrer éventuellement 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 via n’importe quelle méthode respecte les contraintes de version que vous spécifiez dans packages.config ou le fichier projet.
Dans packages.config, vous pouvez spécifier une
allowedVersions
plage dans la dépendance. Pour plus d’informations, consultez Limiter 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 la plage de versions dans la
Version
propriété de la dépendance. Par exemple :<PackageReference Include="Newtonsoft.json" Version="[6,7)" />
Dans les deux cas, utilisez la notation décrite dans le contrôle de version du package.
Forcer la restauration à partir de sources de package distantes
Par défaut, les opérations de restauration NuGet utilisent des packages à partir des packages globaux locaux et des dossiers http-cache , comme décrit dans Gérer les packages globaux et les dossiers 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 tout le ou les caches NuGet dans Le Gestionnaire > depackage NuGetoptions des>outils>.
- 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 à l’aide
nuget locals global-packages -clear
oudotnet 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
pourPackageReference
, ourepositoryPath
pour packages.config, sur un autre dossier. Pour plus d’informations, consultez les paramètres de configuration. - Pour MSBuild uniquement, spécifiez un autre dossier avec la
RestorePackagesPath
propriété.
Pour éviter d’utiliser des packages dans le cache HTTP :
- Effacez le cache à l’aide
nuget locals http-cache -clear
oudotnet 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-NoCache
ou pourdotnet restore
, utilisez l’option--no-cache
. Ces options n’affectent pas les opérations de restauration via le Gestionnaire de package Visual Studio ou la console.
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 package intégrée à MSBuild déconseillé doivent migrer vers la restauration automatique des packages.
Ces projets contiennent généralement un dossier .nuget avec trois fichiers : NuGet.config, nuget.exeet NuGet.targets. Le fichier NuGet.targets entraîne l’utilisation de l’approche intégrée à MSBuild. Il doit donc être supprimé.
Pour migrer vers la restauration automatique des packages :
- Activez la restauration automatique du package.
- Fermez Visual Studio.
- Supprimez .nuget/nuget.exe et .nuget/NuGet.targets.
- Pour chaque fichier projet, supprimez l’élément
<RestorePackages>
et supprimez les références à NuGet.targets.
Pour tester la restauration automatique des packages :
- Supprimez le dossier packages de la solution.
- Ouvrez la solution dans Visual Studio et démarrez une build. La restauration automatique du package doit télécharger et installer chaque package de dépendance, sans l’ajouter au contrôle de code source.