.NET 執行階段組態設定

  • 發行項

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

注意

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

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

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

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

提示

使用環境變數設定選項會將設定套用至所有 .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

另請參閱