Référence nuget.config

Le comportement de NuGet est contrôlé par des paramètres dans différents fichiers NuGet.Config ou nuget.config comme décrit dans les Configurations NuGetcourantes.

nuget.config est un fichier XML contenant un nœud <configuration> de niveau supérieur qui comprend à son tour les éléments de section décrits dans cette rubrique. Chaque section contient zéro ou plusieurs éléments. Consultez l’exemple de fichier config. Les noms de paramètre ne respectent pas la casse et les valeurs peuvent utiliser des variables d’environnement.

Conseil

Ajoutez un fichier nuget.config dans le dossier racine du dépôt de votre projet. Cette pratique est considérée comme une bonne pratique, car elle favorise la répétabilité et garantit que différents utilisateurs ont la même configuration NuGet. Vous devrez peut-être configurer des éléments clear pour vous assurer qu’aucune configuration spécifique à l’utilisateur ou à l’ordinateur n’est appliquée. En savoir plus sur la façon dont les paramètres sont appliqués.

Section config

Contient des paramètres de configuration divers, qui peuvent être définis à l’aide de la commande nuget config.

dependencyVersion et repositoryPath s’appliquent uniquement aux projets utilisant packages.config. globalPackagesFolder s’applique uniquement aux projets utilisant le format PackageReference.

Clé Valeur
dependencyVersion (packages.config uniquement) Valeur DependencyVersion par défaut pour l’installation, la restauration et la mise à jour de package, quand le commutateur -DependencyVersion n’est pas spécifié directement. Cette valeur est également utilisée par l’interface utilisateur du Gestionnaire de package NuGet. Les valeurs sont Lowest, HighestPatch, HighestMinor, Highest.
globalPackagesFolder (projets utilisant PackageReference uniquement) Emplacement du dossier de packages global par défaut. L’emplacement par défaut est %userprofile%\.nuget\packages (Windows) ou ~/.nuget/packages (Mac/Linux). Un chemin relatif peut être utilisé dans les fichiers nuget.config spécifiques au projet. Ce paramètre est remplacé par la variable d’environnement NUGET_PACKAGES, qui est prioritaire.
repositoryPath (packages.config uniquement) Emplacement dans lequel installer les packages NuGet au lieu du dossier $(Solutiondir)/packages par défaut. Un chemin relatif peut être utilisé dans les fichiers nuget.config spécifiques au projet.
defaultPushSource Identifie l’URL ou le chemin de la source du package qui doit être utilisé comme valeur par défaut si aucune autre source de package n’est trouvée pour une opération.
http_proxy http_proxy.user http_proxy.password no_proxy Paramètres de proxy à utiliser lors de la connexion aux sources de packages ; http_proxy doit être au format http://<username>:<password>@<domain>. Les mots de passe sont chiffrés et ne peuvent pas être ajoutés manuellement. Pour no_proxy, la valeur est une liste de domaines séparés par des virgules qui ignorent le serveur proxy. Vous pouvez également utiliser les variables d’environnement http_proxy et no_proxy pour ces valeurs. Pour plus d’informations, consultez NuGet proxy settings (skolima.blogspot.com).
maxHttpRequestsPerSource Contrôle le nombre maximal de requêtes parallèles envoyées à partir de NuGet à chaque source de package pour la résolution et les téléchargements de dépendances de package. La valeur par défaut sur dotnet.exe est Int32.MaxValue, qui est dérivée de la propriété HttpClientHandler.MaxConnectionsPerServer. Ce paramètre n’a aucun impact sur dotnet.exe pour Mac OS, car la limite de limitation est définie à 16 afin d’éviter un trop grand nombre d’erreurs de fichiers ouverts. La valeur par défaut pour NuGet client tools qui s’exécute sur .NET Framework comme Visual Studio et nuget.exe est 64 sur Windows et 1 sur Mono. La valeur par défaut pour les projets de style Packages.config est définie à Environment.ProcessorCount. La configuration de la propriété maxHttpRequestsPerSource sur une valeur inférieure à la valeur par défaut peut avoir un impact sur les performances de NuGet.
signatureValidationMode Spécifie le mode de validation utilisé pour vérifier les signatures de package pour l’installation et la restauration du signature de package. Les valeurs sont accept et require. La valeur par défaut est accept.

Exemple :

<config>
    <add key="dependencyVersion" value="Highest" />
    <add key="globalPackagesFolder" value="c:\packages" />
    <add key="repositoryPath" value="c:\installed_packages" />
    <add key="http_proxy" value="http://company-squid:3128@contoso.com" />
    <add key="signatureValidationMode" value="require" />
    <add key="maxHttpRequestsPerSource" value="16" />
</config>

Section bindingRedirects

Définit si NuGet effectue des redirections de liaisons automatiques quand un package est installé.

Clé Valeur
skip Valeur booléenne indiquant s’il faut ignorer les redirections de liaisons automatiques. La valeur par défaut est false.

Exemple :

<bindingRedirects>
    <add key="skip" value="True" />
</bindingRedirects>

Section packageRestore

Contrôle la restauration de packages pendant les générations.

Clé Valeur
enabled Valeur booléenne indiquant si NuGet peut effectuer une restauration automatique. Vous pouvez également définir la variable d’environnement EnableNuGetPackageRestore avec la valeur True au lieu de définir cette clé dans le fichier config.
automatique Valeur booléenne indiquant si NuGet doit rechercher les packages manquants pendant une génération.

Exemple :

<packageRestore>
    <add key="enabled" value="true" />
    <add key="automatic" value="true" />
</packageRestore>

Section solution

Contrôle si le dossier packages d’une solution est inclus dans le contrôle de code source. Cette section fonctionne uniquement dans les fichiers nuget.config dans un dossier de solution.

Clé Valeur
disableSourceControlIntegration Valeur booléenne indiquant s’il faut ignorer le dossier de packages lors de l’utilisation de contrôle de code source. La valeur par défaut est false (Faux).

Exemple :

<solution>
    <add key="disableSourceControlIntegration" value="true" />
</solution>

Sections sur les sources de packages

packageSources, packageSourceCredentials, apikeys, activePackageSource, disabledPackageSources, trustedSigners et packageSourceMapping fonctionnent ensemble pour configurer la façon dont NuGet utilise les dépôts de packages pendant les opérations d’installation, de restauration et de mise à jour.

La commande nuget sources est généralement utilisée pour gérer ces paramètres, à l’exception de apikeys qui est géré à l’aide de la commande nuget setapikey et detrustedSigners qui est géré à l’aide de la commande nuget trusted-signers.

Notez que l’URL source pour nuget.org est https://api.nuget.org/v3/index.json.

packageSources

Répertorie toutes les sources de packages connues. L’ordre est ignoré pendant les opérations de restauration et avec n’importe quel projet au format PackageReference. NuGet respecte l’ordre des sources pour les opérations d’installation et de mise à jour avec des projets utilisant packages.config.

Attribut XML Objectif
Clé (nom à assigner à la source du package)
Valeur Chemin ou URL de la source du package.
protocolVersion Version du protocole du serveur NuGet à utiliser. La version actuelle est « 3 ». Par défaut, la version « 2 » ne pointe pas vers une URL source de package se terminant par .json (par exemple https://api.nuget.org/v3/index.json). Pris en charge dans NuGet 3.0+. Pour plus d’informations sur le protocole de la version 3, consultez l’API du serveur NuGet.
allowInsecureConnections Quand la valeur est false ou non spécifiée, NuGet émettra un avertissement lorsque la source utilise http au lieu de https. Si vous avez la certitude que la communication avec cette source ne sera jamais à risque d’attaques d’interception, vous pouvez définir la valeur sur true pour supprimer l’avertissement. Pris en charge dans NuGet 6.8+.

Exemple :

<packageSources>
    <clear />    
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Contoso" value="https://contoso.com/packages/" />
    <add key="http-source" value="http://httpsourcetrusted/" allowInsecureConnections="true" />
    <add key="Test Source" value="c:\packages" />
</packageSources>

Remarque

Lorsque vous utilisez l’interface CLI, vous pouvez exprimer une RestoreSources propriété MSBuild ou--source (.NET CLI) | -Source(CLI NuGet) pour remplacer la valeur <packageSources> définie dans NuGet.config.

Conseil

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. En savoir plus sur la façon dont les paramètres sont appliqués.

packageSourceCredentials

Stocke les noms d’utilisateur et mots de passe pour les sources, spécifiés en général en utilisant les commutateurs -username et -password avec nuget sources. Les mots de passe sont chiffrés par défaut, sauf si l’option -storepasswordincleartext est également utilisée. Si vous le souhaitez, les types d’authentification valides peuvent être spécifiés avec le commutateur -validauthenticationtypes.

Clé Valeur
username Nom d’utilisateur pour la source en texte brut. Remarque : les variables d’environnement peuvent être utilisées pour améliorer la sécurité.
mot de passe Mot de passe chiffré pour la source. Les mots de passe chiffrés sont pris en charge uniquement sur Windows et peuvent uniquement être déchiffrés lorsqu’ils sont utilisés sur le même ordinateur et via le même utilisateur que le chiffrement d’origine.
cleartextpassword Mot de passe non chiffré pour la source. Remarque : les variables d’environnement peuvent être utilisées pour améliorer la sécurité.
validauthenticationtypes Liste, séparée par des virgules, des types d’authentification valides pour cette source. Définissez cette valeur sur basic si le serveur publie NTLM ou Negotiate et que vos informations d’identification doivent être envoyées à l’aide du mécanisme Basic, par exemple lors de l’utilisation d’un PAT avec une instance locale d’Azure DevOps Server. negotiate, kerberos, ntlm et digest sont également des valeurs valides, mais il est peu probable qu’elles soient utiles.

Avertissement

Le stockage des mots de passe en texte clair est fortement déconseillé. Notez que les mots de passe chiffrés sont pris en charge uniquement sur Windows. En outre, ils ne peuvent être déchiffrés qu’en cas d’utilisation sur le même ordinateur et par le même utilisateur qui les a chiffrés à l’origine. Pour plus d’informations sur la gestion sécurisée des identifiants, reportez-vous aux meilleures pratiques de sécurité pour consommer des packages à partir de flux privés.

Conseil

Si un mot de passe non chiffré est passé pour password le message d’erreur « Le paramètre est incorrect » se produit.

Exemple :

Dans le fichier config, l’élément <packageSourceCredentials> contient des nœuds enfants pour chaque nom de source applicable (les espaces dans le nom sont remplacés par _x0020_). Autrement dit, pour les sources nommées « Contoso » et « Test Source », le fichier config contient les éléments suivants lors de l’utilisation de mots de passe chiffrés :

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
    </Test_x0020_Source>
</packageSourceCredentials>

En outre, des méthodes d’authentification valides peuvent être fournies.

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
    </Test_x0020_Source>
</packageSourceCredentials>

Lors de l’utilisation de mots de passe non chiffrés stockés dans une variable d’environnement :

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="%ContosoPassword%" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="%TestSourcePassword%" />
    </Test_x0020_Source>
</packageSourceCredentials>

Lors de l’utilisation de mots de passe non chiffrés :

Avertissement

Le stockage des mots de passe en texte clair est fortement déconseillé.

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="33f!!lloppa" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
    </Test_x0020_Source>
</packageSourceCredentials>

apikeys

Stocke les clés pour les sources qui utilisent l’authentification de clé API, comme défini avec la commande nuget setapikey.

Clé Valeur
(URL source) Clé API chiffrée.

Exemple :

<apikeys>
    <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
</apikeys>

disabledPackageSources

Identifie les sources actuellement désactivées. Peut être vide. Sauf si des sources spécifiques sont désactivées dans cette section, elles sont activées.

Clé Valeur
(nom de source) Valeur booléenne indiquant si la source est désactivée.

Exemple :

<disabledPackageSources>
    <add key="Contoso" value="true" />
</disabledPackageSources>

<!-- Empty list -->
<disabledPackageSources />

Dans l’exemple ci-dessus, la source Contoso du package est désactivée et ne sera pas utilisée pour télécharger ou installer des packages.

activePackageSource

(2.x uniquement ; déprécié dans 3.x+)

Identifie la source actuellement active ou indique l’agrégat de toutes les sources.

Clé Valeur
(nom de source) ou All Si la clé est le nom d’une source, la valeur est le chemin ou l’URL de la source. Si la clé est All, la valeur doit être (Aggregate source) pour combiner toutes les sources de packages qui ne sont pas autrement désactivées.

Exemple :

<activePackageSource>
    <!-- Only one active source-->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />

    <!-- All non-disabled sources are active -->
    <add key="All" value="(Aggregate source)" />
</activePackageSource>

section trustedSigners

Stocke les signataires approuvés utilisés pour autoriser le package lors de l’installation ou de la restauration. Cette liste ne peut pas être vide lorsque l’utilisateur définit signatureValidationMode à require.

Cette section peut être mise à jour avec la commande nuget trusted-signers.

Schéma :

Un signataire approuvé dispose d’une collection d’éléments certificate qui inscrivent tous les certificats qui identifient un signataire donné. Un signataire approuvé peut être un Author ou un Repository.

Un référentiel approuvé spécifie également le serviceIndex pour le référentiel (qui doit être un URI https valide) et peut éventuellement spécifier une liste délimitée par des points-virgules pour owners afin de restreindre encore plus les personnes approuvées dans ce référentiel spécifique.

Les algorithmes de hachage pris en charge utilisés pour une empreinte digitale de certificat sont SHA256, SHA384 et SHA512.

Si un certificate spécifie allowUntrustedRoot en tant que true, le certificat donné est autorisé à se chaîner à une racine non approuvée lors de la création de la chaîne de certificats dans le cadre de la vérification de signature.

Exemple :

<trustedSigners>
    <author name="microsoft">
        <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
    </author>
    <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
        <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

section fallbackPackageFolders

(3.5+) Fournit un moyen de préinstaller des packages afin qu’aucun travail ne soit effectué si le package se trouve dans les dossiers de secours. Les dossiers de package de secours ont exactement la même structure de dossiers et de fichiers que le dossier de package global : .nupkg est présent et tous les fichiers sont extraits.

La logique de recherche de cette configuration est la suivante :

  • Recherchez dans le dossier global du package pour voir si le package/version est déjà téléchargé.

  • Recherchez une correspondance de package/version dans les dossiers de secours.

Si l’une ou l’autre recherche réussit, aucun téléchargement n’est nécessaire.

Si une correspondance est introuvable, NuGet vérifie les sources de fichiers, et les sources http, puis télécharge les packages.

Clé Valeur
(nom du dossier de secours) Chemin d’accès au dossier de secours.

Exemple :

<fallbackPackageFolders>
   <add key="XYZ Offline Packages" value="C:\somePath\someFolder\"/>
</fallbackPackageFolders>

Section Mappage de source du package

La section packageSourceMapping contient les détails qui aident les opérations de package NuGet à déterminer l’emplacement à partir duquel l’identifiant d’un package doit être téléchargé.

Cette section ne peut être gérée que manuellement pour l’instant.

Une section packageSourceMapping ne peut contenir que des sections packageSource.

packageSource

Sous-section de la section packageSourceMapping. Contient un mappage pour aider NuGet à déterminer si la source doit être prise en compte pour télécharger le package d’intérêt.

Clé
Nom d’une source de package déclarée dans la section packageSources. La clé doit correspondre exactement à la clé de la source du package.

Les sections packageSource sous packageSourceMapping sont identifiées de manière unique par le key.

package

Le package fait partie de la section packageSource.

Modèle
Modèle tel que défini par la syntaxe du mappage de source de package.

Exemple :

<packageSourceMapping>
  <packageSource key="contoso.com">
    <package pattern="Contoso.*" />
  </packageSource>
</packageSourceMapping>

section packageManagement

Définit le format de gestion de package par défaut, packages.config ou PackageReference. Les projets de style SDK utilisent toujours PackageReference.

Clé Valeur
format Valeur booléenne indiquant le format de gestion de package par défaut. Si 1, le format est PackageReference. Si 0, le format est packages.config.
disabled Valeur booléenne indiquant s’il faut afficher l’invite pour sélectionner un format de package par défaut lors de la première installation du package. False masque l’invite.

Exemple :

<packageManagement>
   <add key="format" value="1" />
   <add key="disabled" value="False" />
</packageManagement>

Conseil

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. En savoir plus sur la façon dont les paramètres sont appliqués.

Utilisation de variables d’environnement

Vous pouvez utiliser des variables d’environnement dans les valeurs nuget.config (NuGet 3.4+) pour appliquer des paramètres au moment de l’exécution.

Par exemple, si la variable d’environnement HOME sur Windows a la valeur c:\users\username, la valeur %HOME%\NuGetRepository dans le fichier de configuration correspond à c:\users\username\NuGetRepository.

Notez que vous devez utiliser des variables d’environnement de style Windows (commence et termine par %) même sur Mac/Linux. Le fait d’avoir $HOME/NuGetRepository dans un fichier de configuration ne résout pas le problème. Sur Mac/Linux, la valeur de %HOME%/NuGetRepository sera résolue sur /home/myStuff/NuGetRepository.

Si aucune variable d’environnement n’est trouvée, NuGet utilise la valeur littérale du fichier de configuration. Par exemple, le %MY_UNDEFINED_VAR%/NuGetRepository sera résolu en tant que path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

Le tableau ci-dessous montre la syntaxe des variables d’environnment et la prise en charge du séparateur de chemin d’accès pour les fichiers NuGet.Config.

Prise en charge des variables d’environnement NuGet.Config

Syntaxe Séparateur dir nuget.exe Windows dotnet.exe Windows nuget.exe Mac (dans Mono) dotnet.exe Mac
%MY_VAR% / Oui Oui Oui Oui
%MY_VAR% \ Oui Oui No Non
$MY_VAR / Non Non Non Non
$MY_VAR \ Non Non Non Non

Exemple de fichier config

Voici un exemple de fichier nuget.config qui illustre un certain nombre de paramètres, y compris des paramètres facultatifs :

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <!--
            Used to specify the default location to expand packages.
            See: nuget.exe help install
            See: nuget.exe help update

            In this example, %PACKAGEHOME% is an environment variable.
            This syntax works on Windows/Mac/Linux
        -->
        <add key="repositoryPath" value="%PACKAGEHOME%/External" />

        <!--
            Used to specify default source for the push command.
            See: nuget.exe help push
        -->

        <add key="defaultPushSource" value="https://MyRepo/ES/api/v2/package" />

        <!-- Proxy settings -->
        <add key="http_proxy" value="host" />
        <add key="http_proxy.user" value="username" />
        <add key="http_proxy.password" value="encrypted_password" />
    </config>

    <packageRestore>
        <!-- Allow NuGet to download missing packages -->
        <add key="enabled" value="True" />

        <!-- Automatically check for missing packages during build in Visual Studio -->
        <add key="automatic" value="True" />
    </packageRestore>

    <!--
        Used to specify the default Sources for list, install and update.
        See: nuget.exe help list
        See: nuget.exe help install
        See: nuget.exe help update
    -->
    <packageSources>
        <clear />
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
        <add key="MyRepo - ES" value="https://MyRepo/ES/nuget" />
    </packageSources>

    <!-- Used to store credentials -->
    <packageSourceCredentials />

    <!-- Used to disable package sources  -->
    <disabledPackageSources />

    <!--
        Used to specify default API key associated with sources.
        See: nuget.exe help setApiKey
        See: nuget.exe help push
        See: nuget.exe help mirror
    -->
    <apikeys>
        <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
    </apikeys>

    <!--
        Used to specify trusted signers to allow during signature verification.
        See: nuget.exe help trusted-signers
    -->
    <trustedSigners>
        <author name="microsoft">
            <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        </author>
        <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
            <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>