Opciones de configuración de entornos de ejecución de .NET

  • Artículo

A partir de .NET 5 (incluidas las versiones de .NET Core), se admite el uso de archivos de configuración y variables de entorno para configurar el comportamiento de las aplicaciones .NET en tiempo de ejecución.

Nota

Los artículos de esta sección se refieren a la configuración del propio entorno de ejecución de .NET. Si va a migrar a .NET Core 3.1 o una versión posterior y busca un sustituto del archivo app.config, o si solo quiere contar con una manera de usar valores de configuración personalizados en la aplicación de .NET, consulte la clase Microsoft.Extensions.Configuration.ConfigurationBuilder y Configuración en .NET.

El uso de esta configuración es una opción atractiva si:

  • No se posee ni controla el código fuente de una aplicación y, por tanto, no puede configurarlo mediante programación.
  • Varias instancias de la aplicación se ejecutan al mismo tiempo en un solo sistema y se quiere configurar cada una para un rendimiento óptimo.

.NET proporciona los siguientes mecanismos para configurar el comportamiento del entorno de ejecución de .NET:

Sugerencia

El hecho de configurar una opción mediante el uso de una variable de entorno aplica la configuración a todas las aplicaciones de .NET. Sin embargo, si se configura una opción en runtimeconfig.json o en el archivo del proyecto, la configuración solo afectará a la aplicación en cuestión.

Algunos valores de configuración también se pueden establecer mediante programación llamando al método AppContext.SetSwitch.

Los artículos de esta sección de la documentación están organizados por categoría, como, por ejemplo, depuración y recolección de elementos no utilizados. En su caso, se muestran las opciones de configuración para archivos runtimeconfig.json, propiedades de MSBuild, variables de entorno y, para referencias cruzadas, archivos de app.config para proyectos de .NET Framework.

runtimeconfig.json

Cuando un proyecto se compila, se genera un archivo [nombre_aplicación].runtimeconfig.json en el directorio de salida. Si un archivo runtimeconfig.template.json existe en la misma carpeta que el archivo de proyecto, las opciones de configuración que contiene se insertan en el archivo [nombre_aplicación].runtimeconfig.json. Si va a compilar la aplicación, coloque las opciones de configuración en el archivo runtimeconfig.template.json. Si solo va a ejecutar la aplicación, insértelas directamente en el archivo [nombre_aplicación].runtimeconfig.json file.

Nota:

  • El archivo [nombre_aplicación].runtimeconfig.json se sobrescribirá en las compilaciones posteriores.
  • Si el valor OutputType de la aplicación no es Exe y quiere que las opciones de configuración se copien de runtimeconfig.template.json en [nombre_de_la_aplicación].runtimeconfig.json, debe establecer explícitamente GenerateRuntimeConfigurationFiles en true en el archivo del proyecto. Para las aplicaciones en las que se necesita un archivo runtimeconfig.json, esta propiedad tiene true como valor predeterminado.

Especifique las opciones de configuración de entornos de ejecución en la sección configProperties de los archivos runtimeconfig.json. Esta sección tiene el formato siguiente:

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

Archivo de ejemplo [nombre_aplicación].runtimeconfig.json

Si va a colocar las opciones en el archivo JSON de salida, anídelas en la propiedad 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
    }
  }
}

Archivo de ejemplo runtimeconfig.template.json

Si va a colocar las opciones en el archivo JSON de plantilla, omita la propiedad runtimeOptions.

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

propiedades de MSBuild

Algunas opciones de configuración de entornos de ejecución se pueden establecer mediante propiedades de MSBuild en el archivo .csproj o .vbproj de proyectos de .NET Core de estilo SDK. Las propiedades de MSBuild tienen prioridad sobre las opciones establecidas en el archivo runtimeconfig.template.json.

Este es un ejemplo de archivo de proyecto de estilo SDK con propiedades de MSBuild para configurar el comportamiento de runtime:

<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>

Las propiedades de MSBuild para configurar el comportamiento de runtime se indican en los artículos individuales de cada área, por ejemplo, la recolección de elementos no utilizados. También se enumeran en la sección sobre la configuración de entornos de ejecución de la referencia de las propiedades de MSBuild para los proyectos de estilo SDK.

Variables de entorno

Las variables de entorno se pueden usar para proporcionar información de configuración de entornos de ejecución. El hecho de configurar una opción relativa al tiempo de ejecución mediante el uso de una variable de entorno aplica la configuración a todas las aplicaciones de .NET Core. Los botones de configuración especificados como variables de entorno generalmente tienen el prefijo DOTNET_ .

Nota:

.NET 6 estandariza en el prefijo DOTNET_ en lugar de en COMPlus_ para las variables de entorno que configuran el comportamiento en tiempo de ejecución de .NET. Sin embargo, el prefijo COMPlus_ seguirá funcionando. Si usa una versión anterior del runtime de .NET, debe seguir usando el prefijo COMPlus_ para las variables de entorno.

Puede definir variables de entorno desde el Panel de control de Windows, en la línea de comandos o mediante programación llamando al método Environment.SetEnvironmentVariable(String, String) en sistemas basados en Windows y Unix.

En los siguientes ejemplos se muestra cómo establecer una variable de entorno en la línea de comandos:

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Consulte también