.NET 運行時間組態設定

2025-06-17

.NET 提供下列機制來設定 .NET 運行時間的行為：

機制	註釋
runtimeconfig.json 檔案	將設定套用至特定應用程式。如果應用程式的多個實例同時在單一系統上執行，而且您想要設定每個實例以獲得最佳效能，請使用此檔案。
MSBuild 屬性	將設定套用至特定應用程式。 MSBuild 屬性的優先順序高於 runtimeconfig.json中的設定。
環境變數	將設定套用至所有 .NET 應用程式。

您也可以呼叫 AppContext.SetSwitch 方法，以程序設計方式設定某些組態值。

備註

本節中的文章涉及 .NET 運行時間本身的設定。如果您要將應用程式從 .NET Framework 移轉至 .NET，並尋找 app.config 檔案的替代專案，請參閱升級至 .NET 之後現代化。如需將自定義組態值提供給 .NET 應用程式的相關信息，請參閱 .NET 中的組態。

本部分文件中的文章是依類別來組織，例如偵錯和垃圾收集。如果適用，則會顯示針對 runtimeconfig.json 檔案的組態選項、MSBuild 屬性、環境變數，以及作為參照的 .NET Framework 專案 app.config 檔案。

runtimeconfig.json

建置專案時，會在輸出目錄中產生 [appname].runtimeconfig.json 檔案。如果 runtimeconfig.template.json 檔案存在於與項目檔相同的資料夾中，則會將它所包含的任何組態選項插入 [appname].runtimeconfig.json 檔案中。如果您要自行建置應用程式，請將任何組態選項放在 runtimeconfig.template.json 檔案中。如果您只是執行應用程式，請將它們直接插入 [appname].runtimeconfig.json 檔案中。

備註

後續組建上將會覆寫 [appname].runtimeconfig.json 檔案。
如果您的應用程式 OutputType 不是 Exe ，而且您要將組態選項從 runtimeconfig.template.json 複製到 [appname].runtimeconfig.json，則必須在專案檔中明確設定 GenerateRuntimeConfigurationFiles 為 true 。對於需要 runtimeconfig.json 檔案的應用程式，此屬性預設為 true。

在 runtimeconfig.json 或 runtimeconfig.template.json 檔案的 configProperties 區段中指定運行時間組態選項。本節的格式如下：

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

範例 [appname].runtimeconfig.json 檔案

如果您要將選項放在輸出 JSON 檔案中，請將選項巢狀置於屬性底下 runtimeOptions 。

{
  "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
    }
  }
}

範例runtimeconfig.template.json檔案

如果您要將選項放在範本 JSON 檔案中， 請省略runtimeOptions 屬性。

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

MSBuild 屬性

某些運行時間組態選項可以使用 SDK 樣式 .NET 專案的 .csproj 或 .vbproj 檔案中的 MSBuild 屬性來設定。 MSBuild 屬性的優先順序高於 runtimeconfig.template.json 檔案中所設定的選項。

針對沒有特定 MSBuild 屬性的執行階段組態設定，您可以改用 RuntimeHostConfigurationOption MSBuild 項目。使用 runtimeconfig.json 設定名稱作為 Include 屬性的值。

以下是具有 MSBuild 屬性的 SDK 樣式專案檔範例，用於設定 .NET 執行時間的行為：

<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 屬性會在每個區域的個別文章中指出，例如垃圾收集。它們也會列在 SDK 樣式專案的 MSBuild 屬性參考的運行時間組態區段中。

環境變數

環境變數可用來提供一些運行時間組態資訊。指定為環境變數的配置選項通常具有前綴 DOTNET_。

備註

.NET 6 會針對設定 .NET Runtime 行為的環境變數，透過前置詞 DOTNET_ (而非 COMPlus_) 進行標準化。不過，COMPlus_ 前綴會繼續運作。如果使用舊版的 .NET 執行階段，則您仍應對環境變數使用 COMPlus_ 前置詞。

您可以從 Windows 控制面板、命令行，或在 Windows 和 Unix 系統上呼叫 Environment.SetEnvironmentVariable(String, String) 方法，以程式設計方式定義環境變數。

下列範例示範如何在命令行設定環境變數：

# Windows
set DOTNET_GCRetainVM=1

# Powershell
$env:DOTNET_GCRetainVM="1"

# Unix
export DOTNET_GCRetainVM=1

另請參閱

.NET 環境變數

共用方式為