Restauration des packagesPackage Restore

Pour promouvoir un environnement de développement plus propre et réduire la taille du référentiel, la fonctionnalité de restauration de package de NuGet installe toutes les dépendances d’un projet telles qu’elles sont listées dans le fichier projet ou packages.config.To promote a cleaner development environment and to reduce repository size, NuGet Package Restore installs all a project's dependencies as listed in either the project file or packages.config. Visual Studio peut restaurer les packages automatiquement à la génération d’un projet.Visual Studio can restore packages automatically when a project is built. Les commandes dotnet build et dotnet run (.NET Core 2.0+) effectuent également une restauration automatique.The dotnet build and dotnet run commands (.NET Core 2.0+) also perform an automatic restore. Vous pouvez aussi restaurer les packages à tout moment avec Visual Studio, nuget restore, dotnet restore et xbuild sur Mono.You can also restore packages at any time through Visual Studio, nuget restore, dotnet restore, and xbuild on Mono.

La restauration de package permet de garantir la disponibilité de toutes les dépendances d’un projet sans stocker les packages dans le contrôle de code source.Package restore makes sure that all a project's dependencies are available without storing those packages in source control. Consultez la page Packages et contrôle de code source pour savoir comment configurer votre référentiel de façon à exclure les binaires des packages.See Packages and Source Control on how to configure your repository to exclude package binaries.

Présentation de la restauration de packagePackage restore overview

La restauration de package installe tout d’abord les dépendances directes nécessaires d’un projet, puis toutes les dépendances du graphique de dépendance de ces packages.Restoring packages first installs the direct dependencies of a project as needed, then installs any dependencies of those packages throughout the entire dependency graph.

Si un package n’est pas déjà installé, NuGet essaie d’abord de le récupérer à partir du cache.If a package is not already installed, NuGet first attempts to retrieve it from the cache. Si le package ne se trouve pas dans le cache, NuGet tente de le télécharger à partir de toute les sources activées (consultez la page Configurer le comportement de NuGet ; les sources apparaissent également dans la liste Outils > Options > Gestionnaire de package NuGet > Sources de packages dans Visual Studio).If the package is not in the cache, NuGet then attempts to download the package from all enabled sources (see Configuring NuGet behavior; sources also appear in the Tools > Options > NuGet Package Manager > Package Sources list in Visual Studio). Lors de la restauration, NuGet ignore l’ordre des sources de packages et utilise le package provenant de la première source à répondre aux requêtes.During restore, NuGet ignores the order of package sources, using the package from whichever source is first to respond to requests.

Notes

NuGet n’indique pas l’échec de la restauration d’un package tant que toutes les sources n’ont pas été vérifiées.NuGet does not indicate a failure to restore a package until all the sources have been checked. À ce stade, NuGet ne signale de défaillance que pour la dernière source de la liste.At that time, NuGet reports a failure for only the last source in the list. L’erreur implique que le package ne se trouvait dans aucune autre source, même si les erreurs ne sont pas affichées pour chacune de ces sources.The error implies that the package wasn't present on any of the other sources, even though errors are not shown for each of those sources individually.

La restauration du package est déclenchée comme suit :Package restore is triggered in the following ways:

  • Interface CLI dotnet : utilisez la commande dotnet restore, qui restaure les packages répertoriés dans le fichier projet (consultez PackageReference).dotnet CLI: use the dotnet restore command, which restores packages listed in the project file (see PackageReference). Avec .NET Core 2.0 et versions ultérieures, la restauration est effectuée automatiquement avec dotnet build et dotnet run.With .NET Core 2.0 and later, restore is done automatically with dotnet build and dotnet run.

  • Interface utilisateur du Gestionnaire de package (Visual Studio sous Windows) : les packages sont automatiquement restaurés lors de la création d’un projet à partir d’un modèle et lors de la création d’un projet (selon l’option décrite dans Activation et désactivation de la restauration des packages).Package Manager UI (Visual Studio on Windows): Packages are restored automatically when creating a project from a template and when building a project (subject to the option described in Enabling and disabling package restore). Dans NuGet 4.0+, la restauration se produit également automatiquement lorsque des modifications sont apportées à un projet basé sur le kit SDK .NET Core.In NuGet 4.0+, restore also happens automatically when changes are made to a .NET Core SDK-based project.

    Pour effectuer une restauration manuelle, cliquez avec le bouton droit sur la solution dans l’Explorateur de solutions puis sélectionnez Restaurer des packages NuGet.To restore manually, right-click the solution in Solution Explorer and select Restore NuGet Packages. Si un ou plusieurs packages individuels ne sont toujours pas installés correctement (comme en témoigne une icône d’erreur dans l’Explorateur de solutions), utilisez l’interface utilisateur du Gestionnaire de package pour désinstaller puis réinstaller les packages affectés.If one or more individual packages are still not installed properly (meaning that Solution Explorer shows an error icon), then use the Package Manager UI to uninstall and reinstall the affected packages. Consultez Réinstallation et mise à jour des packages.See Reinstalling and updating packages

    Si vous voyez l’erreur « Ce projet fait référence à des packages NuGet qui sont manquants 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é », activez la restauration automatique en suivant les instructions de la section Activation et désactivation de la restauration des packages.If you see the error "This project references NuGet package(s) that are missing on this computer" or "One or more NuGet packages need to be restored but couldn't be because consent has not been granted," turn on automatic restore by following the instructions under Enabling and disabling package restore. Consultez également la page Résolution des problèmes de restauration de package.Also see Package restore troubleshooting.

  • Interface CLI NuGet : utilisez la commande nuget restore, qui restaure les packages listés dans le fichier projet ou dans packages.config.NuGet CLI: use the nuget restore command, which restores packages listed in the project file or in packages.config. Vous pouvez également spécifier un fichier solution.You can also specify a solution file.

  • MSBuild : utilisez la commande msbuild -t:restore, qui restaure les packages listés dans le fichier projet (PackageReference uniquement).MSBuild: use the msbuild -t:restore command, which restores packages packages listed in the project file (PackageReference only). Disponible uniquement dans NuGet 4.x+ et MSBuild 15.1+, inclus avec Visual Studio 2017.Available only in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017. nuget restore et dotnet restore utilisent cette commande pour les projets applicables.nuget restore and dotnet restore both use this command for applicable projects.

  • Visual Studio Team Services : lorsque vous créez une définition de build dans Team Services, incluez la tâche Restauration NuGet ou Restauration .NET Core avant de procéder à toute tâche de génération.Visual Studio Team Services: When creating a build definition on Team Services, include the NuGet restore or .NET Core Restore task in the definition before any build task. Cette tâche est incluse par défaut dans plusieurs modèles de build.This task is included by default in a number of build templates.

  • Team Foundation Server : TFS 2013 et versions ultérieures restaure automatiquement les packages lors de la génération, sous réserve que vous utilisiez un modèle Team Build pour TFS 2013 ou version ultérieure.Team Foundation Server: TFS 2013 and later automatically restores packages during build, provided that you're using a Team Build Template for TFS 2013 or later. Pour les versions antérieures de TFS, vous pouvez inclure une étape de génération destinée à appeler une des options de restauration en ligne de commande ci-dessus.For earlier version of TFS, you can include a build step to invoke one of the command-line restore options above. Vous pouvez éventuellement migrer le modèle de build vers TFS 2013.You can optionally migrate the build template to TFS 2013. Pour plus d’informations, consultez Procédure pas à pas pour la restauration des packages avec Team Foundation Build.For more information, see the Walkthrough of package restore with Team Foundation Build.

Activation et désactivation de la restauration des packagesEnabling and disabling package restore

La restauration du package est généralement activée via Outils > Options > Gestionnaire de package NuGet dans Visual Studio :Package restore is primarily enabled through Tools > Options > NuGet Package Manager in Visual Studio:

Contrôle du comportement de la restauration de package via les options du gestionnaire de package NuGet

  • Autoriser NuGet à télécharger les packages manquants : contrôle toutes les formes de restauration de package en changeant la valeur du paramètre packageRestore/enabled dans le fichier NuGet.Config, comme indiqué ci-dessous (%AppData%\NuGet\NuGet.Config sur Windows, ~/.nuget/NuGet/NuGet.Config sur Mac/Linux).Allow NuGet to download missing packages: controls all forms of package restore by changing the packageRestore/enabled setting in the NuGet.Config file as shown below (%AppData%\NuGet\NuGet.Config on Windows, ~/.nuget/NuGet/NuGet.Config on Mac/Linux). Dans Visual Studio, ce paramètre permet à la commande Restaurer les packages NuGet figurant dans le menu contextuel de la solution de fonctionner.In Visual Studio, this setting allows the Restore NuGet Packages command on the solution's context menu to work.

    <configuration>
        <packageRestore>
            <!-- The 'enabled' key is True when the "Allow NuGet to download missing packages" checkbox is set.
                 Clearing the box sets this to False, disabling command-line, automatic, and MSBuild-Integrated restore. -->
            <add key="enabled" value="True" />
        </packageRestore>
    </configuration>
    

Notes

Le paramètre packageRestore/enabled peut être remplacé globalement en définissant une variable d’environnement appelée EnableNuGetPackageRestore sur la valeur TRUE ou FALSE, avant le lancement de Visual Studio ou le démarrage d’une génération.The packageRestore/enabled setting can be overridden globally by setting an environment variable called EnableNuGetPackageRestore with a value of TRUE or FALSE before launching Visual Studio or starting a build.

  • Rechercher automatiquement les packages manquants pendant la génération dans Visual Studio : contrôle la restauration automatique en changeant la valeur du paramètre packageRestore/automatic dans le fichier NuGet.Config, comme indiqué ci-dessous (%AppData%\NuGet\NuGet.Config sur Windows, ~/.nuget/NuGet/NuGet.Config sur Mac/Linux).Automatically check for missing packages during build in Visual Studio: controls automatic restore by changing the packageRestore/automatic setting in the NuGet.Config file as shown below (%AppData%\NuGet\NuGet.Config on Windows, ~/.nuget/NuGet/NuGet.Config on Mac/Linux). Quand cette option est définie, l’exécution d’une build à partir de Visual Studio restaure automatiquement tous les packages manquants.When this option is set, running a build from Visual Studio automatically restores any missing packages. L’option n’affecte pas les builds exécutées à partir de la ligne de commande avec MSBuild.The option does not affect builds run from the command line using MSBuild.

    ...
    <configuration>
        <packageRestore>
            <!-- The 'automatic' key is set to True when the "Automatically check for missing packages during
                 build in Visual Studio" checkbox is set. Clearing the box sets this to False and disables
                 automatic restore. -->
            <add key="automatic" value="True" />
        </packageRestore>
    </configuration>
    

Pour référence, consultez Fichier config NuGet - Section packageRestore.For reference, see the NuGet config file - packageRestore section.

Dans certains cas, un développeur ou une société peuvent vouloir activer ou désactiver la restauration de package pour tous les utilisateurs d’un ordinateur.In some cases, a developer or company might want to enable or disable package restore for all users on a computer. Pour cela, ajoutez les paramètres ci-dessus au fichier de configuration NuGet global situé dans %ProgramData%\NuGet\Config (Windows, potentiellement sous un dossier \{IDE}\{Version}\{SKU}\ propre à Visual Studio) ou ~/.local/share (Mac/Linux).To do this, add the same settings above to the global NuGet configuration file located in %ProgramData%\NuGet\Config (Windows, potentially under a specific \{IDE}\{Version}\{SKU}\ folder for Visual Studio) or ~/.local/share (Mac/Linux). Chaque utilisateur peut ensuite activer la restauration au niveau d’un projet, si nécessaire.Individual users can then selectively enable restore as needed on a project level. Pour plus d’informations sur la façon dont NuGet hiérarchise les fichiers de configuration, consultez Configuration du comportement de NuGet.See Configuring NuGet behavior for exact details on how NuGet prioritizes multiple config files.

Important

Si vous modifiez les paramètres packageRestore directement dans nuget.config, redémarrez Visual Studio pour que la boîte de dialogue des options affiche les valeurs actuelles.If you edit the packageRestore settings directly in nuget.config, restart Visual Studio so that the options dialog box shows the current values.

Restriction des versions de package avec la restaurationConstraining package versions with restore

Lors de la restauration des packages avec l’une des méthodes disponibles, NuGet respecte toutes les restrictions spécifiées dans packages.config ou le fichier projet :When restoring packages through any method, NuGet honors any constraints specified in packages.config or the project file:

  • packages.config : permet de spécifier une plage de versions dans la propriété allowedVersion de la dépendance.packages.config: Specify a version range in the allowedVersion property of the dependency. Consultez Réinstallation et mise à jour des packages.See Reinstalling and updating packages. Exemple :For example:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
    
  • Fichier projet (PackageReference) : permet de spécifier une plage de versions directement avec le numéro de version de la dépendance.Project file (PackageReference): Specify a version range directly with the dependency's version number. Exemple :For example:

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

Dans tous les cas, utilisez la notation décrite dans Gestion des versions du package.In all cases, use the notation described in Package versioning.

Forcer la restauration à partir de sources de packagesForcing restore from package sources

Par défaut, les opérations de restauration NuGet utilisent des packages provenant des dossiers global-packages et http-cache, décrits sur la page Gérer les dossiers de packages globaux et de cache.By default, NuGet restore operations use packages from the global-packages and http-cache folders, which are described on Managing the global packages and cache folders.

Pour éviter d’utiliser le dossier global-packages, effectuez l’une des opérations suivantes :To avoid using the global-packages folder, do one of the following:

  • Effacez le dossier avec nuget locals global-packages -clear ou dotnet nuget locals global-packages --clear.Clear the folder using nuget locals global-packages -clear or dotnet nuget locals global-packages --clear
  • Modifiez temporairement l’emplacement du dossier global-packages avant l’opération de restauration en suivant l’une des méthodes ci-dessous :Temporarily change the location of the global-packages folder before the restore operation using one of the following methods:
    • Définissez la variable d’environnement NUGET_PACKAGES sur un autre dossier.Set the NUGET_PACKAGES environment variable to a different folder.
    • Créez un fichier NuGet.Config qui définit globalPackagesFolder (si vous utilisez PackageReference) ou repositoryPath (si vous utilisez packages.config) sur un autre dossier (consultez les paramètres de configuration).Create a NuGet.Config file that sets globalPackagesFolder (if using PackageReference) or repositoryPath (if using packages.config) to a different folder (see configuration settings
    • MSBuild uniquement : spécifiez un autre dossier avec la propriété RestorePackagesPath.MSBuild only: specify a different folder with the RestorePackagesPath property.

Pour éviter d’utiliser le cache pour les sources HTTP, effectuez l’une des opérations suivantes :To avoid using the cache for HTTP sources, do one of the following:

  • Utilisez l’option -NoCache avec nuget restore ou l’option --no-cache avec dotnet restore.Use the -NoCache option with nuget restore or the --no-cache option with dotnet restore. Elles n’affectent pas les opérations de restauration effectuées par le biais de la console ou de l’interface utilisateur du Gestionnaire de package de Visual Studio.These options do not affect restore operations through the Visual Studio Package Manager UI or Console.
  • Effacez le cache avec nuget locals http-cache -clear ou dotnet nuget locals http-cache --clear.Clear the cache using nuget locals http-cache -clear or dotnet nuget locals http-cache --clear.
  • Définissez temporairement la variable d’environnement NUGET_HTTP_CACHE_PATH sur un autre dossier.Temporarily set of the NUGET_HTTP_CACHE_PATH environment variable to a different folder.

Résolution des problèmesTroubleshooting

Consultez Résolution des erreurs de restauration.See Troubleshooting package restore.