Configuration du comportement de NuGetConfiguring NuGet behavior

Le comportement de NuGet est contrôlé par les paramètres qui sont définis dans un ou plusieurs fichiers NuGet.Config (XML) qui peuvent exister au niveau du projet, de l’utilisateur ou de l’ordinateur.NuGet's behavior is driven by the accumulated settings in one or more NuGet.Config (XML) files that can exist at project-, user-, and computer-wide levels. Un fichier NuGetDefaults.Config global (2.7+) configure également les sources de package.A global NuGetDefaults.Config file (2.7+) also specifically configures package sources. Les paramètres s’appliquent à toutes les commandes émises dans l’interface CLI, la console du gestionnaire de package et l’interface utilisateur du gestionnaire de package.Settings apply to all commands issued in the CLI, the Package Manager Console, and the Package Manager UI.

Dans cette rubrique :In this topic:

Emplacements et utilisations des fichiers configConfig file locations and uses

PortéeScope Emplacement du fichier NuGet.ConfigNuGet.Config file location DescriptionDescription
ProjetProject Dossier du projet ou tout dossier pouvant être situé jusqu’à la racine du lecteurProject folder or any folder up to the drive root Dans un dossier de projet, les paramètres s’appliquent uniquement au projet en question.In a project folder, settings apply only to that project. Dans les dossiers parents qui contiennent plusieurs dossiers de projets, les paramètres s’appliquent à tous les projets des sous-dossiers.In parent folders that contain multiple projects subfolders, settings apply to all projects in those subfolders.
UtilisateurUser Windows : %APPDATA%\NuGet\NuGet.ConfigWindows: %APPDATA%\NuGet\NuGet.Config
Mac/Linux : ~/.nuget/NuGet.ConfigMac/Linux: ~/.nuget/NuGet.Config
Les paramètres s’appliquent à toutes les opérations. Toutefois, ils sont substitués par tout paramètre défini au niveau du projet.Settings apply to all operations, but are overridden by any project-level settings. Lorsque vous utilisez les commandes CLI, vous pouvez spécifier un fichier config différent en utilisant le commutateur -configFile de façon à ignorer les paramètres du fichier défini par défaut au niveau de l’utilisateur.When using CLI commands, you can specify a different config file using the -configFile switch to ignore any settings in the default user-level file.
OrdinateurComputer Windows : %ProgramFiles(x86)%\NuGet\ConfigWindows: %ProgramFiles(x86)%\NuGet\Config
Mac/Linux : $XDG_DATA_HOME (généralement, ~/.local/share)Mac/Linux: $XDG_DATA_HOME (typically ~/.local/share)
Les paramètres s’appliquent à toutes les opérations effectuées sur l’ordinateur. Toutefois, ils sont substitués par tout paramètre défini au niveau de l’utilisateur ou du projet.Settings apply to all operations on the computer, but are overriden by any user- or project-level settings.

Remarques concernant les versions précédentes de NuGet :Notes for earlier versions of NuGet:

  • NuGet 3.3 et versions antérieures utilisaient un dossier .nuget pour les paramètres définis au niveau de la solution.NuGet 3.3 and earlier used a .nuget folder for solution-wide settings. Ce fichier n’est plus utilisé dans NuGet 3.4+.This file not used in NuGet 3.4+.
  • Pour NuGet 2.6 3.x, le fichier config défini au niveau d’un ordinateur Windows était situé dans %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, où {IDE} pouvait correspondre à Visual Studio, {Version} à la version de Visual Studio, comme 14.0, et {SKU} à l’édition Community, Pro ou Enterprise.For NuGet 2.6 to 3.x, the computer-level config file on Windows was located in %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, where {IDE} can be VisualStudio, {Version} was the Visual Studio version such as 14.0, and {SKU} is either Community, Pro, or Enterprise. Pour migrer les paramètres vers NuGet 4.0+, copiez simplement le fichier config vers %ProgramFiles(x86)%\NuGet\Config. Sur Linux, l’ancien emplacement était /etc/opt et sur Mac, Library/Application Support.To migrate settings to NuGet 4.0+, simply copy the config file to %ProgramFiles(x86)%\NuGet\Config. On Linus, this previous location was /etc/opt, and on Mac, /Library/Application Support.

Modification des paramètres de configurationChanging config settings

Un fichier NuGet.Config est un simple fichier texte XML contenant des paires clé/valeur, comme décrit dans la rubrique Paramètres de configuration NuGet.A NuGet.Config file is a simple XML text file containing key/value pairs as described in the NuGet Configuration Settings topic.

Les paramètres sont gérés à l’aide de la commande config de l’interface CLI de NuGet :Settings are managed using the NuGet CLI config command:

  • Par défaut, les modifications sont apportées au fichier config défini au niveau de l’utilisateur.By default, changes are made to the user-level config file.
  • Pour modifier les paramètres dans un autre fichier, utilisez le commutateur -configFile.To change settings in a different file, use the -configFile switch. Dans ce cas, les fichiers peuvent utiliser n’importe quel nom de fichier.In this case files can use any filename.
  • Les clés respectent toujours la casse.Keys are always case sensitive.
  • Une élévation des privilèges est nécessaire pour modifier les paramètres du fichier de paramètres défini au niveau de l’ordinateur.Elevation is required to change settings in the computer-level settings file.

Avertissement

Même si vous pouvez modifier le fichier dans n’importe quel éditeur de texte, NuGet (v3.4.3 et versions ultérieures) ignore silencieusement l’intégralité du fichier de configuration si celui-ci contient du code XML incorrectement formé (balises incompatibles, guillemets non valides, etc.).Although you can modify the file in any text editor, NuGet (v3.4.3 and later) silently ignores the entire configuration file if it contains malformed XML (mismatched tags, invalid quotation marks, etc.). C’est pourquoi il est préférable de gérer les paramètres à l’aide de nuget config.This is why it's preferable to manage setting using nuget config.

Définition d’une valeurSetting a value

Windows :Windows:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=c:\packages 

# Set repositoryPath in project-level files
nuget config -set repositoryPath=c:\packages -configfile c:\my.Config
nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=c:\packages -configfile %ProgramFiles(x86)%\NuGet\NuGet.Config

Mac/Linux :Mac/Linux:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=/home/packages 

# Set repositoryPath in project-level files
nuget config -set repositoryPath=/home/projects/packages -configfile /home/my.Config
nuget config -set repositoryPath=/home/packages -configfile home/myApp/NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=/home/packages -configfile $XDG_DATA_HOME/NuGet.Config

Note

Dans NuGet 3.4 et versions ultérieures, vous pouvez utiliser des variables d’environnement dans n’importe quelle valeur, comme dans repositoryPath=%PACKAGEHOME% (Windows) et repositoryPath=%PACKAGEHOME (Mac/Linux).In NuGet 3.4 and later you can use environment variables in any value, as in repositoryPath=%PACKAGEHOME% (Windows) and repositoryPath=%PACKAGEHOME (Mac/Linux).

Suppression dune valeurRemoving a value

Pour supprimer une valeur, spécifiez une clé avec une valeur vide.To remove a value, specify a key with an empty value.

# Windows
nuget config -set repositoryPath= -configfile c:\my.Config

# Mac/Linux
nuget config -set repositoryPath= -configfile /home/my.Config

Création d’un fichier configCreating a new config file

Copiez le modèle ci-dessous dans le nouveau fichier, puis utilisez nuget config --configFile <filename> pour définir les valeurs :Copy the template below into the new file and then use nuget config --configFile <filename> to set values:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
</configuration>


Application des paramètresHow settings are applied

L’utilisation de plusieurs fichiers NuGet.Config permet de stocker des paramètres à différents emplacements, de manière à les appliquer à un projet, à un groupe de projets ou à l’ensemble des projets.Multiple NuGet.Config files allow you to store settings in different locations so that they apply to a single project, a group of projects, or all projects. Ces paramètres s’appliquent collectivement à toute opération NuGet appelée à partir de la ligne de commande ou de Visual Studio. Les paramètres « les plus proches » d’un projet ou du dossier actif sont prioritaires.These settings collectively apply to any NuGet operation invoked from the command line or from Visual Studio, with settings that exist "closest" to a project or the current folder taking precedence.

Plus précisément, NuGet charge les paramètres à partir de plusieurs fichiers config dans l’ordre suivant :Specifically, NuGet loads settings from the different config files in the following order:

  1. Le fichier NuGetDefaults.Config, qui contient les paramètres concernant uniquement les sources de package.The NuGetDefaults.Config file, which contains settings related only to package sources.
  2. Le fichier défini au niveau de l’ordinateur.The computer-level file.
  3. Le fichier défini au niveau de l’utilisateur.The user-level file.
  4. Le fichier spécifié avec -configFile.The file specified with -configFile.
  5. Les fichiers qui se trouvent dans chacun des dossiers du chemin allant de la racine du lecteur au dossier actif (celui où nuget.exe est appelé ou le dossier qui contient le projet Visual Studio).Files found in every folder in the path from the drive root to the current folder (where nuget.exe is invoked or the folder containing the Visual Studio project). Par exemple, si une commande est appelée dans c:\A\B\C, NuGet recherche et charge les fichiers config dans c:,, puis c:\A, puis c:\A\B, et enfin, dans c:\A\B\C.For example, if a command is invoked in c:\A\B\C, NuGet looks for and loads config files in c:, then c:\A, then c:\A\B, and finally c:\A\B\C.

Quand NuGet trouve les paramètres dans ces fichiers, il les applique de la manière suivante :As NuGet finds settings in these files, they are applied as follows:

  1. Pour les éléments uniques, NuGet remplaçait toute valeur précédemment trouvée pour la même clé.For single-item elements, NuGet replaced any previously-found value for the same key. Cela signifie que les paramètres qui sont « les plus proches » du dossier actif ou du projet remplacent les paramètres trouvés précédemment.This means that settings that are "closest" to the current folder or project override any others found earlier. Par exemple, le paramètre defaultPushSource dans NuGetDefaults.Config est remplacé s’il se trouve également dans un autre fichier config.For example, the defaultPushSource setting in NuGetDefaults.Config is overridden if it exists in any other config file.

  2. Pour les éléments de collection (tels que <packageSources>), NuGet combine les valeurs de tous les fichiers de configuration dans une même collection.For collection elements (such as <packageSources>), NuGet combines the values from all configuration files into a single collection.

  3. Lorsque <clear /> est présent pour un nœud donné, NuGet ignore les valeurs de configuration définies précédemment pour ce nœud.When <clear /> is present for a given node, NuGet ignores previously defined configuration values for that node.

Procédure pas à pas pour l’application des paramètresSettings walkthrough

Supposons que vous disposiez de la structure de dossiers suivante sur deux lecteurs distincts :Let's say you have the following folder structure on two separate drives:

disk_drive_1
    User
disk_drive_2
   Project1
     Source
   Project2
     Source
   tmp

Vous avez donc quatre fichiers NuGet.Config aux emplacements suivants, avec le contenu spécifiéYou then have four NuGet.Config files in the following locations with the given content. (le fichier défini au niveau de l’ordinateur n’est pas inclus dans cet exemple, toutefois, son comportent est similaire à celui du fichier défini au niveau de l’utilisateur).(The computer-level file is not included in this example, but would behave similarly to the user-level file.)

Fichier A. Fichier défini au niveau de l’utilisateur (%APPDATA%\NuGet\NuGet.Config sur Windows, ~/.nuget/NuGet.Config sur Mac/Linux) :File A. User-level file, (%APPDATA%\NuGet\NuGet.Config on Windows, ~/.nuget/NuGet.Config on Mac/Linux):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <activePackageSource>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
    </activePackageSource>
</configuration>

Fichier B. disk_drive_2/NuGet.Config :File B. disk_drive_2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>        
        <add key="repositoryPath" value="disk_drive_2/tmp" />
    </config>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Fichier C. disk_drive_2/Project1/NuGet.Config :File C. disk_drive_2/Project1/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="External/Packages" />
        <add key="defaultPushSource" value="https://MyPrivateRepo/ES/api/v2/package" />
    </config>
    <packageSources>
        <clear /> <!-- ensure only the sources defined below are used -->
        <add key="MyPrivateRepo - ES" value="https://MyPrivateRepo/ES/nuget" />
    </packageSources>
</configuration>

Fichier D. disk_drive_2/Project2/NuGet.Config :File D. disk_drive_2/Project2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <!-- Add this repository to the list of available repositories -->
        <add key="MyPrivateRepo - DQ" value="https://MyPrivateRepo/DQ/nuget" />
    </packageSources>
</configuration>

Ensuite, NuGet charge et applique les paramètres de la manière suivante, en fonction de l’emplacement où ils sont appelés :NuGet then loads and applies settings as follows, depending on where it's invoked:

  • Appelés à partir de disk_drive_1/users : seul le référentiel par défaut répertorié dans le fichier de configuration défini au niveau de l’utilisateur (A) est utilisé, car il s’agit du seul fichier trouvé à l’emplacement disk_drive_1.Invoked from disk_drive_1/users: Only the default repository listed in the user-level configuration file (A) is used, because that's the only file found on disk_drive_1.

  • Appelés à partir de disk_drive_2/ ou de disk_drive_/tmp : le fichier défini au niveau de l’utilisateur (A) est chargé en premier, puis NuGet accède à la racine de disk_drive_2 et trouve le fichier (B).Invoked from disk_drive_2/ or disk_drive_/tmp: The user-level file (A) is loaded first, then NuGet goes to the root of disk_drive_2 and finds file (B). NuGet recherche également un fichier de configuration dans le répertoire /tmp, sans en trouver un.NuGet also looks for a configuration file in /tmp but does not find one. Par conséquent, le référentiel par défaut de nuget.org est utilisé, la restauration de package est activée et les packages sont développés dans disk_drive_2/tmp.As a result, the default repository on nuget.org is used, package restore is enabled, and packages get expanded in disk_drive_2/tmp.

  • Appelés à partir de disk_drive_2/Project1 ou de disk_drive_2/Project1/Source : le fichier défini au niveau de l’utilisateur (A) est chargé en premier, puis NuGet charge le fichier (B) à partir de la racine de disk_drive_2, suivi du fichier (C).Invoked from disk_drive_2/Project1 or disk_drive_2/Project1/Source: The user-level file (A) is loaded first, then NuGet loads file (B) from the root of disk_drive_2, followed by file (C). Les paramètres du fichier (C) remplacent ceux des fichiers (B) et (A). Par conséquent, le repositoryPath où les packages sont installés est disk_drive_2/Project1/External/Packages et non disk_drive_2/tmp.Settings in (C) override those in (B) and (A), so the repositoryPath where packages get installed is disk_drive_2/Project1/External/Packages instead of disk_drive_2/tmp. De plus, étant donné que (C) efface <packageSources>, nuget.org n’est plus disponible en tant que source, ce qui laisse uniquement https://MyPrivateRepo/ES/nuget.Also, because (C) clears <packageSources>, nuget.org is no longer available as a source leaving only https://MyPrivateRepo/ES/nuget.

  • Appelés à partir de disk_drive_2/Project2 ou de disk_drive_2/Project2/Source : le fichier défini au niveau de l’utilisateur (A) est chargé en premier, suivi du fichier (B) et du fichier (D).Invoked from disk_drive_2/Project2 or disk_drive_2/Project2/Source: The user-level file (A) is loaded first followed by file (B) and file (D). Étant donné que packageSources n’est pas effacé, nuget.org et https://MyPrivateRepo/DQ/nuget sont disponibles en tant que sources.Because packageSources is not cleared, both nuget.org and https://MyPrivateRepo/DQ/nuget are available as sources. Les packages sont développés dans disk_drive_2/tmp, comme spécifié dans le fichier (B).Packages get expanded in disk_drive_2/tmp as specified in (B).

Fichier de valeurs par défaut de NuGetNuGet defaults file

Le fichier NuGetDefaults.Config permet de spécifier les sources de package à partir desquelles les packages sont installés et mis à jour, et de contrôler la cible par défaut pour la publication des packages avec nuget push.The NuGetDefaults.Config file exists to specify package sources from which packages are installed and updated, and to control the default target for publishing packages with nuget push. Étant donné que les administrateurs peuvent aisément (à l’aide d’une stratégie de groupe, par exemple) déployer des fichiers NuGetDefaults.Config cohérents sur les ordinateurs de développeurs et les ordinateurs de build, ils peuvent être sûrs que tous les membres de l’organisation utilisent les bonnes sources de package plutôt que nuget.org.Because administrators can conveniently (using Group Policy, for example) deploy consistent NuGetDefaults.Config files to developer and build machines, they can ensuring that everyone in the organization is using the correct package sources rather than nuget.org.

Important

Le fichier NuGetDefaults.Config n’entraîne jamais la suppression d’une source de package de la configuration NuGet d’un développeur.The NuGetDefaults.Config file never causes a package source to be removed from a developer's NuGet configuration. Cela signifie que si le développeur a déjà utilisé NuGet, et donc, que la source du package nuget.org est inscrite, celle-ci ne sera pas supprimée après la création d’un fichier NuGetDefaults.Config.That means if the developer has already used NuGet and therefore has the nuget.org package source registered, it won't be removed after the creation of a NuGetDefaults.Config file.

De plus, ni NuGetDefaults.Config ni tout autre mécanisme de NuGet ne peuvent empêcher l’accès aux sources de package telles que nuget.org. Si une organisation souhaite bloquer ce type d’accès, elle peut utiliser d’autres moyens, tels que les pare-feu.Furthermore, neither NuGetDefaults.Config nor any other mechanism in NuGet can prevent access to package sources like nuget.org. If an organization wishes to block such access, it much use other means such as firewalls to do so.

Emplacement du fichier NuGetDefaults.ConfigNuGetDefaults.Config location

Windows : %ProgramFiles(x86)%\NuGet\Config (de NuGet 2.7 à NuGet 3.x : %PROGRAMDATA%\NuGet\NuGetDefaults.Config) Mac/Linux : $XDG_DATA_HOME (généralement, ~/.local/share)Windows: %ProgramFiles(x86)%\NuGet\Config (NuGet 2.7 to NuGet 3.x: %PROGRAMDATA%\NuGet\NuGetDefaults.Config) Mac/Linux: $XDG_DATA_HOME (typically ~/.local/share)

Paramètres du fichier NuGetDefaults.ConfigNuGetDefaults.Config settings

  • packageSources : cette collection a la même signification que packageSources dans les fichiers config habituels, et spécifie les sources par défaut dans l’ordre souhaité.packageSources: this collection has the same meaning as packageSources in regular config files and specifies the default sources in their preferred order. Si ce paramètre existe dans NuGetDefaults.Config, NuGet n’utilise pas nuget.org comme une source de package par défaut.If this setting exists in NuGetDefaults.Config, then NuGet doesn't use nuget.org as a default package source. Un administrateur peut ainsi faire en sorte que ceux qui utilisent ce fichier utilisent également les mêmes sources et évitent d’utiliser nuget.org, si nécessaire.An administrator can thus make sure that everyone using this file is working with the same sources and avoids using nuget.org if desired.

  • disabledPackageSources : cette collection a également la même signification que dans les fichiersNuGet.Config, où chaque source affectée est répertoriée, avec son nom et une valeur true/false indiquant si elle est activée ou non.disabledPackageSources: this collection also has the same meaning as in NuGet.Config files, where each affected source is listed by its name and a true/false value indicating whether it's disabled. Ainsi, le nom et l’URL de la source sont conservés dans packageSources, sans que vous ayez à l’activer par défaut.This allows the source name and URL to remain in packageSources without having it turned on by default. Les développeurs peuvent ensuite réactiver la source en définissant sa valeur sur false dans d’autres fichiers NuGet.Config, sans avoir à connaître l’URL correcte.Individual developers can then re-enable the source by setting the source's value to false in other NuGet.Config files without having to find the correct URL again. Cela est également utile pour fournir aux développeurs la liste complète des URL sources internes d’une organisation, tout en activant uniquement la source par défaut d’une équipe.This is also useful to supply developers with a full list of internal source URLs for an organization while enabling only an individual team's source by default.

  • defaultPushSource : spécifie la cible par défaut pour les opérations nuget push, en substituant la valeur intégrée par défaut de nuget.org. Les administrateurs peuvent déployer ce paramètre pour éviter de publier par inadvertance des packages internes sur le nuget.org public, puisque les développeurs doivent utiliser nuget push -Source pour publier des packages sur nuget.org.defaultPushSource: specifies the default target for nuget push operations, overriding the built-in default of nuget.org. Administrators can deploy this setting to avoid publishing internal packages to the public nuget.org by accident, as developers specifically need to use nuget push -Source to publish to nuget.org.

Exemple de fichier NuGetDefaults.Config et d’applicationExample NuGetDefaults.Config and application

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- defaultPushSource key works like the 'defaultPushSource' key of NuGet.Config files. -->
    <!-- This can be used by administrators to prevent accidental publishing of packages to nuget.org. -->
    <config>
        <add key="defaultPushSource" value="https://contoso.com/packages/" />
    </config>

    <!-- Default Package Sources; works like the 'packageSources' section of NuGet.Config files. -->
    <!-- This collection cannot be deleted or modified but can be disabled/enabled by users. -->
    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

    <!-- Default Package Sources that are disabled by default. -->
    <!-- Works like the 'disabledPackageSources' section of NuGet.Config files. -->
    <!-- Sources cannot be modified or deleted either but can be enabled/disabled by users. -->
    <disabledPackageSources>
        <add key="nuget.org" value="true" />
    </disabledPackageSources>
</configuration>