Konfigurationseinstellungen für die .NET-Runtime

  • Artikel

.NET 5 und höher (einschließlich .NET Core-Versionen) unterstützen die Verwendung von Konfigurationsdateien und Umgebungsvariablen, um das Verhalten von .NET-Anwendungen zur Laufzeit zu konfigurieren.

Hinweis

Die Artikel in diesem Abschnitt betreffen die Konfiguration der .NET-Runtime selbst. Wenn Sie zu .NET Core 3.1 oder höher migrieren und nach einem Ersatz für die app.config-Datei suchen, oder Sie einfach eine Möglichkeit zum Verwenden benutzerdefinierter Konfigurationswerte in Ihrer .NET-App suchen, sehen Sie sich die Microsoft.Extensions.Configuration.ConfigurationBuilder-Klasse an, und lesen Sie Konfiguration in .NET.

Die Verwendung dieser Einstellungen ist in folgenden Fällen eine attraktive Option:

  • Sie den Quellcode für eine Anwendung nicht besitzen oder steuern und ihn deshalb nicht programmgesteuert konfigurieren können.
  • mehrere Instanzen Ihrer Anwendung zur gleichen Zeit auf einem einzelnen System ausgeführt werden und Sie jede Instanz für die optimale Leistung konfigurieren möchten.

.NET bietet die folgenden Mechanismen zum Konfigurieren des Verhaltens der .NET-Runtime:

Tipp

Wenn Sie eine Option mithilfe einer Umgebungsvariablen konfigurieren, wird diese Einstellung auf alle .NET-Apps angewendet. Wenn Sie eine Option in der Datei runtimeconfig.json oder in der Projektdatei konfigurieren, wird die Einstellung nur auf diese Anwendung angewendet.

Einige Konfigurationswerte können auch programmgesteuert festgelegt werden, indem die AppContext.SetSwitch-Methode aufgerufen wird.

Die Artikel in diesem Teil der Dokumentation sind nach Kategorie geordnet, z. B. Debuggen und Garbage Collection. Gegebenenfalls werden Konfigurationsoptionen für runtimeconfig.json-Dateien, MSBuild-Eigenschaften, Umgebungsvariablen und, als Querverweis, app.config-Dateien für .NET Framework-Projekte angezeigt.

runtimeconfig.json

Wenn ein Projekt erstellt wird, wird im Ausgabeverzeichnis eine Datei namens [App-Name].runtimeconfig.json generiert. Wenn eine runtimeconfig.template.json-Datei im selben Ordner liegt wie eine Projektdatei, werden alle in ihr enthaltenen Konfigurationsoptionen in die Datei [App-Name].runtimeconfig.json eingefügt. Wenn Sie die App selbst erstellen, legen Sie alle Konfigurationsoptionen in der Datei runtimeconfig.template.json fest. Wenn Sie die App nur ausführen, fügen Sie sie direkt in die Datei [App-Name].runtimeconfig.json ein.

Hinweis

  • Die Datei [App-Name].runtimeconfig.json wird bei nachfolgenden Builds überschrieben.
  • Wenn der OutputType Ihrer App nicht Exe lautet und Sie möchten, dass Konfigurationsoptionen aus runtimeconfig.template.json in [appname].runtimeconfig.json kopiert werden, müssen Sie GenerateRuntimeConfigurationFiles explizit auf true in Ihrer Projektdatei festlegen. Für Apps, die eine runtimeconfig.json-Datei benötigen, wird diese Eigenschaft standardmäßig auf true festgelegt.

Geben Sie die Optionen für die Runtimekonfiguration im Abschnitt configProperties der Datei runtimeconfig.json an. Dieser Abschnitt hat das folgende Format:

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

Beispiel einer „[App-Name].runtimeconfig.jason“-Datei

Wenn Sie die Optionen in der JSON-Ausgabedatei angeben möchten, platzieren Sie sie unter der Eigenschaft 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
    }
  }
}

Beispiel einer „runtimeconfig.template.json“-Datei

Wenn Sie die Optionen in der template.json-Datei platzieren, lassen Sie die Eigenschaft runtimeOptions weg.

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

MSBuild-Eigenschaften

Manche Optionen für die Runtimekonfiguration können mithilfe von MSBuild-Eigenschaften in den Dateien CSPROJ oder VBPROJ von .NET Core-Projekten im SDK-Stil festgelegt werden. MSBuild-Eigenschaften haben Vorrang vor Optionen, die in der Datei runtimeconfig.template.json festgelegt sind.

Hier sehen Sie ein Beispiel für eine Projektdatei im SDK-Stil mit MSBuild-Eigenschaften zum Konfigurieren des Runtimeverhaltens:

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

Die MSBuild-Eigenschaften zum Konfigurieren des Runtimeverhaltens finden Sie in den Artikeln für die einzelnen Bereiche, z. B. Garbage Collection. Sie werden auch im Abschnitt Runtimekonfiguration der Referenz zu MSBuild-Eigenschaften für SDK-Projekte aufgeführt.

Umgebungsvariablen

Umgebungsvariablen können verwendet werden, um einige Informationen zur Runtimekonfiguration bereitzustellen. Wenn Sie eine Laufzeitoption mithilfe einer Umgebungsvariablen konfigurieren, wird diese Einstellung auf alle .NET Core-Apps angewendet. Konfigurationseinstellungen, die als Umgebungsvariablen angegeben werden, verfügen generell über das Präfix DOTNET_ .

Hinweis

In .NET 6 ist das Präfix DOTNET_ statt COMPlus_ Standard für Umgebungsvariablen, die das .NET-Runtimeverhalten konfigurieren. Das Präfix COMPlus_ funktioniert jedoch weiterhin. Wenn Sie eine frühere Version der .NET-Runtime verwenden, sollten Sie weiterhin das Präfix COMPlus_ für Umgebungsvariablen verwenden.

Sie können Umgebungsvariablen über die Windows-Systemsteuerung, die Befehlszeile oder programmgesteuert durch Aufruf der Environment.SetEnvironmentVariable(String, String)-Methode jeweils auf den Windows- und Linux-basierten Systemen definieren.

In den folgenden Beispielen wird dargestellt, wie eine Umgebungsvariable in der Befehlszeile festgelegt wird:

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Weitere Informationen