Referência do `nuget.config`

Artigo
12/29/2023

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 (projetos usando somente PackageReference)	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.

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="Test Source" value="c:\packages" />
</packageSources>

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.

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" />
        <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	Não

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" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>

Referência do `nuget.config`

seção de configuração

Seção bindingRedirects

Seção packageRestore

solution section

Seções de origem de pacote

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

Seção trustedSigners

Seção fallbackPackageFolders

Mapeamento de origem do pacote

packageSource

package

seção packageManagement

Usando variáveis de ambiente

Suporte a variáveis de ambiente `NuGet.Config`

Exemplo de arquivo de configuração

Comentários

Comentários

Recursos adicionais

Referência do nuget.config

seção de configuração

Seção bindingRedirects

Seção packageRestore

solution section

Seções de origem de pacote

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

Seção trustedSigners

Seção fallbackPackageFolders

Mapeamento de origem do pacote

packageSource

package

seção packageManagement

Usando variáveis de ambiente

Suporte a variáveis de ambiente NuGet.Config

Exemplo de arquivo de configuração

Comentários

Comentários

Recursos adicionais

Referência do `nuget.config`

Suporte a variáveis de ambiente `NuGet.Config`