Configurações comuns do NuGet

O comportamento do NuGet é impulsionado pelas configurações acumuladas em um ou mais arquivos de configuração (XML) que podem existir nos níveis de solução (projeto, se nenhuma solução for usada), usuário e computador.

Localizações e usos de arquivos de configuração

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 as ferramentas. A maioria dos usuários usa ferramentas que procuram o arquivo de configuração do usuário na ~/.nuget/NuGet pasta. Essas outras ferramentas procuram o arquivo de configuração do usuário na ~/.config/NuGet 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á-los seguindo estas etapas para permitir que você trabalhe com apenas um arquivo de configuração no nível do usuário:

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

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

• O NuGet 3.3 e anteriores usaram uma .nuget pasta para configurações em toda a solução. Essa pasta não é usada no NuGet 3.4+.
• 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, Proou Enterprise. Para migrar as configurações para o NuGet 4.0+, basta copiar o arquivo de configuração para %ProgramFiles(x86)%\NuGet\Config. No Linux, esse local anterior era /etc/opt, e no Mac, /Library/Application Support.

Alterando as configurações

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

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

• Por padrão, as alterações são feitas no arquivo de configuração no nível do usuário. (No Mac/Linux, o local do arquivo de configuração no nível do usuário varia de acordo com as ferramentas)
• 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 são sensíveis a 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.

Definindo um valor

Windows:

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder "C:\packages"

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath "C:\packages"

# Set repositoryPath in solution-level files
dotnet nuget config set repositoryPath "C:\packages" --configfile "C:\my.config"
dotnet nuget config set repositoryPath "c:\packages" --configfile "..\..\my.config"

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

Mac/Linux:

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder /home/packages

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath /home/packages

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

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

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

Criando um novo arquivo de configuração

Usando a CLI do .NET, crie um nuget.config padrão executando dotnet new nugetconfig. Para obter mais informações, consulte os comandos da CLI do dotnet.

Como alternativa, copie manualmente o modelo abaixo para o novo arquivo e, em seguida, use nuget config -configFile <filename> para definir valores:

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

Como as configurações são aplicadas

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

Especificamente, quando um arquivo de configuração não é especificado explicitamente na linha de comando, o NuGet carrega configurações dos diferentes arquivos de configuração na seguinte ordem:

1. (Incomum) O NuGetDefaults.Config arquivo, que contém configurações relacionadas somente às fontes do pacote.
2. O arquivo no nível do computador.
3. O arquivo no nível do usuário.
4. Arquivos encontrados em cada pasta ao longo do caminho desde a raiz da unidade até a pasta atual (onde nuget.exe é invocado ou a que contém a solução do Visual Studio). Por exemplo, se um comando for invocado em c:\A\B\C, o NuGet procurará e carregará arquivos de configuração em c:\, em seguida em c:\A, depois em c:\A\B, e por fim em c:\A\B\C.

Quando um arquivo de configuração for especificado explicitamente na linha de comando, por exemplo nuget -configFile my.config ou dotnet restore --configfile my.config, somente as configurações do arquivo especificado serão usadas.

À medida que o NuGet localiza as configurações nesses arquivos, elas são aplicadas 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 estão "mais próximas" da pasta ou solução atual substituem todas as outras encontradas anteriormente. Por exemplo, a configuração defaultPushSource será substituída NuGetDefaults.Config se existir em qualquer outro arquivo de configuração.
2. Para elementos de coleção (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ó.

Passo a passo das configurações

Digamos que você tenha a seguinte estrutura de pastas em duas unidades separadas:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

Em seguida, você tem quatro NuGet.Config arquivos nos locais a seguir com o conteúdo especificado. (O arquivo no nível do computador não está incluído neste exemplo, mas se comportaria de forma semelhante ao arquivo no nível do usuário.)

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

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</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>

Em seguida, o NuGet carrega e aplica as configurações da seguinte maneira, dependendo de onde ele é invocado:

• Invocado de disk_drive_1/users: somente o repositório padrão listado no arquivo de configuração no nível do 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 de nível de usuário (A) é carregado primeiro e, em seguida, o NuGet vai para a raiz do disk_drive_2 arquivo e localiza (B). O NuGet também procura um arquivo de configuração, /tmp mas não encontra um. Como resultado, o repositório padrão nuget.org é usado, a restauração de pacotes está 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 de usuário (A) é carregado primeiro e, em seguida, o NuGet carrega o arquivo (B) da raiz de disk_drive_2, seguido pelo arquivo (C). As configurações em (C) substituem aquelas em (B) e (A), de modo que onde os pacotes são instalados é disk_drive_2/Project1/External/Packages em vez de disk_drive_2/tmp. Além disso, como (C) limpa <packageSources>, nuget.org não está mais disponível como uma fonte, 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 pelo arquivo (B) e arquivo (D). Como packageSources não está limpo, ambos nuget.orghttps://MyPrivateRepo/DQ/nuget estão disponíveis como fontes. 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 para arquivos de configuração de todo o usuário adicionais. Isso permite que fornecedores de terceiros adicionem arquivos de configuração de usuário adicionais sem elevação. Esses arquivos de configuração são encontrados na pasta de configuração geral do usuário padrão em uma config subpasta. Todos os arquivos que terminam com .config ou .Config serão considerados. Esses arquivos não podem ser editados pelas ferramentas padrão.

Arquivo padrão do NuGet

O NuGetDefaults.Config é incomum e só pode especificar fontes de pacotes das quais os pacotes são instalados e atualizados, ou controlar o destino padrão de publicação de pacotes com nuget push.

Como os administradores podem convenientemente (usando a Política de Grupo, por exemplo) implantar arquivos consistentes NuGetDefaults.Config em computadores de desenvolvedor e build, eles podem garantir que todos na organização estejam usando fontes de pacote consistentes, incluindo ou não nuget.org.

NuGetDefaults.Config localização

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

Configurações de NuGetDefaults.Config

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

• disabledPackageSources: essa coleção também tem o mesmo significado que nos arquivos NuGet.Config onde cada fonte afetada é listada por seu nome e um true/false valor que indica se está desabilitada. Isso permite que o nome de origem e a URL permaneçam em packageSources, sem que ele esteja ativado por padrão. Desenvolvedores individuais podem então reativar a origem definindo o valor da origem para false em outros arquivos NuGet.Config sem precisar encontrar a URL correta novamente. Isso também é útil para fornecer aos desenvolvedores uma lista completa de URLs de origem internas para uma organização, permitindo apenas a origem de uma equipe individual por padrão.

• defaultPushSource: especifica o destino padrão para operações de nuget push, substituindo o padrão interno de nuget.org. Os administradores podem implantar essa configuração para evitar a publicação de pacotes internos para o público nuget.org por acidente, pois os desenvolvedores precisam usar nuget push -Source especificamente para publicar 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>