Paramètres de configuration du runtime .NET

  • Article

.NET 5+ (y compris les versions .NET Core) prend en charge l’utilisation de fichiers de configuration et de variables d’environnement pour configurer le comportement des applications .NET au moment de l’exécution.

Notes

Les articles de cette section concernent la configuration du runtime .NET lui-même. Si vous effectuez une migration vers .NET Core 3.1 ou version ultérieure et que vous recherchez un remplacement pour le fichier app.config, ou si vous souhaitez simplement utiliser des valeurs de configuration personnalisées dans votre application .NET, consultez la classe Microsoft.Extensions.Configuration.ConfigurationBuilder et Configuration dans .NET.

L’utilisation de ces paramètres est une option intéressante si :

  • Vous ne possédez pas ou ne contrôlez pas le code source d’une application et ne pouvez donc pas le configurer par programmation.
  • Plusieurs instances de votre application s’exécutent en même temps sur un même système et vous souhaitez les configurer pour des performances optimales.

.NET fournit les mécanismes suivants pour configurer le comportement du runtime .NET :

Conseil

La configuration d’une option à l’aide d’une variable d’environnement applique le paramètre à toutes les applications .NET. La configuration d’une option dans le fichier runtimeconfig.json ou le fichier projet applique le paramètre à cette application uniquement.

Certaines valeurs de configuration peuvent également être définies par programmation en appelant la méthode AppContext.SetSwitch.

Les articles de cette section de la documentation sont organisés par catégorie, par exemple, débogage et garbage collection. Le cas échéant, les options de configuration s’affichent pour les fichiers runtimeconfig.json, les propriétés MSBuild, les variables d’environnement et, pour référence croisée, les fichiers app.config pour les projets .NET Framework.

runtimeconfig.json

Lorsqu’un projet est généré, un fichier [appname].runtimeconfig.json est généré dans le répertoire de sortie. Si un fichier runtimeconfig.template.json existe dans le même dossier que le fichier projet, toutes les options de configuration qu’il contient sont insérées dans le fichier [appname].runtimeconfig.json. Si vous générez l’application vous-même, placez des options de configuration dans le fichier runtimeconfig.template.json. Si vous exécutez simplement l’application, insérez-les directement dans le fichier [appname].runtimeconfig.json.

Notes

  • Le fichier [appname].runtimeconfig.json sera remplacé lors des builds suivantes.
  • Si le OutputType de votre application n’est pas Exe et que vous souhaitez que les options de configuration soient copiées de runtimeconfig.template.json vers [appname].runtimeconfig.json, vous devez définir explicitement GenerateRuntimeConfigurationFiles sur true dans votre fichier projet. Pour les applications qui nécessitent un fichier runtimeconfig.json, cette propriété est true par défaut.

Spécifiez les options de configuration du runtime dans la section configProperties des fichiers runtimeconfig.json. Cette section se présente sous la forme :

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

Exemple de fichier [appname].runtimeconfig.json

Si vous placez les options dans le fichier JSON de sortie, imbriquez-les sous la propriété 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
    }
  }
}

Exemple de fichier runtimeconfig.template.json

Si vous placez les options dans le fichier JSON du modèle, omettez la propriété runtimeOptions.

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

MSBuild (propriétés)

Certaines options de configuration du runtime peuvent être définies à l’aide des propriétés MSBuild dans le fichier .csproj ou .vbproj des projets .NET Core de style SDK. Les propriétés MSBuild sont prioritaires par rapport aux options définies dans le fichier runtimeconfig.template.json.

Voici un exemple de fichier projet de style SDK avec des propriétés MSBuild pour la configuration du comportement au moment de l’exécution :

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

Les propriétés MSBuild pour la configuration du comportement au moment de l’exécution sont notées dans les articles individuels pour chaque zone, par exemple, garbage collection. Elles sont également répertoriées dans la section Configuration du runtime de la référence des propriétés MSBuild pour les projets de style SDK.

Variables d'environnement

Les variables d’environnement peuvent être utilisées pour fournir des informations de configuration du runtime. La configuration d’une option au moment de l’exécution à l’aide d’une variable d’environnement applique le paramètre à toutes les applications .NET Core. Les boutons de configuration spécifiés en tant que variables d’environnement ont généralement le préfixe DOTNET_.

Notes

.NET 6 se normalise sur le préfixe DOTNET_ au lieu de COMPlus_ pour les variables d’environnement qui configurent le comportement au moment de l’exécution de .NET. Toutefois, le préfixe COMPlus_ continuera à fonctionner. Si vous utilisez une version précédente du runtime .NET, vous devez tout de même utiliser le préfixe COMPlus_.

Vous pouvez définir des variables d’environnement à partir du Panneau de configuration Windows, sur la ligne de commande ou par programmation en appelant la méthode Environment.SetEnvironmentVariable(String, String) sur les systèmes Windows et Unix.

Les exemples suivants montrent comment définir une variable d’environnement sur la ligne de commande :

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Voir aussi