.NET 執行階段組態設定

發行項
02/27/2024

.NET 5+ (包括 .NET Core 版本) 支援使用組態檔和環境變數來設定 .NET 應用程式在執行階段的行為。

注意

本節中的文章說明 .NET 執行階段本身的組態。如果您要移轉至 .NET Core 3.1 或更新版本，並尋找 app.config 檔案的取代檔，或只想在 .NET 應用程式中使用自訂組態值，請參閱 Microsoft.Extensions.Configuration.ConfigurationBuilder 類別和 .NET 中的設定。

使用這些設定是一個有吸引力的選項，如果：

您未擁有或無法控制應用程式的原始程式碼，因此無法以程式設計方式進行設定。
應用程式的多個執行個體同時在單一系統上執行，而且您想要設定每個執行個體以獲得最佳效能。

.NET 提供下列機制，讓您可以設定 .NET 執行階段的行為：

runtimeconfig.json 檔案
MSBuild 屬性
環境變數

提示

使用環境變數設定選項會將設定套用至所有 .NET 應用程式。在 runtimeconfig.json 或專案檔中設定選項，只會將設定套用至該應用程式。

某些組態值也可以透過呼叫 AppContext.SetSwitch 方法來以程式設計方式設定。

在本文件中，本節中的文章會依照類別加以組織，例如，偵錯和記憶體回收。在適當情況下，會顯示 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": "netcoreapp3.1",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "3.1.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 屬性設定 .NET 執行階段行為的範例 SDK 樣式專案檔：

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

  <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 環境變數

共用方式為