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 restoremsbuild -t:restoreou 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:

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 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 :

1. 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.

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

3. 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 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, 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 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 -NoCache ou pour dotnet 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 :

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 les références à 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 du package doit télécharger et installer chaque package de dépendance, sans l’ajouter au contrôle de code source.

Étapes suivantes

• Résoudre les problèmes de restauration de package
• Gérer les packages globaux, le cache et les dossiers temporaires