Freigeben über

.NET-Laufzeitkonfigurationseinstellungen

.NET stellt die folgenden Mechanismen zum Konfigurieren des Verhaltens der .NET-Laufzeit bereit:

Mechanismus Hinweise
Die runtimeconfig.json Datei Wendet die Einstellung auf eine bestimmte App an. Verwenden Sie diese Datei, wenn mehrere Instanzen Ihrer App gleichzeitig auf einem einzigen System ausgeführt werden und Sie die einzelnen Instanzen für eine optimale Leistung konfigurieren möchten.
MSBuild-Eigenschaften Wendet die Einstellung auf eine bestimmte App an. MSBuild-Eigenschaften haben Vorrang vor Einstellungen in runtimeconfig.json.
Umgebungsvariablen Wendet die Einstellung auf alle .NET-Apps an.

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

Hinweis

Die Artikel in diesem Abschnitt betreffen die Konfiguration der .NET-Laufzeit selbst. Wenn Sie eine App von .NET Framework zu .NET migrieren und nach einem Ersatz für die app.config-Datei suchen, lesen Sie "Modernize" nach dem Upgrade auf .NET. Informationen zum Bereitstellen von benutzerdefinierten Konfigurationswerten für .NET-Apps finden Sie unter Configuration in .NET.

Die Artikel in diesem Abschnitt der Dokumentation sind nach Kategorie organisiert, z. B. Debuggen und Garbage Collection. Gegebenenfalls werden Konfigurationsoptionen für runtimeconfig.json Dateien, MSBuild-Eigenschaften, Umgebungsvariablen und für querverweis app.configDateien für .NET Framework-Projekte angezeigt.

runtimeconfig.json

Wenn ein Projekt erstellt wird, wird eine [appname]-.runtimeconfig.json Datei im Ausgabeverzeichnis generiert. Wenn eine runtimeconfig.template.json Datei im selben Ordner wie die Projektdatei vorhanden ist, werden alle darin enthaltenen Konfigurationsoptionen in die Datei [appname].runtimeconfig.json eingefügt. Wenn Sie die App selbst erstellen, platzieren Sie alle Konfigurationsoptionen in der dateiruntimeconfig.template.json . Wenn Sie die App gerade ausführen, fügen Sie sie direkt in die [appname].runtimeconfig.json Datei ein.

Hinweis

  • Die [appname]-.runtimeconfig.json Datei wird bei nachfolgenden Builds überschrieben.
  • Wenn Ihre App nicht OutputTypeExe ist und Sie möchten, dass die 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 erfordern, ist diese Eigenschaft standardmäßig auf true voreingestellt.

Geben Sie laufzeitkonfigurationsoptionen im Abschnitt configProperties der dateiruntimeconfig.json oder runtimeconfig.template.json an. Dieser Abschnitt hat die Form:

"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 platzieren, schachteln Sie sie unter der runtimeOptions Eigenschaft.

{
  "runtimeOptions": {
    "tfm": "net8.0",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "8.0.0"
    },
    "configProperties": {
      "System.Globalization.UseNls": true,
      "System.Net.DisableIPv6": true,
      "System.GC.Concurrent": false,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

Beispieldatei runtimeconfig.template.json

Wenn Sie die Optionen in der JSON-Vorlagendatei platzieren, lassen Sie die runtimeOptions Eigenschaft aus.

{
  "configProperties": {
    "System.Globalization.UseNls": true,
    "System.Net.DisableIPv6": true,
    "System.GC.Concurrent": false,
    "System.Threading.ThreadPool.MinThreads": "4",
    "System.Threading.ThreadPool.MaxThreads": "25"
  }
}

MSBuild-Eigenschaften

Einige Laufzeitkonfigurationsoptionen können mithilfe von MSBuild-Eigenschaften in der .csproj - oder .vbproj-Datei von .NET-Projekten im SDK-Stil festgelegt werden. MSBuild-Eigenschaften haben Vorrang vor optionen, die in der runtimeconfig.template.json Datei festgelegt sind.

Für Laufzeitkonfigurationseinstellungen, die nicht über eine bestimmte MSBuild-Eigenschaft verfügen, können Sie stattdessen das RuntimeHostConfigurationOption MSBuild-Element verwenden. Verwenden Sie den Einstellungsnamen runtimeconfig.json als Wert des Include-Attributs.

Nachfolgend finden Sie ein Beispiel für eine SDK-Projektdatei mit MSBuild-Eigenschaften zum Konfigurieren des Verhaltens der .NET-Laufzeit:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

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

  <ItemGroup>
    <RuntimeHostConfigurationOption Include="System.Globalization.UseNls" Value="true" />
    <RuntimeHostConfigurationOption Include="System.Net.DisableIPv6" Value="true" />
  </ItemGroup>

</Project>

MSBuild-Eigenschaften zum Konfigurieren des Verhaltens der Laufzeit werden in den einzelnen Artikeln für jeden Bereich, z. B. Garbage Collection, aufgeführt. Sie sind auch im Abschnitt zur Laufzeitkonfiguration der MSBuild-Eigenschaftenreferenz für SDK-Stilprojekte aufgeführt.

Umgebungsvariablen

Umgebungsvariablen können verwendet werden, um einige Laufzeitkonfigurationsinformationen bereitzustellen. Konfigurationsknüppeln, die als Umgebungsvariablen angegeben sind, weisen im Allgemeinen das Präfix DOTNET_ auf.

Hinweis

.NET 6 standardisiert das Präfix DOTNET_ anstelle von COMPlus_ für Umgebungsvariablen, die das .NET-Laufzeitverhalten konfigurieren. Das Präfix COMPlus_ funktioniert jedoch weiterhin. Wenn Sie eine frühere Version der .NET-Laufzeit verwenden, sollten Sie weiterhin das präfix COMPlus_ für Umgebungsvariablen verwenden.

Sie können Umgebungsvariablen über die Windows-Systemsteuerung, über die Befehlszeile oder programmgesteuert definieren, indem Sie die Environment.SetEnvironmentVariable(String, String) Methode sowohl auf Windows- als auch auf Unix-basierten Systemen aufrufen.

Die folgenden Beispiele zeigen, wie Sie eine Umgebungsvariable in der Befehlszeile festlegen:

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

Siehe auch