Variáveis de ambiente do .NET

  • Artigo

Este artigo se aplica a: ✔️ SDK do .NET Core 3.1 e versões posteriores

Neste artigo, você aprenderá sobre as variáveis de ambiente usadas pelo .NET. Algumas variáveis de ambiente são usadas pelo runtime do .NET, enquanto outras são usadas apenas pelo SDK do .NET e pela CLI do .NET. Algumas variáveis de ambiente são usadas pelos três componentes.

Variável de ambiente do runtime do .NET

DOTNET_SYSTEM_NET_HTTP_*

Há várias configurações globais de variável de ambiente HTTP:

  • DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
    • Indica se a propagação de atividade do manipulador de diagnóstico das configurações HTTP globais deve ser habilitada ou não.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
    • Quando definida como false ou 0, desabilita o suporte HTTP/2, que é habilitado por padrão.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
    • Quando definida como true ou 1, habilita o suporte HTTP/3, que é desabilitado por padrão.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
    • Quando definida como false ou 0, substitui o padrão e desabilita o algoritmo de dimensionamento de janela dinâmica HTTP/2.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE
    • O padrão é 16 MB. Quando substituído, o tamanho máximo da janela de recebimento do fluxo HTTP/2 não pode ser inferior a 65.535.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER
    • O valor padrão é 1.0. Quando substituído, valores mais altos resultam em uma janela mais curta, mas em downloads mais lentos. Não pode ser inferior a 0.

DOTNET_SYSTEM_GLOBALIZATION_*

  • DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: confira o modo invariável definido.
  • DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY: especifica se apenas as culturas predefinidas devem ser carregadas.
  • DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU: indica se o ICU (International Components of Unicode) local do aplicativo deve ser usado. Para obter mais informações, veja ICU local do aplicativo.

Definir o modo invariável

Os aplicativos podem habilitar o modo invariável usando um dos seguintes métodos:

  1. No arquivo de projeto:

    <PropertyGroup>
    <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

  2. No arquivo runtimeconfig.json:

    {
    "runtimeOptions": {
        "configProperties": {
            "System.Globalization.Invariant": true
        }
    }
}

  3. Definindo o valor DOTNET_SYSTEM_GLOBALIZATION_INVARIANT da variável de ambiente como true ou 1.

Importante

Um valor definido no arquivo de projeto ou no runtimeconfig.json tem uma prioridade maior do que a variável de ambiente.

Para obter mais informações, confira Modo invariável de globalização do .NET.

DOTNET_SYSTEM_GLOBALIZATION_USENLS

Isso se aplica somente ao Windows. Para que a globalização use o NLS (suporte ao idioma nacional), defina DOTNET_SYSTEM_GLOBALIZATION_USENLS como true ou 1. Para não usá-lo, defina DOTNET_SYSTEM_GLOBALIZATION_USENLS como false ou 0.

DOTNET_SYSTEM_NET_SOCKETS_*

Esta seção se concentra em duas variáveis de ambiente System.Net.Sockets:

  • DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
  • DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT

As continuações do soquete são enviadas do thread de eventos ao System.Threading.ThreadPool. Isso evita continuações que bloqueiam o tratamento de evento. Para permitir que as continuações sejam executadas diretamente no thread de eventos, defina DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS como 1. Isso está desabilitado por padrão.

Observação

Essa configuração pode piorar o desempenho quando há um trabalho dispendioso que mantém o thread de E/S por mais tempo do que o necessário. Faça um teste para verificar se essa configuração ajuda no desempenho.

Usando parâmetros de comparação do TechEmpower que geram muitas leituras e gravações pequenas de soquete com uma carga muito alta, um só mecanismo de soquete pode ocupar até trinta núcleos de CPU x64 e oito Arm64. A grande maioria dos cenários reais nunca gera uma carga tão grande (centenas de milhares de solicitações por segundo), portanto, um só produtor é quase sempre suficiente. No entanto, para ter certeza de que cargas extremas podem ser manipuladas, use DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT para substituir o valor calculado. Quando ele não é substituído, o seguinte valor é usado:

DOTNET_SYSTEM_NET_DISABLEIPV6

Ajuda a determinar se o IPv6 está desabilitado ou não. Quando definida como true ou 1, o IPv6 está desabilitado, a menos que haja outra especificação em System.AppContext.

DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER

Você pode usar um dos seguintes mecanismos para configurar um processo para usar o HttpClientHandler mais antigo:

No código, use a classe AppContext:

AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);

A opção AppContext também pode ser definida por um arquivo de configuração. Para obter mais informações sobre como configurar opções, confira AppContext para consumidores de biblioteca.

O mesmo pode ser obtido por meio da variável de ambiente DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER. Para recusar, defina o valor como false ou 0.

Observação

Do .NET 5 em diante, essa configuração para usar HttpClientHandler não está mais disponível.

DOTNET_Jit* e DOTNET_GC*

Há dois recursos relacionados a estresse para as informações JIT e da GC geradas por JIT: estresse JIT e estresse de espaço de GC. Durante o desenvolvimento, esses recursos são uma forma de descobrir casos de borda e cenários mais "reais" sem precisar desenvolver aplicativos complexos. As seguintes variáveis de ambiente estão disponíveis:

  • DOTNET_JitStress
  • DOTNET_JitStressModeNamesOnly
  • DOTNET_GCStress

Estresse JIT

A habilitação do estresse JIT pode ser feita de várias maneiras. Defina DOTNET_JitStress como um valor inteiro diferente de zero para gerar diferentes níveis de otimizações JIT com base em um hash do nome do método. Para aplicar todas as otimizações, defina DOTNET_JitStress=2, por exemplo. Outra maneira de habilitar o estresse JIT é definir DOTNET_JitStressModeNamesOnly=1 e solicitar os modos de estresse, delimitados por espaço, na variável DOTNET_JitStressModeNames.

Como exemplo, considere:

DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS

Estresse de espaço de GC

A habilitação do estresse de espaço de GC faz com que as GCs sempre ocorram em locais específicos e isso ajuda a rastrear espaços de GC. O estresse de espaço de GC pode ser habilitado usando a variável de ambiente DOTNET_GCStress.

Para obter mais informações, confira Investigar o estresse JIT e o estresse de espaço de GC.

Barreiras de memória JIT

O gerador de código para Arm64 permite que todas as instruções MemoryBarriers sejam removidas definindo DOTNET_JitNoMemoryBarriers como 1.

DOTNET_RUNNING_IN_CONTAINER e DOTNET_RUNNING_IN_CONTAINERS

As imagens oficiais do .NET (Windows e Linux) definem as variáveis de ambiente conhecidas:

  • DOTNET_RUNNING_IN_CONTAINER
  • DOTNET_RUNNING_IN_CONTAINERS

Esses valores são usados para determinar quando as cargas de trabalho do ASP.NET Core estão em execução no contexto de um contêiner.

DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION

Quando Console.IsOutputRedirected é true, você pode emitir código de cor ANSI definindo DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION como 1 ou true.

  • DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL: quando 1 ou true, o formato padrão da ID de atividade é hierárquico.
  • DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: em execuções de Depuração, o rastreamento pode ser habilitado quando essa opção é true.

DOTNET_DiagnosticPorts

Configura pontos de extremidade alternativos em que as ferramentas de diagnóstico podem se comunicar com o runtime do .NET. Confira a documentação da Porta de Diagnóstico para obter mais informações.

DOTNET_DefaultDiagnosticPortSuspend

Quando definida como 1, configura o runtime para ser pausado durante a inicialização e aguardar o comando Diagnostics IPC ResumeStartup da porta de diagnóstico especificada. Assume o padrão de 0. Confira a documentação da Porta de Diagnóstico para obter mais informações.

DOTNET_EnableDiagnostics

Quando definido como 0, desabilita a depuração, a criação de perfil e outros diagnósticos por meio da Porta de diagnóstico e não pode ser substituído por outras configurações de diagnóstico. Assume o padrão de 1.

DOTNET_EnableDiagnostics_IPC

A partir do .NET 8, quando definido como 0, desabilita a Porta de diagnóstico e não pode ser substituído por outras configurações de diagnóstico. Assume o padrão de 1.

DOTNET_EnableDiagnostics_Debugger

A partir do .NET 8, quando definido como 0, desabilita a depuração e não pode ser substituído por outras configurações de diagnóstico. Assume o padrão de 1.

DOTNET_EnableDiagnostics_Profiler

A partir do .NET 8, quando definido como 0, desabilita a criação de perfil e não pode ser substituído por outras configurações de diagnóstico. Assume o padrão de 1.

Variáveis EventPipe

Confira Variáveis de ambiente EventPipe para obter mais informações.

  • DOTNET_EnableEventPipe: quando definida como 1, habilita o rastreamento via EventPipe.
  • DOTNET_EventPipeOutputPath: o caminho de saída em que o rastreamento será gravado.
  • DOTNET_EventPipeOutputStreaming: quando definida como 1, habilita o streaming para o arquivo de saída enquanto o aplicativo está em execução. Por padrão, as informações de rastreamento são acumuladas em um buffer circular e o conteúdo é gravado durante o desligamento do aplicativo.

Variáveis de ambiente do SDK e da CLI do .NET

DOTNET_ROOT, DOTNET_ROOT(x86)

Especifica o local dos runtimes do .NET, quando eles não estão instalados no local padrão. O local padrão no Windows é C:\Program Files\dotnet. O local padrão no macOS é /usr/local/share/dotnet. O local padrão no Linux varia dependendo do método de distribuição e parcelamento. O local padrão no Ubuntu 22.04 é /usr/share/dotnet (quando instalado a partir o packages.microsoft.com) ou /usr/lib/dotnet (quando instalado no feed do Jammy). Para saber mais, consulte os recursos a seguir:

Essa variável de ambiente é usada somente ao executar aplicativos por meio de executáveis gerados (apphosts). DOTNET_ROOT(x86) é usado quando um executável de 32 bits é executado em um sistema operacional de 64 bits.

DOTNET_HOST_PATH

Especifica o caminho absoluto para um dotnet host (dotnet.exe no Windows, dotnet no Linux e no macOS) que foi usado para iniciar o processo dotnet em execução no momento. Isso é usado pelo SDK do .NET para ajudar as ferramentas executadas durante os comandos do SDK do .NET a garantir que usem o mesmo runtime dotnet para todos os processos dotnet filho criados durante o comando. As ferramentas e as tarefas do MSBuild no SDK que invocam binários por meio do host dotnet devem honrar essa variável de ambiente para garantir uma experiência consistente.

As ferramentas que invocam dotnet durante um comando do SDK devem usar o seguinte algoritmo para localizá-lo:

  • se DOTNET_HOST_PATH estiver definido, use esse valor diretamente
  • caso contrário, confie em dotnet por meio de PATH do sistema

Observação

DOTNET_HOST_PATH não é uma solução geral para localizar o host dotnet. Destina-se apenas a ser usado por ferramentas que são invocadas pelo SDK do .NET.

DOTNET_LAUNCH_PROFILE

O comando executar dotnet define essa variável para o perfil de inicialização selecionado.

Dado o seguinte arquivo launchSettings.json :

{
  "profiles": {
    "First": {
      "commandName": "Project",
    },
    "Second": {
      "commandName": "Project",
    }
  }
}

E o seguinte arquivo Program.cs :

var value = Environment.GetEnvironmentVariable("DOTNET_LAUNCH_PROFILE");
Console.WriteLine($"DOTNET_LAUNCH_PROFILE={value}");

Os seguintes cenários produzem a saída mostrada:

  • Perfil de inicialização especificado e existente

    $ dotnet run --launch-profile First
DOTNET_LAUNCH_PROFILE=First

  • Perfil de inicialização não especificado, primeiro selecionado

    $ dotnet run
DOTNET_LAUNCH_PROFILE=First

  • Perfil de inicialização especificado, mas não existe

    $ dotnet run --launch-profile Third
The launch profile "Third" could not be applied.
A launch profile with the name 'Third' doesn't exist.
DOTNET_LAUNCH_PROFILE=

  • Iniciar sem perfil

    $ dotnet run --no-launch-profile
DOTNET_LAUNCH_PROFILE=

NUGET_PACKAGES

A pasta de pacotes globais. Se não estiver definido, o padrão será ~/.nuget/packages em Unix ou %userprofile%\.nuget\packages no Windows.

DOTNET_SERVICING

Especifica o local do índice de manutenção a ser usado pelo host compartilhado ao carregar o runtime.

Especifica se as mensagens de boas-vindas e de telemetria do .NET são exibidas na primeira execução. Defina como true para silenciar essas mensagens (valores true, 1 e yes aceitos) ou defina como false para permiti-las (valores false, 0 ou no aceitos). Se ela não for definida, o padrão será false e as mensagens serão exibidas na primeira execução. Esse sinalizador não afeta a telemetria (veja DOTNET_CLI_TELEMETRY_OPTOUT para recusar o envio de telemetria).

DOTNET_CLI_PERF_LOG

Especifica se os detalhes de desempenho sobre a sessão da CLI atual são registrados. Habilitado quando definido como 1, true ou yes. Isso está desabilitado por padrão.

DOTNET_GENERATE_ASPNET_CERTIFICATE

Especifica se um certificado do ASP.NET Core deve ser gerado. O valor padrão é true, mas pode ser substituído definindo essa variável de ambiente como 0, false ou no.

DOTNET_ADD_GLOBAL_TOOLS_TO_PATH

Especifica se as ferramentas globais devem ser adicionadas à variável de ambiente PATH. O padrão é true. Para não adicionar ferramentas globais ao caminho, defina como 0, false ou no.

DOTNET_CLI_TELEMETRY_OPTOUT

Especifica se os dados sobre o uso de ferramentas .NET são coletados e enviados à Microsoft. Definido como true para recusar o recurso de telemetria (os valores true, 1 ou yes são aceitos). Caso contrário, definido como false para aceitar os recursos de telemetria (os valores false, 0 ou no são aceitos). Se não estiver definido, o padrão será false, e o recurso de telemetria estará ativo.

DOTNET_SKIP_FIRST_TIME_EXPERIENCE

Se DOTNET_SKIP_FIRST_TIME_EXPERIENCE estiver definido como true, NuGetFallbackFolder não será expandido para o disco e uma mensagem de boas-vindas e um aviso de telemetria mais breves serão mostrados.

Observação

Essa variável de ambiente não tem mais suporte no .NET Core 3.0 e posterior. Use DOTNET_NOLOGO como uma substituição.

DOTNET_MULTILEVEL_LOOKUP

Especifica se o runtime, a estrutura compartilhada ou o SDK do .NET são resolvidos na localização global. Se não estiver definida, o padrão será 1 (true lógico). Defina o valor como 0 (false lógico) para que a resolução não ocorra por meio da localização global e para ter instalações isoladas do .NET. Para obter mais informações sobre a pesquisa de vários níveis, consulte Pesquisa SharedFX de vários níveis.

Observação

Essa variável de ambiente só se aplica a aplicativos direcionados ao .NET 6 e versões anteriores. do .NET 7 em diante, o .NET procura estruturas apenas em uma localização. Para obter mais informações, confira A pesquisa em vários níveis está desabilitada.

DOTNET_ROLL_FORWARD

Determina o comportamento de roll forward. Para saber mais, confira a opção --roll-forward para o comando dotnet.

DOTNET_ROLL_FORWARD_TO_PRERELEASE

Se definida como 1 (habilitada), habilita o roll forward de uma versão de lançamento para uma versão de pré-lançamento. Por padrão (0 – Desabilitado), quando uma versão de lançamento do runtime do .NET for solicitada, o roll forward vai considerar apenas as versões de lançamento instaladas.

Para saber mais, confira a opção --roll-forward para o comando dotnet

DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX

Desabilita o roll forward da versão secundária, se definido como 0. Essa configuração foi substituída no .NET Core 3.0 por DOTNET_ROLL_FORWARD. As novas configurações devem ser usadas.

DOTNET_CLI_FORCE_UTF8_ENCODING

Força o uso da codificação UTF-8 no console, mesmo para versões mais antigas de Windows 10 que não dão suporte total ao UTF-8. Para obter mais informações, confira SDK não altera mais a codificação do console após a conclusão.

DOTNET_CLI_UI_LANGUAGE

Define o idioma da interface do usuário da CLI usando um valor de localidade, como en-us. Os valores com suporte são os mesmos do Visual Studio. Para obter mais informações, confira a seção sobre como alterar o idioma do instalador na documentação de instalação do Visual Studio. As regras do gerenciador de recursos do .NET se aplicam, portanto, você não precisa escolher uma correspondência exata, também é possível escolher descendentes na CultureInfo árvore. Por exemplo, se você definir essa opção como fr-CA, a CLI vai encontrar e usar as traduções de fr. Se você a definir como um idioma sem suporte, a CLI retornará ao inglês.

DOTNET_DISABLE_GUI_ERRORS

Para executáveis gerados habilitados para GUI, essa opção desabilita o pop-up da caixa de diálogo, que normalmente é exibido para determinadas classes de erros. Ela só grava em stderr e é encerrada nesses casos.

DOTNET_ADDITIONAL_DEPS

Equivalente à opção --additional-deps da CLI.

DOTNET_RUNTIME_ID

Substitui o RID detectado.

DOTNET_SHARED_STORE

Local do "repositório compartilhado" para o qual a resolução do assembly retorna em alguns casos.

DOTNET_STARTUP_HOOKS

Lista de assemblies dos quais os ganchos de inicialização são carregados e executados.

DOTNET_BUNDLE_EXTRACT_BASE_DIR

Especifica um diretório ao qual um aplicativo de arquivo único é extraído antes de ser executado.

Para obter mais informações, confira executáveis de arquivo único.

DOTNET_CLI_CONTEXT_*

  • DOTNET_CLI_CONTEXT_VERBOSE: para habilitar um contexto detalhado, defina essa opção como true.
  • DOTNET_CLI_CONTEXT_ANSI_PASS_THRU: para habilitar uma passagem ANSI, defina essa opção como true.

DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE

Desabilita o download em segundo plano de manifestos de publicidade para cargas de trabalho. O padrão é false – Não desabilitado. Se definida como true, o download está desabilitado. Para saber mais, confira Manifestos de publicidade.

DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS

Especifica o número mínimo de horas entre downloads em segundo plano de manifestos de publicidade para cargas de trabalho. O padrão é 24, que não é mais frequente do que uma vez por dia. Para saber mais, consulte Manifestos de publicidade.

DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT

Especifica se as ferramentas locais do SDK do .NET pesquisam arquivos de manifesto da ferramenta na pasta raiz no Windows. O padrão é false.

COREHOST_TRACE

Controla o rastreamento de diagnóstico dos componentes de hospedagem, como dotnet.exe, hostfxr e hostpolicy.

  • COREHOST_TRACE=[0/1] – O padrão é 0 – Rastreamento desabilitado. Se definida como 1, o rastreamento de diagnóstico está habilitado.

  • COREHOST_TRACEFILE=<file path> – Só entra em vigor quando o rastreamento está habilitado pela configuração COREHOST_TRACE=1. Quando definida, as informações de rastreamento são gravadas no arquivo especificado. Caso contrário, as informações de rastreamento são gravadas em stderr.

  • COREHOST_TRACE_VERBOSITY=[1/2/3/4] – O padrão é 4. A configuração é usada somente quando o rastreamento é habilitado por meio de COREHOST_TRACE=1.

    • 4 – Todas as informações de rastreamento são gravadas
    • 3 – Somente mensagens informativas, de aviso e de erro são gravadas
    • 2 – Somente mensagens de aviso e de erro são gravadas
    • 1 – Somente mensagens de erro são gravadas

A maneira típica de obter informações detalhadas de rastreamento sobre a inicialização do aplicativo é definir COREHOST_TRACE=1 e COREHOST_TRACEFILE=host_trace.txt, depois executar o aplicativo. Um arquivo host_trace.txt será criado no diretório atual com as informações detalhadas.

SuppressNETCoreSdkPreviewMessage

Se definida como true, a invocação de dotnet não produzirá um aviso quando um SDK de versão prévia estiver sendo usado.

Configurar o MSBuild na CLI do .NET

Para executar o MSBuild fora do processo, defina a variável de ambiente DOTNET_CLI_RUN_MSBUILD_OUTOFPROC como 1, true ou yes. Por padrão, o MSBuild será executado no processo. Para forçar o MSBuild a usar um processo de longa duração de nó de trabalho externo para a criação de projetos, defina DOTNET_CLI_USE_MSBUILDNOINPROCNODE como 1, true ou yes. Isso definirá a variável de ambiente MSBUILDNOINPROCNODE como 1, que é conhecido como MSBuild Server V1, pois o processo de entrada encaminha a maior parte do trabalho a ele.

DOTNET_MSBUILD_SDK_RESOLVER_*

Essas são substituições usadas para forçar as tarefas e os destinos do SDK resolvidos a serem provenientes de um determinado diretório base e relatar uma determinada versão ao MSBuild, que pode ser null quando desconhecido. Um dos principais casos de uso para isso é testar tarefas e destinos do SDK sem implantá-los usando o SDK do .NET Core.

  • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR: substitui o diretório do SDK do .NET.
  • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER: substitui a versão do SDK do .NET.
  • DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: substitui o caminho de diretório do dotnet.exe.

DOTNET_NEW_PREFERRED_LANG

Configura a linguagem de programação padrão do comando dotnet new quando a opção -lang|--language é omitida. O valor padrão é C#. Os valores válidos são C#, F# ou VB. Para obter mais informações, confira dotnet new.

Variáveis de ambiente dotnet watch

Para obter informações sobre as configurações dotnet watch disponíveis como variáveis de ambiente, confira Variáveis de ambiente dotnet watch.

Confira também