Partilhar via


Referência do nuget.config

O comportamento do NuGet é controlado pelas configurações em diferentes arquivos NuGet.Config ou nuget.config, conforme descrito em Configurações comuns do NuGet.

nuget.config é um arquivo XML que contém um nó <configuration> de nível superior, o qual contém os elementos da seção descritos neste tópico. Cada seção contém zero ou mais itens. Consulte o arquivo de configuração de exemplos. Nomes de configuração não diferenciam maiúsculas de minúsculas e podem usar valores variáveis de ambiente.

Dica

Adicione um arquivo nuget.config na raiz do repositório do projeto. Essa é considerada uma prática recomendada, pois promove a capacidade de repetição e garante que diferentes usuários tenham a mesma configuração do NuGet. Talvez seja necessário configurar elementos clear para garantir que nenhuma configuração específica do usuário ou da máquina seja aplicada. Leia mais sobre como as configurações são aplicadas.

seção de configuração

Contém diversas definições de configurações, que podem ser definidas usando o comando nuget config.

Observação: dependencyVersion e repositoryPath se aplicam apenas a projetos que usam packages.config. globalPackagesFolder aplica-se somente a projetos que usam o formato PackageReference.

Chave Valor
dependencyVersion (somente packages.config) O valor DependencyVersion padrão para a instalação, restauração e atualização do pacote, quando a opção -DependencyVersion não tiver sido especificada diretamente. Esse valor também é usado pela interface do usuário do Gerenciador de Pacotes do NuGet. Os valores são Lowest, HighestPatch, HighestMinor, Highest.
globalPackagesFolder O local da pasta de pacotes global padrão. O padrão é %userprofile%\.nuget\packages (Windows) ou ~/.nuget/packages (Mac/Linux). Um caminho relativo pode ser usado em arquivos nuget.config específicos do projeto. Essa configuração é substituída pela variável de ambiente NUGET_PACKAGES, que tem precedência.
repositoryPath (somente packages.config) O local no qual instalar os pacotes do NuGet em vez da pasta $(Solutiondir)/packages padrão. Um caminho relativo pode ser usado em arquivos nuget.config específicos do projeto.
defaultPushSource Identifica a URL ou o caminho da origem do pacote que deve ser usada como o padrão se nenhuma outra origem de pacote for encontrada para uma operação.
http_proxy http_proxy.user http_proxy.password no_proxy Configurações de proxy a serem usadas ao se conectar a origens de pacote; http_proxy deve estar no formato http://<username>:<password>@<domain>. As senhas são criptografadas e não podem ser adicionadas manualmente. Para no_proxy, o valor é uma lista separada por vírgulas de domínios a ignorar no servidor proxy. Como alternativa, você pode usar as variáveis de ambiente http_proxy e no_proxy para esses valores. Para ver detalhes adicionais, consulte Configurações de proxy do NuGet (skolima.blogspot.com).
maxHttpRequestsPerSource Controla o número máximo de solicitações paralelas enviadas do NuGet para cada origem de pacote para resolução de dependência de pacote e downloads. O valor padrão em dotnet.exe é Int32.MaxValue, que é derivado da propriedade HttpClientHandler.MaxConnectionsPerServer. Essa configuração não tem impacto sobre dotnet.exe para Mac OS porque o limite de limitação é definido para 16 a fim de evitar o erro de muitos arquivos abertos. O valor padrão para NuGet client tools que é executado em .NET Framework como Visual Studio e nuget.exe é 64 em Windows e 1 em Mono. O valor padrão para projetos de estilo Packages.config é definido como Environment.ProcessorCount. Configurar a propriedade maxHttpRequestsPerSource para um valor menor que o padrão pode afetar o desempenho do NuGet.
signatureValidationMode Especifica o modo de validação usado para verificar as assinaturas de pacote para instalação e restauração de pacote. Os valores são accept, require. Assume o padrão de accept.

Exemplo:

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

Seção bindingRedirects

Configura se o NuGet realiza redirecionamentos de associação automática quando um pacote é instalado.

Chave Valor
skip Um valor booliano que indica se os redirecionamentos de associação automática devem ser ignorados. O padrão é false.

Exemplo:

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

Seção packageRestore

Controla a restauração de pacote durante builds.

Chave Valor
Habilitado Um valor booliano que indica se o NuGet pode executar uma restauração automática. Você também pode definir a variável de ambiente EnableNuGetPackageRestore com um valor de True em vez de configurar essa chave no arquivo de configuração.
automático Um valor booliano que indica se o NuGet deve verificar se há pacotes ausentes durante um build.

Exemplo:

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

solution section

Controla se a pasta packages de uma solução está incluída no controle do código-fonte. Esta seção funciona somente em arquivos nuget.config em uma pasta de solução.

Chave Valor
disableSourceControlIntegration Um booliano que indica se a pasta de pacotes deve ser ignorada ao trabalhar com o controle do código-fonte. O valor padrão é falso.

Exemplo:

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

Seções de origem de pacote

O packageSources, packageSourceCredentials, apikeys, activePackageSource, disabledPackageSources, trustedSigners e packageSourceMapping trabalham todos juntos para configurar como o NuGet funciona com repositórios de pacote durante as operações de instalação, restauração e atualização.

O comando nuget sources geralmente é usado para gerenciar essas configurações, exceto apikeys, que é gerenciado usando o comando nuget setapikey, e trustedSigners, que é gerenciado usando o comando nuget trusted-signers.

Observe que a URL de origem para nuget.org é https://api.nuget.org/v3/index.json.

packageSources

Lista todas as origens de pacotes conhecidas. A ordem é ignorada durante as operações de restauração e com qualquer projeto usando o formato PackageReference. O NuGet respeita a ordem dos códigos-fonte para operações de instalação e atualização com projetos que usam packages.config.

Atributo XML Finalidade
Chave (nome a ser atribuído à origem do pacote)
Valor O caminho ou URL da origem do pacote.
protocolVersion A versão do protocolo do servidor NuGet a ser usada. A versão atual é "3". O padrão é a versão "2" quando não aponta para uma URL de origem do pacote que termina em .json (por exemplo, https://api.nuget.org/v3/index.json). Com suporte no NuGet 3.0+. Consulte API do NuGet Server para obter mais informações sobre o protocolo versão 3.
allowInsecureConnections Quando falso ou não especificado, o NuGet emitirá um aviso quando a origem usar http, em vez de https. Se você estiver confiante de que a comunicação com essa fonte nunca correrá risco de ataques de interceptação, poderá definir o valor como true para suprimir o aviso. Com suporte no NuGet 6.8 ou superior.
disableTLSCertificateValidation Esta propriedade de configuração permite desabilitar a validação de certificado SSL/TLS para o servidor HTTPS. Se definido como verdadeiro, o servidor ignorará erros relacionados a certificados SSL/TLS, como certificados expirados ou autoassinados, e estabelecerá a conexão sem realizar a validação. Com suporte no NuGet 6.11 e em versões posteriores.

Exemplo:

<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="Invalid-certificate-https-source" value="https://httpsSourceTrusted/" disableTLSCertificateValidation="true" />
    <add key="Test Source" value="c:\packages" />
</packageSources>

Observação

Use origens de pacotes de sua confiança.

Observação

Ao usar a CLI, você pode expressar uma propriedade MSBuild RestoreSources ou --source(.NET CLI) | -Source(NuGet CLI) para substituir o <packageSources> definido no NuGet.config.

Dica

Quando <clear /> está presente para um nó específico, o NuGet ignora os valores de configuração definidos anteriormente para esse nó. Leia mais sobre como as configurações são aplicadas.

auditSources

Lista todas as origens de auditoria conhecidas, que o NuGet Audit usará durante a restauração. Se nenhuma origem de auditoria for fornecida, a restauração usará as origens de pacotes e suprimirá o NU1905. auditSources foi adicionado ao NuGet 6.12.

As origens de auditoria oferecem suporte para os mesmos atributos que packageSources (protocolVersion, allowInsecureConnections), e origens que requerem autenticação são configuradas com packageSourceCredentials, de forma semelhante a packageSources.

Exemplo:

<auditSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</auditSources>

packageSourceCredentials

Armazena os nomes de usuário e senhas para as origens, geralmente especificado com as opções -username e -password com nuget sources. As senhas são criptografadas por padrão, a menos que a opção -storepasswordincleartext também seja usada. Opcionalmente, os tipos de autenticação válidos podem ser especificados com a opção -validauthenticationtypes.

Chave Valor
Nome de Usuário O nome de usuário para a origem em texto sem formatação. Observação: as variáveis de ambiente podem ser usadas para melhorar a segurança.
password A senha criptografada para a origem. As senhas criptografadas só têm suporte no Windows e só podem ser descriptografadas quando usadas na mesma máquina e por meio do mesmo usuário que a criptografia original.
cleartextpassword A senha não criptografada para a origem. Observação: as variáveis de ambiente podem ser usadas para melhorar a segurança.
ValidAuthenticationTypes Lista separada por vírgulas de tipos de autenticação válidos para essa origem. Defina como basic se o servidor anunciar NTLM ou Negociar e suas credenciais precisarem ser enviadas com o uso do mecanismo Básico, por exemplo, ao usar um PAT com Azure DevOps Server local. Outros valores válidos são negotiate, kerberos, ntlm e digest, mas sua utilidade é improvável.

Aviso

Armazenar senhas em texto não criptografado é fortemente desencorajado. Observe que as senhas criptografadas só são compatíveis no Windows. Além disso, eles só podem ser descriptografados quando usados na mesma máquina e pelo mesmo usuário que os criptografou originalmente. Para obter mais informações sobre como gerenciar credenciais com segurança, confira as melhores práticas de segurança para consumir pacotes de feeds privados.

Dica

Se uma senha não criptografada for passada para password, a mensagem de erro "O parâmetro está incorreto" ocorrerá.

Exemplo:

No arquivo de configuração, o elemento <packageSourceCredentials> contém nós filho para cada nome de origem aplicável (espaços no nome serão substituídos por _x0020_). Ou seja, para origens chamadas “Contoso” e “Origem de teste”, o arquivo de configuração contém o seguinte ao usar senhas criptografadas:

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

Além disso, métodos de autenticação válidos podem ser fornecidos.

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

Ao usar senhas não criptografadas armazenadas em uma variável de ambiente:

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

Ao usar senhas não criptografadas:

Aviso

Armazenar senhas em texto não criptografado é fortemente desencorajado.

<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

Armazena as chaves de origens que usam autenticação de chave de API, conforme definido com o comando nuget setapikey.

Chave Valor
(URL de origem) A chave de API criptografada.

Exemplo:

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

disabledPackageSources

Identificar fontes desabilitadas no momento. Pode ficar em branco. A menos que fontes específicas estejam desabilitadas nesta seção, elas serão habilitadas.

Chave Valor
(nome da origem) Um valor booliano que indica se a origem está desabilitada.

Exemplo:

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

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

No exemplo acima, a origem do pacote Contoso está desabilitada e não será usada para baixar ou instalar pacotes.

activePackageSource

(somente 2.x; preterido no 3.x ou superior)

Identifica a fonte ativa no momento ou indica a agregação de todas as fontes.

Chave Valor
(nome da origem) ou All Se a chave é o nome de uma fonte, o valor é o caminho ou URL da origem. Se All, o valor deve ser (Aggregate source) para combinar todas as origens de pacote que não foram desabilitadas.

Exemplo:

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

Seção trustedSigners

Armazena signatários confiáveis usados para permitir pacotes durante a instalação ou restauração. Essa lista não pode estar vazia quando o usuário define signatureValidationMode como require.

Esta seção pode ser atualizada com o comando nuget trusted-signers.

Esquema:

Um signatário confiável tem uma coleção de itens certificate que alistam todos os certificados que identificam um determinado signatário. Um signatário confiável pode ser um Author ou Repository.

Um repositório confiável também especifica o serviceIndex para o repositório (que deve ser um uri válido https) e pode, opcionalmente, especificar uma lista delimitada por ponto e vírgula de owners para restringir ainda mais quem é confiável com base nesse repositório específico.

Os algoritmos de hash com suporte usados para uma impressão digital de certificado são SHA256, SHA384 e SHA512.

Se um certificate especifica allowUntrustedRoot como true, o certificado fornecido tem permissão para encadear para uma raiz não confiável durante a criação da cadeia de certificados como parte da verificação de assinatura.

Exemplo:

<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" />
        <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />        
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

Seção fallbackPackageFolders

(3,5+) Fornece uma maneira de pré-instalar pacotes para que nenhum trabalho precise ser feito se o pacote for encontrado nas pastas de fallback. As pastas do pacote de fallback têm exatamente a mesma estrutura de pastas e arquivos que a pasta do pacote global: .nupkg está presente e todos os arquivos são extraídos.

A lógica de pesquisa para essa configuração é:

  • Examine a pasta global do pacote para ver se o pacote/versão já foi baixado.

  • Procure nas pastas de fallback uma correspondência de pacote/versão.

Se qualquer uma das pesquisas for bem-sucedida, nenhum download será necessário.

Se uma correspondência não for encontrada, o NuGet verificará os códigos-fonte do arquivo e, em seguida, os códigos-fonte http e, em seguida, baixará os pacotes.

Chave Valor
(nome da pasta de fallback) Caminho para a pasta de fallback.

Exemplo:

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

Mapeamento de origem do pacote

A seção packageSourceMapping contém os detalhes que ajudam as operações do pacote NuGet a determinar de onde uma ID de pacote deve ser baixada.

Esta seção só pode ser gerenciada manualmente no momento.

Uma seção packageSourceMapping só pode conter seções packageSource.

packageSource

Uma subseção da seção packageSourceMapping. Contém um mapeamento para ajudar o NuGet a determinar se a origem deve ser considerada para baixar o pacote de interesse.

Chave
Nome de uma fonte de pacote declarada na seção packageSources. A chave deve corresponder exatamente à chave da origem do pacote.

As seções packageSource em packageSourceMapping são identificadas exclusivamente pelo key.

package

O package faz parte da seção packageSource.

Padrão
Um padrão conforme definido pela sintaxe do mapeamento de Origem do Pacote.

Exemplo:

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

seção packageManagement

Define o formato de gerenciamento de pacotes padrão, packages.config ou PackageReference. Projetos no estilo SDK sempre usam PackageReference.

Chave Valor
format Um booliano indicando o formato de gerenciamento de pacote padrão. Se for 1, o formato será PackageReference. Se for 0, o formato será packages.config.
desabilitado Um booliano indicando se deseja mostrar o prompt para selecionar um formato de pacote padrão na primeira instalação do pacote. False oculta o prompt.

Exemplo:

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

Dica

Quando <clear /> está presente para um nó específico, o NuGet ignora os valores de configuração definidos anteriormente para esse nó. Leia mais sobre como as configurações são aplicadas.

Usando variáveis de ambiente

Você pode usar variáveis de ambiente em valores nuget.config (NuGet 3.4 ou superior) para aplicar as configurações no tempo de execução.

Por exemplo, se a variável de ambiente HOME no Windows for definida como c:\users\username, o valor de %HOME%\NuGetRepository no arquivo de configuração é resolvido para c:\users\username\NuGetRepository.

Observe que você precisa usar variáveis de ambiente no estilo Windows (começa e termina com %) mesmo no Mac/Linux. A presença de $HOME/NuGetRepository em um arquivo de configuração não será resolvida. No Mac/Linux, o valor de %HOME%/NuGetRepository será resolvido como /home/myStuff/NuGetRepository.

Se uma variável de ambiente não for encontrada, o NuGet usa o valor literal do arquivo de configuração. Por exemplo %MY_UNDEFINED_VAR%/NuGetRepository será resolvido como path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

A tabela abaixo mostra a sintaxe da variável de ambiente e o suporte ao separador de caminho para arquivos NuGet.Config.

Suporte a variáveis de ambiente NuGet.Config

Sintaxe Separador de Dir nuget.exe do Windows dotnet.exe do Windows nuget.exe do Mac (em Mono) dotnet.exe do Mac
%MY_VAR% / Sim Sim Sim Sim
%MY_VAR% \ Sim Sim Não No
$MY_VAR / No No No No
$MY_VAR \ No No No No

Exemplo de arquivo de configuração

Abaixo está um arquivo nuget.config de exemplo que ilustra uma série de configurações, incluindo as opcionais:

<?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" />
            <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>