Definições de configuração do Runtime do .NET

  • Artigo

O .NET 5+ (incluindo versões do .NET Core) oferece suporte ao uso de arquivos de configuração e variáveis de ambiente para configurar o comportamento de aplicativos .NET em tempo de execução.

Observação

Os artigos desta seção dizem respeito à configuração do próprio Runtime do .NET. Se você estiver migrando para o .NET Core 3.1 ou posterior e procurando uma substituição para o arquivo app.config, ou se quiser apenas uma maneira de usar valores de configuração personalizados no seu aplicativo .NET, consulte a classe Microsoft.Extensions.Configuration.ConfigurationBuilder e Configuração no .NET.

Usar essas configurações é uma opção interessante se:

  • Você não é proprietário nem controla o código-fonte de um aplicativo e, portanto, não consegue configurá-lo programaticamente.
  • Várias instâncias do aplicativo são executadas ao mesmo tempo em um único sistema e você quer configurar cada uma delas para obter desempenho ideal.

O .NET fornece os seguintes mecanismos para configurar o comportamento do runtime do .NET:

Dica

A configuração de uma opção usando uma variável de ambiente aplica a definição a todos os aplicativos .NET. A configuração de uma opção no arquivo runtimeconfig.json ou de projeto aplica a definição somente a esse aplicativo.

Alguns valores de configuração também podem ser definidos programaticamente com a chamada do método AppContext.SetSwitch.

Os artigos desta seção da documentação são organizados por categoria; por exemplo, depuração e coleta de lixo. Quando for o caso, as opções de configuração serão mostradas para arquivos runtimeconfig.json, propriedades MSBuild, variáveis de ambiente e, para referência cruzada, arquivos app.config para projetos .NET Framework.

runtimeconfig.json

Quando um projeto é criado, um arquivo [appname].runtimeconfig.json é gerado no diretório de saída. Se existir um arquivo runtimeconfig.template.json na mesma pasta que o arquivo de projeto, todas as opções de configuração que ele contém serão inseridas no arquivo [appname].runtimeconfig.json. Se você estiver criando o aplicativo por conta própria, coloque as opções de configuração no arquivo runtimeconfig.template.json. Se você estiver apenas executando o aplicativo, insira-o diretamente no arquivo [appname].runtimeconfig.json.

Observação

  • O arquivo [appname].runtimeconfig.json será substituído em builds subsequentes.
  • Se o OutputType do aplicativo não for Exe e você quiser que as opções de configuração sejam copiadas de runtimeconfig.template.json para [appname].runtimeconfig.json, defina explicitamente GenerateRuntimeConfigurationFiles como true no seu arquivo de projeto. No caso de aplicativos que exigem um arquivo runtimeconfig.json, o padrão dessa propriedade é true.

Especifique as opções de configuração de runtime na seção configProperties dos arquivos runtimeconfig.json. Esta seção tem o formulário:

"configProperties": {
  "config-property-name1": "config-value1",
  "config-property-name2": "config-value2"
}

Exemplo, arquivo [appname].runtimeconfig.json

Se você estiver colocando as opções no arquivo JSON de saída, aninha-as sob a propriedade runtimeOptions.

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "3.1.0"
    },
    "configProperties": {
      "System.GC.Concurrent": false,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

Exemplo, arquivo runtimeconfig.template.json

Se você estiver colocando as opções no arquivo JSON de modelo, omita a propriedade runtimeOptions.

{
  "configProperties": {
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

propriedades MSBuild

Algumas opções de configuração de runtime podem ser definidas usando as propriedades MSBuild no arquivo .csproj ou .vbproj de projetos .NET Core no estilo SDK. As propriedades MSBuild têm precedência sobre as opções definidas no arquivo runtimeconfig.template.json.

Aqui está um exemplo de arquivo de projeto no estilo SDK com propriedades MSBuild para configuração do comportamento em tempo de execução:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
    <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
    <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
  </PropertyGroup>

</Project>

As propriedades MSBuild para configuração do comportamento em tempo de execução são observadas nos artigos individuais de cada área, por exemplo, coleta de lixo. Eles também estão listados na seção Configuração do runtime da referência de propriedades MSBuild para projetos no estilo SDK.

Variáveis de ambiente

Variáveis de ambiente podem ser usadas para fornecer algumas informações de configuração de runtime. A configuração de uma opção de tempo de execução com o uso de uma variável de ambiente aplica a definição a todos os aplicativos .NET. Em geral, os botões de configuração especificados como variáveis de ambiente têm o prefixo DOTNET_.

Observação

O .NET 6 usa o prefixo DOTNET_ como padrão em vez de COMPlus_ para variáveis de ambiente que configuram o comportamento de tempo de execução do .NET. No entanto, o prefixo COMPlus_ continuará funcionando. Se você estiver usando uma versão anterior do runtime do .NET, ainda deverá usar o prefixo COMPlus_ para variáveis de ambiente.

Você pode definir variáveis de ambiente no Painel de Controle do Windows, na linha de comando ou programaticamente, chamando o método Environment.SetEnvironmentVariable(String, String) em sistemas baseados no Windows e no Unix.

Os exemplos a seguir mostram como definir uma variável de ambiente na linha de comando:

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Confira também