Definições de configuração de tempo de execução .NET

  • Artigo

.NET 5+ (incluindo versões .NET Core) suporta a utilização de ficheiros de configuração e variáveis ambientais para configurar o comportamento das aplicações .NET no tempo de execução.

Nota

Os artigos nesta secção dizem respeito à configuração do tempo de execução .NET em si. Se estiver a migrar para .NET Core 3.1 ou mais tarde e estiver à procura de uma substituição para o ficheiro app.config , ou se simplesmente quiser uma forma de utilizar valores de configuração personalizados na sua aplicação .NET, consulte a Microsoft.Extensions.Configuration.ConfigurationBuilder classe e configuração em .NET.

A utilização destas definições é uma opção atraente se:

  • Não possui nem controla o código fonte de uma aplicação e, portanto, não é capaz de o configurar programáticamente.
  • Vários casos da sua aplicação são executados ao mesmo tempo num único sistema, e pretende configurar cada uma para um desempenho ideal.

.NET fornece os seguintes mecanismos para configurar o comportamento do tempo de execução .NET:

Dica

Configurar uma opção utilizando uma variável ambiental aplica a definição a todas as aplicações .NET. Configurar uma opção no ficheiro runtimeconfig.json ou projeto aplica a definição apenas a essa aplicação.

Alguns valores de configuração também podem ser definidos programáticamente, chamando o AppContext.SetSwitch método.

Os artigos nesta secção da documentação são organizados por categoria, por exemplo, depuração e recolha de lixo. Quando aplicável, as opções de configuração são mostradas para ficheiros runtimeconfig.json, propriedades MSBuild, variáveis ambientais e, para referências cruzadas, ficheiros deapp.config para projetos .NET Framework.

runtimeconfig.json

Quando um projeto é construído, um ficheiro [appname].runtimeconfig.json é gerado no diretório de saída. Se um ficheiro runtimeconfig.template.json existir na mesma pasta que o ficheiro do projeto, quaisquer opções de configuração que contenha são inseridas no ficheiro [appname].runtimeconfig.json . Se você mesmo estiver construindo a aplicação, coloque quaisquer opções de configuração no ficheiro runtimeconfig.template.json . Se estiver apenas a executar a aplicação, insira-a diretamente no ficheiro [appname].runtimeconfig.json .

Nota

  • O ficheiro [appname].runtimeconfig.json será substituído em construções posteriores.
  • Se a sua aplicação OutputType não for e pretender que as opções de configuração sejam copiadas de runtimeconfig.template.json para [appname].runtimeconfig.json, deve definir GenerateRuntimeConfigurationFilestrue explicitamente no seu ficheiro do projeto.Exe Para aplicações que requerem um ficheiro runtimeconfig.json , esta propriedade não tem padrão para true.

Especifique as opções de configuração de tempo de execução na secção configProperties dos ficheiros runtimeconfig.json . Esta secção tem o formulário:

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

Exemplo [appname].runtimeconfig.json file

Se estiver a colocar as opções no ficheiro JSON de saída, aninho-as debaixo da runtimeOptions propriedade.

{
  "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 runtimeconfig.template.json

Se estiver a colocar as opções no ficheiro JSON do modelo, omita a runtimeOptions propriedade.

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

Propriedades MSBuild

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

Aqui está um arquivo de projeto de estilo SDK com propriedades MSBuild para configurar o 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 configurar o comportamento em tempo de execução são notadas nos artigos individuais para cada área, por exemplo, a recolha de lixo. Também estão listados na secção de configuração de tempo de execução da referência de propriedades MSBuild para projetos de estilo SDK.

Variáveis de ambiente

As variáveis ambientais podem ser usadas para fornecer algumas informações de configuração de tempo de execução. Configurar uma opção de tempo de execução utilizando uma variável ambiental aplica a definição a todas as aplicações .NET Core. Os botões de configuração especificados como variáveis ambientais geralmente têm o prefixo DOTNET_.

Nota

.NET 6 normaliza no prefixo DOTNET_ em vez de COMPlus_ para variáveis ambientais que configuram o comportamento do tempo de execução .NET. No entanto, o COMPlus_ prefixo continuará a funcionar. Se estiver a utilizar uma versão anterior do tempo de execução .NET, deve ainda utilizar o COMPlus_ prefixo para variáveis ambientais.

Pode definir variáveis ambientais a partir do Windows Painel de Controlo, na linha de comando, ou programáticamente, chamando o Environment.SetEnvironmentVariable(String, String) método em sistemas Windows e baseados em Unix.

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

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Ver também