Variáveis de ambiente .NET

  • Artigo

Este artigo aplica-se 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 tempo de execução 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áveis de ambiente de tempo de execução do .NET

DOTNET_SYSTEM_NET_HTTP_*

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

  • DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
    • Indica se a propagação de atividade do manipulador de diagnóstico deve ou não ser habilitada para configurações HTTP globais.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
    • Quando definido como false ou 0, desativa o suporte a HTTP/2, que é ativado por padrão.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
    • Quando definido como true ou 1, habilita o suporte a HTTP/3, que é desativado por padrão.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
    • Quando definido como false ou 0, substitui o padrão e desabilita o algoritmo de dimensionamento dinâmico de janela 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 de fluxo HTTP/2 não pode ser inferior a 65.535.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER
    • O padrão é 1.0. Quando substituídos, valores mais altos resultam em uma janela mais curta, mas downloads mais lentos. Não pode ser inferior a 0.

DOTNET_SYSTEM_GLOBALIZATION_*

  • DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: Consulte definir modo invariante.
  • DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY: Especifica se as culturas predefinidas devem ser carregadas.
  • DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU: Indica se os Componentes Internacionais do Unicode (ICU) locais devem ser usados pelo aplicativo. Para obter mais informações, consulte UTI local do aplicativo.

Definir modo invariante

Os aplicativos podem habilitar o modo invariante de qualquer uma das seguintes maneiras:

  1. No arquivo do 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 runtimeconfig.json tem uma prioridade maior do que a variável de ambiente.

Para obter mais informações, consulte Modo invariante de globalização do .NET.

DOTNET_SYSTEM_GLOBALIZATION_USENLS

Isto aplica-se apenas ao Windows. Para que a globalização use o NLS (National Language Support), defina DOTNET_SYSTEM_GLOBALIZATION_USENLS como ou 1true . Para não usá-lo, defina DOTNET_SYSTEM_GLOBALIZATION_USENLS como um false ou 0.

DOTNET_SYSTEM_NET_SOCKETS_*

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

  • DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
  • DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT

As continuações de soquete são despachadas para o System.Threading.ThreadPool thread do evento. Isso evita que continuações bloqueiem a manipulação de eventos. Para permitir que as continuações sejam executadas diretamente no thread de eventos, defina DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS como 1. Está desativada por predefinição.

Nota

Essa configuração pode piorar o desempenho se houver um trabalho caro que acabará segurando o thread de E/S por mais tempo do que o necessário. Teste para verificar se essa configuração ajuda no desempenho.

Usando benchmarks TechEmpower que geram muitas leituras e gravações de soquete pequenas sob uma carga muito alta, um único mecanismo de soquete é capaz de manter ocupado até trinta núcleos de CPU x64 e oito Arm64. A grande maioria dos cenários da vida real nunca gerará uma carga tão grande (centenas de milhares de solicitações por segundo), e ter um único produtor é quase sempre suficiente. No entanto, para ter certeza de que cargas extremas podem ser manipuladas, você pode usar DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT para substituir o valor calculado. Quando não substituído, o seguinte valor é usado:

DOTNET_SYSTEM_NET_DISABLEIPV6

Ajuda a determinar se o protocolo IP versão 6 (IPv6) está ou não desativado. Quando definido como um true ou 1, o IPv6 é desativado, a menos que especificado de outra forma no System.AppContext.

DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER

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

Do código, use a AppContext classe:

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

O AppContext switch também pode ser definido por um arquivo de configuração. Para obter mais informações sobre como configurar switches, consulte AppContext para consumidores de biblioteca.

O mesmo pode ser conseguido através da variável DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLERambiente. Para desativar, defina o valor como um false ou 0.

Nota

A partir do .NET 5, essa configuração a ser usada HttpClientHandler não está mais disponível.

DOTNET_Jit* e DOTNET_GC*

Há dois recursos relacionados a estresse para as informações de GC geradas por JIT e JIT: Tensão JIT e Tensão de Furo GC. Esses recursos fornecem uma maneira durante o desenvolvimento de descobrir casos de borda e mais cenários do "mundo real" sem ter que desenvolver aplicativos complexos. As seguintes variáveis de ambiente estão disponíveis:

  • DOTNET_JitStress
  • DOTNET_JitStressModeNamesOnly
  • DOTNET_GCStress

Stress JIT

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

Como exemplo, considere:

DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS

Tensão GC Hole

Habilitar o GC Hole Stress faz com que os GCs sempre ocorram em locais específicos e isso ajuda a rastrear os orifícios GC. GC Hole Stress pode ser ativado usando a DOTNET_GCStress variável de ambiente.

Para obter mais informações, consulte Investigando a tensão do furo JIT e GC.

Barreiras de memória JIT

O gerador de código para Arm64 permite que todas as MemoryBarriers instruções 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 bem 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 sendo executadas no contexto de um contêiner.

DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION

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

  • DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL: Quando 1 ou true, o formato padrão de ID de atividade é hierárquico.
  • DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: Ao executar como Depuração, o rastreamento pode ser ativado quando isso é true.

DOTNET_DiagnosticPorts

Configura pontos de extremidade alternativos onde as ferramentas de diagnóstico podem se comunicar com o tempo de execução do .NET. Consulte a documentação da Porta de diagnóstico para obter mais informações.

DOTNET_DefaultDiagnosticPortSuspend

Configura o tempo de execução para pausar durante a inicialização e aguardar o comando Diagnostics IPC ResumeStartup da porta de diagnóstico especificada quando definido como 1. O padrão é 0. Consulte a documentação da Porta de diagnóstico para obter mais informações.

DOTNET_EnableDiagnostics

Quando definido como 0, desativa a depuração, a criação de perfis 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. O padrão é 1.

DOTNET_EnableDiagnostics_IPC

A partir do .NET 8, quando definido como 0, desativa a Porta de Diagnóstico e não pode ser substituído por outras configurações de diagnóstico. O padrão é 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. O padrão é 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. O padrão é 1.

Variáveis EventPipe

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

  • DOTNET_EnableEventPipe: Quando definido como 1, permite o rastreamento via EventPipe.
  • DOTNET_EventPipeOutputPath: O caminho de saída onde o rastreamento será gravado.
  • DOTNET_EventPipeOutputStreaming: Quando definido como 1, permite 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 no desligamento do aplicativo.

Variáveis de ambiente do .NET SDK e CLI

DOTNET_ROOT, DOTNET_ROOT(x86)

Especifica o local dos tempos de execução do .NET, se eles não estiverem 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 da distro e do método de parcelamento. O local padrão no Ubuntu 22.04 é /usr/share/dotnet (quando instalado a partir de ) ou /usr/lib/dotnet (quando instalado a partir packages.microsoft.comdo feed Jammy). Para obter mais informações, consulte os seguintes recursos:

Essa variável de ambiente é usada somente ao executar aplicativos por meio de executáveis gerados (apphosts). DOTNET_ROOT(x86) é usado em vez disso ao executar um executável de 32 bits 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 em execução dotnet no momento. Isso é usado pelo SDK do .NET para ajudar as ferramentas executadas durante os comandos do SDK do .NET a garantir que eles usem o mesmo dotnet tempo de execução para quaisquer processos filho dotnet criados durante a duração do comando. Espera-se que as ferramentas e as tarefas do MSBuild dentro do SDK que invocam binários por meio do dotnet host honrem essa variável de ambiente para garantir uma experiência consistente.

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

  • se DOTNET_HOST_PATH estiver definido, use esse valor diretamente
  • caso contrário, conte com dotnet através do sistema PATH

Nota

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

DOTNET_LAUNCH_PROFILE

O comando dotnet run 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 .cs programa:

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

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

  • Perfil de inicialização especificado e existe

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

  • Perfil de lançamento 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=

  • Lançamento 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á no ~/.nuget/packages Unix ou %userprofile%\.nuget\packages no Windows.

DOTNET_SERVICING

Especifica o local do índice de serviço a ser usado pelo host compartilhado ao carregar o tempo de execução.

Especifica se as mensagens de boas-vindas e telemetria do .NET são exibidas na primeira execução. Defina como true para silenciar essas mensagens (valores , ou aceitos) ou definido para false permitir que eles (valores falsetrue, 01ou yesno aceitos). Se não estiver definido, o padrão é false e as mensagens serão exibidas na primeira execução. Este sinalizador não afeta a telemetria (consulte DOTNET_CLI_TELEMETRY_OPTOUT para desativar o envio de telemetria).

DOTNET_CLI_PERF_LOG

Especifica se os detalhes de desempenho sobre a sessão atual da CLI são registrados. Ativado quando definido como 1, trueou yes. Opção desativada por predefinição.

DOTNET_GENERATE_ASPNET_CERTIFICATE

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

DOTNET_ADD_GLOBAL_TOOLS_TO_PATH

Especifica se as ferramentas globais devem ser adicionadas PATH à variável de ambiente. A predefinição é true. Para não adicionar ferramentas globais ao caminho, defina como 0, falseou no.

DOTNET_CLI_TELEMETRY_OPTOUT

Especifica se os dados sobre o uso das ferramentas .NET são coletados e enviados à Microsoft. Defina como true para desativar o recurso de telemetria (valores true, 1ou yes aceitos). Caso contrário, defina como false optar pelos recursos de telemetria (valores false, 0ou no 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, o não será expandido para disco e uma mensagem de boas-vindas mais curta e um aviso de telemetria NuGetFallbackFolder serão exibidos.

Nota

Essa variável de ambiente não é mais suportada no .NET Core 3.0 e posterior. Use DOTNET_NOLOGO como substituto.

DOTNET_MULTILEVEL_LOOKUP

Especifica se o tempo de execução do .NET, a estrutura compartilhada ou o SDK são resolvidos a partir do local global. Se não estiver definido, o padrão será 1 (lógico true). Defina o valor como 0 (lógico false) para não resolver a partir do local global e ter instalações .NET isoladas. Para obter mais informações sobre pesquisa de vários níveis, consulte Pesquisa SharedFX de vários níveis.

Nota

Essa variável de ambiente só se aplica a aplicativos destinados ao .NET 6 e versões anteriores. A partir do .NET 7, o .NET procura apenas estruturas em um local. Para obter mais informações, consulte A pesquisa em vários níveis está desativada.

DOTNET_ROLL_FORWARD

Determina o comportamento de roll forward. Para obter mais informações, consulte a --roll-forward opção para o dotnet comando.

DOTNET_ROLL_FORWARD_TO_PRERELEASE

Se definido como 1 (habilitado), permite avançar para uma versão de pré-lançamento a partir de uma versão de lançamento. Por padrão (0 - disabled), quando uma versão de lançamento do tempo de execução do .NET é solicitada, o roll-forward considerará apenas as versões de lançamento instaladas.

Para obter mais informações, consulte a --roll-forward opção para o dotnet comando

DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX

Desativa a versão secundária roll-forward, se definido como 0. Essa configuração é substituída no .NET Core 3.0 por DOTNET_ROLL_FORWARD. Em vez disso, devem ser utilizadas as novas definições.

DOTNET_CLI_FORCE_UTF8_ENCODING

Força o uso da codificação UTF-8 no console, mesmo para versões mais antigas do Windows 10 que não suportam totalmente UTF-8. Para obter mais informações, consulte SDK não altera mais a codificação do console quando terminar.

DOTNET_CLI_UI_LANGUAGE

Define o idioma da interface do usuário da CLI usando um valor de localidade como en-us. Os valores suportados são os mesmos do Visual Studio. Para obter mais informações, consulte 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 — você também pode escolher descendentes na CultureInfo árvore. Por exemplo, se você defini-lo como fr-CA, a CLI localizará e usará as fr traduções. Se você defini-lo para um idioma que não é suportado, a CLI retornará para o inglês.

DOTNET_DISABLE_GUI_ERRORS

Para executáveis gerados habilitados para GUI - desativa o pop-up de diálogo, que normalmente é exibido para certas classes de erros. Só escreve e stderr sai nesses casos.

DOTNET_ADDITIONAL_DEPS

Equivalente à opção --additional-depsCLI .

DOTNET_RUNTIME_ID

Substitui o RID detetado.

DOTNET_SHARED_STORE

Localização da "loja compartilhada" à qual a resolução de montagem recai em alguns casos.

DOTNET_STARTUP_HOOKS

Lista de assemblies a partir dos quais carregar e executar ganchos de inicialização.

DOTNET_BUNDLE_EXTRACT_BASE_DIR

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

Para obter mais informações, consulte Executáveis de arquivo único.

DOTNET_CLI_CONTEXT_*

  • DOTNET_CLI_CONTEXT_VERBOSE: Para habilitar um contexto detalhado, defina como true.
  • DOTNET_CLI_CONTEXT_ANSI_PASS_THRU: Para habilitar uma passagem ANSI, defina 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 desativado. Se definido como true, o download será desativado. Para obter mais informações, consulte 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 é , que não é 24mais freqüentemente do que uma vez por dia. Para obter mais informações, 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. A predefinição é false.

COREHOST_TRACE

Controla o rastreamento de diagnósticos dos componentes de hospedagem, como dotnet.exe, hostfxre hostpolicy.

  • COREHOST_TRACE=[0/1] - o padrão é 0 - rastreamento desativado. Se definido como 1, o rastreamento de diagnóstico estará habilitado.

  • COREHOST_TRACEFILE=<file path> - só produz efeitos se o rastreio for ativado através da definição COREHOST_TRACE=1. Quando definidas, as informações de rastreamento são gravadas no arquivo especificado; caso contrário, as informações de rastreamento serão gravadas em stderr.

  • COREHOST_TRACE_VERBOSITY=[1/2/3/4] - o padrão é 4. A definição é utilizada apenas quando o rastreio está ativado através do COREHOST_TRACE=1.

    • 4 - todas as informações de rastreio são escritas
    • 3 - apenas mensagens informativas, de aviso e de erro são escritas
    • 2 - apenas mensagens de aviso e erro são escritas
    • 1 - apenas mensagens de erro são escritas

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

SuppressNETCoreSdkPreviewMessage

Se definido como true, a dotnet invocação não produzirá um aviso quando um SDK de visualização estiver sendo usado.

Configurar o MSBuild na CLI do .NET

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

DOTNET_MSBUILD_SDK_RESOLVER_*

Essas são substituições que são usadas para forçar as tarefas e destinos resolvidos do SDK a vir de um determinado diretório base e relatar uma determinada versão para o MSBuild, que pode ser null se desconhecido. Um caso de uso importante 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 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 do diretório dotnet.exe .

DOTNET_NEW_PREFERRED_LANG

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

dotnet watch variáveis de ambiente

Para obter informações sobre dotnet watch configurações disponíveis como variáveis de ambiente, consulte Variáveis de ambiente de observação dotnet.

Consulte também