Configurações comuns do NuGet

  • Artigo

O comportamento do NuGet é controlado pelas configurações acumuladas em um ou mais arquivos NuGet.Config (XML) que podem existir no nível de solução (ou projeto, se nenhuma solução for usada), usuário e computador. Um arquivo global NuGetDefaults.Config também configura as origens de pacote especificamente. As configurações se aplicam a todos os comandos emitidos na CLI, no Console do Gerenciador de Pacotes e na interface do usuário do Gerenciador de Pacotes.

Usos e locais do arquivo de configuração

Escopo Local do arquivo NuGet.Config Descrição
Solução A pasta atual (também conhecida como pasta de solução) ou qualquer pasta até a raiz da unidade. Em uma pasta de solução, as configurações se aplicam a todos os projetos nas subpastas. Observe que, se um arquivo de configuração for colocado em uma pasta de projeto, ele não causará nenhum efeito nesse projeto. Ao restaurar um projeto na linha de comando, o diretório do projeto é tratado como o diretório da solução, o que pode levar a diferenças no comportamento ao restaurar o projeto versus a solução.
Usuário Windows:%appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config ou ~/.nuget/NuGet/NuGet.Config (varia de acordo com as ferramentas)
Configurações adicionais são aceitas em todas as plataformas. Essas configurações não podem ser editadas pelas ferramentas.
Windows:%appdata%\NuGet\config\*.Config
Mac/Linux:~/.config/NuGet/config/*.config ou ~/.nuget/config/*.config		 As configurações se aplicam a todas as operações, mas são sobrescritas por quaisquer configurações de nível de projeto.
Computador Windows:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:/etc/opt/NuGet/Config (Linux) ou /Library/Application Support (Mac) por padrão. Se $NUGET_COMMON_APPLICATION_DATA não for nulo nem estiver vazio, use $NUGET_COMMON_APPLICATION_DATA/NuGet/Config		 As configurações se aplicam a todas as operações, mas são substituídas por quaisquer configurações em nível de usuário ou solução.

Observação

No Mac/Linux, o local do arquivo de configuração do usuário varia de acordo com a ferramenta. A CLI do .NET usa a pasta ~/.nuget/NuGet, enquanto o Mono usa a pasta ~/.config/NuGet.

No Mac/Linux, o local do arquivo de configuração no nível do usuário varia de acordo com as ferramentas

No Mac/Linux, o local do arquivo de configuração do usuário varia de acordo com a ferramenta. A maioria dos usuários usa ferramentas que procuram o arquivo de configuração do usuário na pasta ~/.nuget/NuGet. Essas outras ferramentas procuram o arquivo de configuração do usuário ~/.config/NuGet na pasta:

  • Mono
  • NuGet.exe
  • Visual Studio 2019 para Mac (e versões anteriores)
  • Visual Studio 2022 para Mac (e versões posteriores), somente ao trabalhar em projetos Mono clássicos.

Se as ferramentas usadas envolverem ambos os locais, considere consolidá-las seguindo estas etapas para permitir que você trabalhe com apenas um arquivo de configuração em nível do usuário:

  1. Verifique o conteúdo dos dois arquivos de configuração em nível de usuário e mantenha o desejado na pasta ~/.nuget/NuGet.
  2. Definir link simbólico de ~/.nuget/NuGet para ~/.config/NuGet. Por exemplo, execute o comando bash: ln -s ~/.nuget/NuGet ~/.config/NuGet.

Observações para versões anteriores do NuGet:

  • O NuGet 3.3 e versões anteriores usavam uma pasta .nuget para configurações de toda a solução. Este arquivo não é usado no NuGet 3.4 ou posterior.
  • Para o NuGet 2.6 a 3.x, o arquivo de configuração no nível do computador no Windows estava localizado em %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, onde {IDE} pode ser VisualStudio, {Version} era a versão do Visual Studio, como 14.0, e {SKU} é Community, Pro ou Enterprise. Para migrar as configurações para o NuGet 4.0 ou superior, simplesmente copie o arquivo de configuração para %ProgramFiles(x86)%\NuGet\Config. No Linux, esse local anterior era /etc/opt, e no Mac, /Library/Application Support.

Alterar as definições da configuração

Um arquivo NuGet.Config é um arquivo de texto XML simples que contém pares chave-valor, conforme descrito no tópico Definições de configuração do NuGet.

As configurações são gerenciadas usando o comando config da CLI do NuGet:

  • Por padrão, as alterações são feitas no arquivo de configuração de nível de usuário. (No Mac/Linux, o local do arquivo de configuração em nível de usuário varia de acordo com a ferramenta)
  • Para alterar as configurações em um arquivo diferente, use a opção -configFile. Nesse caso, os arquivos podem usar qualquer nome de arquivo.
  • As chaves sempre diferenciam maiúsculas e minúsculas.
  • A elevação é necessária para alterar as configurações no arquivo de configurações no nível do computador.

Aviso

Embora você possa modificar o arquivo em qualquer editor de texto, o NuGet (v3.4.3 e posterior) ignorará silenciosamente todo o arquivo de configuração se ele contiver XML malformado (marcas não correspondidas, aspas inválidas, etc.). É por isso que é preferível gerenciar a configuração usando nuget config.

Definindo um valor

Windows:

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

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

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

Mac/Linux:

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

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

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

Observação

No NuGet 3.4 e posterior, você pode usar as variáveis de ambiente em qualquer valor, como no repositoryPath=%PACKAGEHOME% (Windows) e repositoryPath=$PACKAGEHOME (Mac/Linux).

Removendo um valor

Para remover um valor, especifique uma chave com um valor vazio.

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

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

Criar um novo arquivo de configuração

Copie o modelo abaixo para o novo arquivo e, em seguida, use nuget config -configFile <filename> para definir os valores:

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

Como as configurações são aplicadas

Vários arquivos NuGet.Config permitem que você armazene as configurações em locais diferentes, para que elas se apliquem a uma única solução ou a um grupo de soluções. Coletivamente, essas configurações se aplicam a qualquer operação do NuGet invocada na linha de comando ou do Visual Studio, com as configurações existentes “mais próximas” para uma solução ou a pasta atual tendo precedência. Se uma ferramenta de linha de comando é usada em um arquivo de projeto, em vez de um arquivo de solução, então o diretório de projeto é usado como o "diretório de solução", o que pode levar a um comportamento inconsistente quando há um arquivo em um subdiretório NuGet.Config do arquivo de solução.

Especificamente, o NuGet carrega as configurações dos arquivos de configuração diferente na seguinte ordem:

  1. O arquivo NuGetDefaults.Config, que contém as configurações relacionadas somente a origens de pacotes.
  2. O arquivo de nível de computador.
  3. O arquivo de nível de usuário.
  4. O arquivo especificado com -configFile.
  5. Arquivos encontrados em todas as pastas no caminho da raiz de unidade para a pasta atual (em que nuget.exe é invocado ou a pasta que contém a solução em Visual Studio). Por exemplo, se um comando for invocado em c:\A\B\C, o NuGet irá procurar e carregar arquivos de configuração em c:\, c:\A e c:\A\B e, finalmente, em c:\A\B\C.

À medida que o NuGet encontra configurações nesses arquivos, eles são aplicados da seguinte maneira:

  1. Para elementos de item único, o NuGet substituiu qualquer valor encontrado anteriormente pela mesma chave. Isso significa que as configurações que são “mais próximas” da pasta ou solução atual substituem quaisquer outras encontradas anteriormente. Por exemplo, a definição defaultPushSource em NuGetDefaults.Config será substituída se ela existir em qualquer outro arquivo de configuração.
  2. Para elementos de coleta (como <packageSources>), o NuGet combina os valores de todos os arquivos de configuração em uma única coleção.
  3. Quando <clear /> está presente para um nó específico, o NuGet ignora os valores de configuração definidos anteriormente para esse nó.

Dica

Adicione um arquivo nuget.config na raiz do repositório de soluções. Essa é considerada uma melhor prática, pois promove a repetibilidade e garante que diferentes usuários tenham a mesma configuração do NuGet.

Explicação passo a passo das configurações

Digamos que você tem a seguinte estrutura de pasta em duas unidades separadas:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

Dessa forma, você terá quatro arquivos NuGet.Config nos seguintes locais com o conteúdo em questão. (O arquivo no nível de computador não está incluído neste exemplo, mas se comportaria da mesma forma que o arquivo de nível de usuário.)

Arquivo A. Arquivo de nível de usuário, (%appdata%\NuGet\NuGet.Config no Windows e ~/.config/NuGet/NuGet.Config no Mac/Linux):

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

Arquivo B. disk_drive_2/NuGet.Config:

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

Arquivo C. disk_drive_2/Project1/NuGet.Config:

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

Arquivo D. disk_drive_2/Project2/NuGet.Config:

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

O NuGet, em seguida, carrega e aplica as configurações como mostrado a seguir, dependendo de onde ele é chamado:

  • Invocado de disk_drive_1/users: somente o repositório padrão listado no arquivo de configuração de nível de usuário (A) é usado, pois esse é o único arquivo encontrado em disk_drive_1.

  • Invocado de disk_drive_2/ ou disk_drive_/tmp: o arquivo no nível do usuário (A) é carregado primeiro, depois o NuGet acessa a raiz de disk_drive_2 e descobre o arquivo (B). O NuGet também procura um arquivo de configuração em /tmp, mas não o encontra. Como resultado, o repositório padrão em nuget.org é usado, a restauração de pacote é habilitada e os pacotes são expandidos em disk_drive_2/tmp.

  • Invocado de disk_drive_2/Project1 ou disk_drive_2/Project1/Source: o arquivo de nível do usuário (A) é carregado primeiro, depois o NuGet carrega o arquivo (B) da raiz de disk_drive_2, seguido pelo arquivo (C). As configurações em (C) substituem as configurações em (B) e (A), de modo que o repositoryPath em que os pacotes são instalados é disk_drive_2/Project1/External/Packages em vez de disk_drive_2/tmp. Além disso, como (C) limpa o <packageSources>, o nuget.org não está mais disponível como uma origem, restando apenas https://MyPrivateRepo/ES/nuget.

  • Invocado de disk_drive_2/Project2 ou disk_drive_2/Project2/Source: o arquivo de nível de usuário (A) é carregado primeiro, seguido pelos arquivo (B) e (D). Como packageSources não foi apagado, ambos nuget.org e https://MyPrivateRepo/DQ/nuget estão disponíveis como origens. Os pacotes são expandidos em disk_drive_2/tmp conforme especificado em (B).

Configuração adicional para todos os usuários

A partir da versão 5.7, o NuGet adicionou suporte a arquivos de configuração adicionais para todos os usuários. Isso permite que fornecedores terceirizados adicionem arquivos de configuração de usuário adicionais sem elevação. Esses arquivos de configuração podem ser encontrados na pasta de configuração do usuário padrão em uma subpasta config. Todos os arquivos que terminam com .config ou .Config serão considerados. Esses arquivos não podem ser editados pelas ferramentas padrão.

Plataforma do SO Configurações adicionais
Windows %appdata%\NuGet\config\*.Config
Mac/Linux ~/.config/NuGet/config/*.config ou ~/.nuget/config/*.config

Arquivo de padrões do NuGet

O arquivo NuGetDefaults.Config existe para especificar origens de pacote do qual os pacotes são instalados e atualizados, e para controlar o destino padrão para publicar pacotes com nuget push. Como os administradores podem implantar com conveniência (usando a Política de Grupo, por exemplo) arquivos NuGetDefaults.Config consistentes em computadores de desenvolvedor e de build, eles podem garantir que todos na organização estejam usando as origens de pacotes corretas, em vez do nuget.org.

Importante

O arquivo NuGetDefaults.Config nunca faz com que a origem do pacote seja removida da configuração do NuGet do desenvolvedor. Isso significa que, se o desenvolvedor já tiver usado o NuGet e, portanto, a origem do pacote no nuget.org está registrada, ele não será removido após a criação de um arquivo NuGetDefaults.Config.

Além disso, o NuGetDefaults.Config e os outros mecanismos no NuGet não podem impedir o acesso a fontes de pacotes como o nuget.org. Se uma organização desejar bloquear esse acesso, ela deverá usar outros meios, como firewalls, para fazê-lo.

Local do NuGetDefaults.Config

A tabela a seguir descreve onde o arquivo NuGetDefaults.Config deve ser armazenado, dependendo do sistema operacional de destino:

Plataforma do SO NuGetDefaults.Config Local
Windows Visual Studio 2017 ou NuGet 4.x+:%ProgramFiles(x86)%\NuGet
Visual Studio 2015 e anteriores ou NuGet 3.x e anteriores:%PROGRAMDATA%\NuGet
Mac/Linux $XDG_DATA_HOME (normalmente ~/.local/share ou /usr/local/share, dependendo da distribuição do SO)

Configurações do NuGetDefaults.Config

  • packageSources: esta coleção tem o mesmo significado que packageSources em arquivos de configuração regulares e especifica as origens padrão. O NuGet usa as origens em ordem ao instalar ou atualizar pacotes em projetos usando o formato de gerenciamento packages.config. Para projetos usando o formato PackageReference, o NuGet usa origens locais primeiro e, em seguida, origens em compartilhamentos de rede e origens em HTTP, independentemente da ordem dos arquivos de configuração. O NuGet sempre ignora a ordem de origens com operações de restauração.

  • disabledPackageSources: esta coleção também tem o mesmo significado que arquivos NuGet.Config, em que cada origem afetada é listada por seu nome e um valor true/false que indica se ela está desabilitada. Isso permite que o nome de origem e a URL permaneçam em packageSources sem que ele seja ativado por padrão. Desenvolvedores individuais podem reabilitar a origem definindo seu valor para false em outros arquivos NuGet.Config sem precisar localizar o URL correto novamente. Isso também é útil para fornecer aos desenvolvedores uma lista completa de URLs de origem interna para uma organização, permitindo somente a origem de uma equipe individual por padrão.

  • defaultPushSource: especifica o destino padrão para operações nuget push, substituindo o padrão interno de nuget.org. Os administradores podem implantar essa configuração para evitar publicar pacotes internos no nuget.org público por acidente, visto que os desenvolvedores precisam usar especificamente nuget push -Source para publicar em nuget.org.

Exemplo de NuGetDefaults.Config e aplicativo

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

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

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