Referencia nuget.config

El comportamiento de NuGet se controla mediante valores de diferentes archivos NuGet.Config o nuget.config, como se describe en Configuraciones comunes de NuGet.

nuget.config es un archivo XML que contiene un nodo <configuration> de nivel superior, que contiene los elementos de sección que se describen en este tema. Cada sección contiene cero o más elementos. Vea el archivo de configuración de ejemplo. Los nombres de opción distinguen mayúsculas de minúsculas, y los valores pueden usar variables de entorno.

Sugerencia

Agregue un archivo nuget.config en la raíz del repositorio del proyecto. Esto se considera un procedimiento recomendado, ya que promueve la repetibilidad y garantiza que distintos usuarios tengan la misma configuración de NuGet. Es posible que tenga que configurar elementos clear para asegurarse de que no se aplica ninguna configuración específica del usuario o de la máquina. Más información sobre cómo se aplica la configuración.

Sección config

Contiene varios valores de configuración, que se pueden establecer mediante el comando nuget config.

dependencyVersion y repositoryPath solo se aplican a proyectos en los que se usa packages.config. globalPackagesFolder solo se aplica a proyectos en los que se usa el formato PackageReference.

Key Value
dependencyVersion (solo packages.config) El valor predeterminado DependencyVersion para la instalación, restauración y actualización del paquete, cuando no se especifica directamente el modificador -DependencyVersion. Este valor también se usa en la interfaz de usuario del Administrador de paquetes NuGet. Los valores son Lowest, HighestPatch, HighestMinor, Highest.
globalPackagesFolder (proyectos que solo usan PackageReference) La ubicación de la carpeta de paquetes global predeterminada. El valor predeterminado es %userprofile%\.nuget\packages (Windows) o ~/.nuget/packages (Mac o Linux). Se puede usar una ruta de acceso relativa en archivos nuget.config específicos del proyecto. Este valor se invalida mediante la variable de entorno NUGET_PACKAGES, que tiene prioridad.
repositoryPath (solo packages.config) La ubicación en la que se van a instalar los paquetes NuGet en lugar de la carpeta $(Solutiondir)/packages predeterminada. Se puede usar una ruta de acceso relativa en archivos nuget.config específicos del proyecto.
defaultPushSource Identifica la dirección URL o ruta de acceso de origen del paquete que se debe usar como valor predeterminado si no se encuentra ningún otro origen del paquete para una operación.
http_proxy http_proxy.user http_proxy.password no_proxy Configuración de proxy que se usa al conectarse a orígenes de paquetes; http_proxy debe tener el formato http://<username>:<password>@<domain>. Las contraseñas están cifradas y no se pueden agregar de forma manual. Para no_proxy, el valor es una lista separada por comas de dominios que omiten el servidor proxy. Como alternativa, puede usar las variables de entorno http_proxy y no_proxy para esos valores. Para obtener más información, vea Configuración de proxy de NuGet (skolima.blogspot.com).
maxHttpRequestsPerSource Controla el número máximo de solicitudes paralelas enviadas desde NuGet a cada origen de paquete para la resolución y descargas de dependencias de paquetes. El valor predeterminado en dotnet.exe es Int32.MaxValue, que se deriva de la propiedad HttpClientHandler.MaxConnectionsPerServer. Este valor no afecta a dotnet.exe para Mac OS, porque el límite de limitación está establecido en 16 para evitar demasiados errores de archivos abiertos. El valor predeterminado para NuGet client tools que se ejecuta en .NET Framework, como Visual Studio y nuget.exe es 64 en Windows y 1 en Mono. El valor predeterminado de los proyectos de estilo Packages.config se establece en Environment.ProcessorCount. La configuración de la propiedad maxHttpRequestsPerSource en un valor menor que el predeterminado podría afectar al rendimiento de NuGet.
signatureValidationMode Especifica el modo de validación que se usa para comprobar las firmas de paquete para la instalación del paquete y la restauración. Los valores son accept, require. Tiene como valor predeterminado accept.

Ejemplo:

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

Sección bindingRedirects

Configura si NuGet realiza redirecciones de enlaces automáticas cuando se instala un paquete.

Key Value
skip Un valor booleano que indica si se omiten las redirecciones de enlaces automáticas. El valor predeterminado es false.

Ejemplo:

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

Sección packageRestore

Controla la restauración del paquete durante las compilaciones.

Key Value
enabled Un valor booleano que indica si NuGet puede realizar la restauración automática. También se puede establecer la variable de entorno EnableNuGetPackageRestore con un valor de True en lugar de establecer esta clave en el archivo de configuración.
automatic Un valor booleano que indica si NuGet debe comprobar los paquetes que faltan durante una compilación.

Ejemplo:

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

Sección solution

Controla si la carpeta packages de una solución se incluye en el control de código fuente. En esta sección solo funciona en los archivos nuget.config de la carpeta de una solución.

Key Value
disableSourceControlIntegration Un valor booleano que indica si se debe ignorar la carpeta de paquetes cuando se trabaja con el control de código fuente. El valor predeterminado es falso.

Ejemplo:

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

Secciones de origen del paquete

packageSources, packageSourceCredentials, apikeys, activePackageSource, disabledPackageSources, trustedSigners y packageSourceMapping trabajan de manera conjunta para configurar el funcionamiento de NuGet con repositorios de paquetes durante las operaciones de instalación, restauración y actualización.

Normalmente se usa el comando nuget sources para administrar estos valores, excepto para apikeys que se administra con el comando nuget setapikey, y trustedSigners, que se administra con el comando nuget trusted-signers.

Tenga en cuenta que la dirección URL de origen de nuget.org es https://api.nuget.org/v3/index.json.

packageSources

Enumera todos los orígenes de paquetes conocidos. El orden se omite durante las operaciones de restauración y con cualquier proyecto que use el formato PackageReference. NuGet respeta el orden de los orígenes para las operaciones de instalación y actualización con proyectos que usen packages.config.

Atributo XML Fin
Clave (nombre para asignar al origen del paquete)
Valor La ruta de acceso o dirección URL del origen del paquete.
protocolVersion Versión del protocolo de servidor NuGet que se va a usar. La versión actual es "3". El valor predeterminado es la versión "2" cuando no apunta a una dirección URL de origen del paquete que termina en .json (por ejemplo, https://api.nuget.org/v3/index.json). Compatible con NuGet 3.0 y versiones posteriores. Vea API de servidor NuGet para más información sobre el protocolo de la versión 3.
allowInsecureConnections Cuando es false o no se especifica, NuGet emitirá una advertencia cuando el origen use http, en lugar de https. Si está seguro de que la comunicación con este origen nunca estará en riesgo de ataques de interceptación, puede establecer el valor en true para suprimir la advertencia. Compatible con NuGet 6.8 y versiones posteriores.

Ejemplo:

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

Nota:

Al usar la CLI, puede expresar una propiedad RestoreSources de MSBuild o de la --source(CLI de .NET) | -Source(CLI de NuGet) para invalidar el valor <packageSources> definido en NuGet.config.

Sugerencia

Cuando <clear /> está presente para un nodo determinado, NuGet ignora los valores de configuración definidos previamente para ese nodo. Más información sobre cómo se aplica la configuración.

packageSourceCredentials

Almacena nombres de usuario y contraseñas para los orígenes, normalmente especificados con los modificadores -username y -password con nuget sources. Las contraseñas se cifran de forma predeterminada a menos que también se use la opción -storepasswordincleartext. Opcionalmente, se pueden especificar tipos de autenticación válidos con el modificador -validauthenticationtypes.

Key Value
username El nombre de usuario para el origen en texto sin formato. Nota: Las variables de entorno se pueden usar para mejorar la seguridad.
password La contraseña cifrada para el origen. Las contraseñas cifradas solo se admiten en Windows y solo se pueden descifrar cuando se usan en la misma máquina y mediante el mismo usuario que el cifrado original.
cleartextpassword La contraseña no cifrada para el origen. Nota: Las variables de entorno se pueden usar para mejorar la seguridad.
validauthenticationtypes Lista separada por comas de tipos de autenticación válidos para este origen. Establézcalo en basic si el servidor anuncia NTLM o Negotiate y las credenciales deben enviarse mediante el mecanismo básico, por ejemplo, cuando se usa una instancia de PAT con Azure DevOps Server local. Otros valores válidos son negotiate, kerberos, ntlm y digest, pero es poco probable que estos valores sean útiles.

Advertencia

No se recomienda almacenar contraseñas en texto no cifrado. Tenga en cuenta que las contraseñas cifradas solo se admiten en Windows. Además, solo se pueden descifrar cuando se usan en el mismo equipo y por el mismo usuario que las cifró originalmente. Para obtener más información sobre cómo administrar credenciales de forma segura, consulte los procedimientos recomendados de seguridad para consumir paquetes de fuentes privadas.

Sugerencia

Si se pasa una contraseña no cifrada para password, aparecerá el mensaje de error "El parámetro es incorrecto".

Ejemplo:

En el archivo de configuración, el elemento <packageSourceCredentials> contiene nodos secundarios para cada nombre de origen aplicable (los espacios en el nombre se reemplazan por _x0020_). Es decir, para los orígenes denominados "Contoso" y "Test Source", el archivo de configuración contiene lo siguiente cuando se usan contraseñas cifradas:

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

Además, se pueden proporcionar métodos de autenticación válidos.

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

Al usar contraseñas sin cifrar almacenadas en una variable de entorno:

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

Cuando se usan contraseñas sin cifrar:

Advertencia

No se recomienda almacenar contraseñas en texto no cifrado.

<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

Almacena claves para los orígenes en los que se usa autenticación de clave de API, como se establece mediante el comando nuget setapikey.

Key Value
(dirección URL de origen) La clave de API cifrada.

Ejemplo:

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

disabledPackageSources

Orígenes actualmente deshabilitados identificados. Puede estar vacío. A menos que se deshabiliten orígenes específicos en esta sección, están habilitados.

Key Value
(nombre del origen) Un valor booleano que indica si el origen está deshabilitado.

Ejemplo:

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

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

En el ejemplo anterior, el origen del paquete Contoso está deshabilitado y no se usará para descargar o instalar paquetes.

activePackageSource

(solo para 2.x; en desuso en 3.x y versiones posteriores)

Identifica al origen actualmente activo o indica la suma de todos los orígenes.

Key Value
(nombre del origen) o All Si la clave es el nombre de un origen, el valor es la ruta de acceso o la dirección URL del origen. Si es All, el valor debe ser (Aggregate source) para combinar todos los orígenes de paquetes que no estén deshabilitados.

Ejemplo:

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

Sección trustedSigners

Almacena firmantes de confianza usados para permitir el paquete durante la instalación o la restauración. Esta lista no puede estar vacía cuando el usuario establece signatureValidationMode en require.

Esta sección se puede actualizar con el comando nuget trusted-signers.

Esquema:

Un firmante de confianza tiene una colección de elementos certificate que inscriben todos los certificados que identifican un firmante determinado. Un firmante de confianza puede ser Author o Repository.

Un repositorio de confianza también especifica serviceIndex para el repositorio (que tiene que ser un URI https válido) y, opcionalmente, puede especificar una lista delimitada por punto y coma de elementos owners para restringir aún más en quién se confía en ese repositorio específico.

Los algoritmos hash admitidos que se usan para una huella digital de certificado son SHA256 y SHA384SHA512.

Si certificate especifica allowUntrustedRoot como true, el certificado especificado se puede encadenar a una raíz que no es de confianza mientras se crea la cadena de certificados como parte de la comprobación de la firma.

Ejemplo:

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

Sección fallbackPackageFolders

(3.5+) Proporciona una manera de preinstalar paquetes para que no sea necesario realizar ningún trabajo si el paquete se encuentra en las carpetas de reserva. Las carpetas de paquete de reserva tienen exactamente la misma estructura de carpetas y archivos que la carpeta del paquete global: .nupkg está presente y se extraen todos los archivos.

La lógica de búsqueda de esta configuración es la siguiente:

  • Se busca en la carpeta global del paquete para ver si el paquete o la versión ya están descargados.

  • Se busca en las carpetas de reserva una coincidencia del paquete o la versión.

Si alguna de las búsquedas es correcta, no es necesaria ninguna descarga.

Si no se encuentra una coincidencia, NuGet comprueba los orígenes de archivos, después los orígenes http y, luego, descarga los paquetes.

Key Value
(nombre de la carpeta de reserva) Ruta de acceso a la carpeta de reserva.

Ejemplo:

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

Sección de asignación de origen del paquete

La sección packageSourceMapping contiene los detalles que ayudan a las operaciones del paquete NuGet a determinar de dónde se debe descargar un identificador de paquete.

Esta sección solo se puede administrar manualmente por el momento.

Una sección packageSourceMapping solo puede contener secciones packageSource.

packageSource

Subsección de la sección packageSourceMapping. Contiene una asignación para ayudar a NuGet a determinar si se debe tener en cuenta el origen para descargar el paquete de interés.

Clave
Nombre de un origen de paquete declarado en la sección packageSources. La clave debe coincidir exactamente con la clave del origen del paquete.

Las secciones packageSource de packageSourceMapping se identifican de forma única mediante key.

paquete

package forma parte de la sección packageSource.

Patrón
Patrón como se define en la sintaxis de asignación del origen del paquete.

Ejemplo:

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

Sección packageManagement

Establece el formato de administración de paquetes predeterminado, ya sea packages.config o PackageReference. En los proyectos de estilo SDK siempre se usa PackageReference.

Key Value
format Valor booleano que indica el formato de administración de paquetes predeterminado. Si es 1, el formato es PackageReference. Si es 0, el formato es packages.config.
disabled Valor booleano que indica si se va a mostrar el mensaje para seleccionar un formato de paquete predeterminado en la primera instalación del paquete. False oculta el mensaje.

Ejemplo:

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

Sugerencia

Cuando <clear /> está presente para un nodo determinado, NuGet ignora los valores de configuración definidos previamente para ese nodo. Más información sobre cómo se aplica la configuración.

Uso de variables de entorno

Puede usar variables de entorno en valores nuget.config (NuGet 3.4 o versiones posteriores) para aplicar la configuración en tiempo de ejecución.

Por ejemplo, si la variable de entorno HOME en Windows se establece en c:\users\username, el valor de %HOME%\NuGetRepository en el archivo de configuración se resuelve como c:\users\username\NuGetRepository.

Tenga en cuenta que debe usar variables de entorno de estilo Windows (que empiezan y terminan con %) incluso en Mac/Linux. Tener $HOME/NuGetRepository en un archivo de configuración no se resolverá. En Mac/Linux, el valor de %HOME%/NuGetRepository se resolverá en /home/myStuff/NuGetRepository.

Si no se encuentra una variable de entorno, NuGet usa el valor literal del archivo de configuración. Por ejemplo %MY_UNDEFINED_VAR%/NuGetRepository se resolverá como path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

En la tabla siguiente se muestra la sintaxis de variables de entorno y la compatibilidad con el separador de ruta de acceso para los archivos NuGet.Config.

Compatibilidad con variables de entorno NuGet.Config

Sintaxis Separador de directorio Windows nuget.exe Windows dotnet.exe Mac nuget.exe (en Mono) Mac dotnet.exe
%MY_VAR% /
%MY_VAR% \ No N.º
$MY_VAR / N.º N.º N.º N.º
$MY_VAR \ N.º N.º N.º No

Archivo de configuración de ejemplo

A continuación se muestra un archivo nuget.config de ejemplo en el que se ilustran varios valores, incluidos los opcionales:

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