適用於執行緒的執行階段組態選項

此文章詳細說明可用來在 .NET 中配置執行緒的設定。

注意

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

在 Windows 上使用所有 CPU 群組

• 在具有多個 CPU 群組的電腦上，此設定會配置執行緒集區等元件是否會使用所有 CPU 群組，或只使用流程的主要 CPU 群組。 此設定也會影響 Environment.ProcessorCount 傳回的內容。
• 啟用此設定時，預設會使用所有 CPU 群組，而且執行緒也會自動分散到不同的 CPU 群組。
• Windows 11 和更新版本預設會啟用此設定，Windows 10 和更舊版本預設會停用此設定。 若要讓此設定在啟用時生效，GC 也必須配置為使用所有 CPU 群組；如需詳細資訊，請參閱 GC CPU 群組。

	設定名稱	值
runtimeconfig.json	N/A	N/A
環境變數	COMPlus_Thread_UseAllCpuGroups 或 DOTNET_Thread_UseAllCpuGroups	0 - 已停用 1 - 已啟用

將執行緒指派給 Windows 上的 CPU 群組

• 在具有多個 CPU 群組並使用所有 CPU 群組的電腦上，此設定會配置執行緒是否自動分散到不同的 CPU 群組。
• 啟用此設定時，會將新的執行緒指派給 CPU 群組，以嘗試完整填入已在使用中的 CPU 群組，再使用新的 CPU 群組。
• 此設定預設為啟用狀態。

	設定名稱	值
runtimeconfig.json	N/A	N/A
環境變數	COMPlus_Thread_AssignCpuGroups 或 DOTNET_Thread_AssignCpuGroups	0 - 已停用 1 - 已啟用

執行緒數目下限

• 指定背景工作執行緒集區的執行緒數目下限。
• 對應至 ThreadPool.SetMinThreads 方法。

	設定名稱	值
runtimeconfig.json	System.Threading.ThreadPool.MinThreads	代表執行緒數目下限的整數
MSBuild 屬性	ThreadPoolMinThreads	代表執行緒數目下限的整數
環境變數	N/A	N/A

範例

runtimeconfig.json 檔案：

{
   "runtimeOptions": {
      "configProperties": {
         "System.Threading.ThreadPool.MinThreads": 4
      }
   }
}

runtimeconfig.template.json 檔案：

{
   "configProperties": {
      "System.Threading.ThreadPool.MinThreads": 4
   }
}

專案檔：

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

  <PropertyGroup>
    <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
  </PropertyGroup>

</Project>

執行緒數目上限

• 指定背景工作執行緒集區的執行緒數目上限。
• 對應至 ThreadPool.SetMaxThreads 方法。

	設定名稱	值
runtimeconfig.json	System.Threading.ThreadPool.MaxThreads	代表執行緒數目上限的整數
MSBuild 屬性	ThreadPoolMaxThreads	代表執行緒數目上限的整數
環境變數	N/A	N/A

範例

runtimeconfig.json 檔案：

{
   "runtimeOptions": {
      "configProperties": {
         "System.Threading.ThreadPool.MaxThreads": 20
      }
   }
}

runtimeconfig.template.json 檔案：

{
   "configProperties": {
      "System.Threading.ThreadPool.MaxThreads": 20
   }
}

專案檔：

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

  <PropertyGroup>
    <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
  </PropertyGroup>

</Project>

Windows 執行緒集區

• 針對 Windows 上的專案，配置是否要將執行緒集區的執行緒管理委派給 Windows 執行緒集區。
• 如果您省略此設定，或者平台並非 Windows，則會改用 .NET 執行緒集區。
• 只有 Windows 上以原生 AOT 發佈的應用程式預設會使用 Windows 執行緒集區，您可以藉由停用組態設定來選擇改用 .NET 執行緒集區。
• 在某些情況下，Windows 執行緒集區的效能可能會比較好，例如，當果執行緒的數目下限設定為較高的值，或當應用程式已大量使用 Windows 執行緒集區時。 在有些情境中，.NET 執行緒集區的效能可能也會比較好，例如在大型電腦上處理大量 I/O 時。 建議您在變更此組態設定時，檢查效能計量。
• 使用 Windows 執行緒集區時，不支援某些 API，例如 ThreadPool.SetMinThreads、ThreadPool.SetMaxThreads 與 ThreadPool.BindHandle(SafeHandle)。 最小和最大執行緒的執行緒集區配置設定也並未生效。 ThreadPool.BindHandle(SafeHandle) 的替代方法是類別 ThreadPoolBoundHandle。

	設定名稱	值	導入的版本
runtimeconfig.json	System.Threading.ThreadPool.UseWindowsThreadPool	true - 已啟用 false - 已停用	.NET 8
MSBuild 屬性	UseWindowsThreadPool	true - 已啟用 false - 已停用	.NET 8
環境變數	DOTNET_ThreadPool_UseWindowsThreadPool	1 - 已啟用 0 - 已停用	.NET 8

範例

runtimeconfig.json 檔案：

{
   "runtimeOptions": {
      "configProperties": {
         "System.Threading.ThreadPool.UseWindowsThreadPool": true
      }
   }
}

runtimeconfig.template.json 檔案：

{
   "configProperties": {
      "System.Threading.ThreadPool.UseWindowsThreadPool": true
   }
}

專案檔：

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

  <PropertyGroup>
    <UseWindowsThreadPool>true</UseWindowsThreadPool>
  </PropertyGroup>

</Project>

執行緒插入以回應封鎖工作項目

在某些情況下，執行緒集區會偵測封鎖其執行緒的工作項目。 為了補償，它會插入更多執行緒。 在 .NET 6+ 中，您可以使用下列執行階段組態設定，來配置執行緒插入，以回應封鎖的工作項目。 目前，這些設定只會對等候另一個工作完成的工作項目生效，例如，在一般非同步中的同步案例中。

runtimeconfig.json 設定名稱	描述	導入的版本
System.Threading.ThreadPool.Blocking.ThreadsToAddWithoutDelay_ProcCountFactor	在達到以 MinThreads 為依據的執行緒計數之後，此值 (當其乘以處理器計數之後) 會指定可以在沒有延遲的情況下建立多少個額外的執行緒。	.NET 6
System.Threading.ThreadPool.Blocking.ThreadsPerDelayStep_ProcCountFactor	在達到以 ThreadsToAddWithoutDelay 為依據的執行緒計數之後，此值 (在其乘以處理器計數之後) 會指定要在多少個執行緒之後將額外的 DelayStepMs 執行緒新增至延遲，然後再建立每個新的執行緒。	.NET 6
System.Threading.ThreadPool.Blocking.DelayStepMs	在達到以 ThreadsToAddWithoutDelay 為依據的執行緒計數之後，此值會指定每個 ThreadsPerDelayStep 執行緒要新增多少個額外的延遲，其會在建立每個新執行緒之前套用。	.NET 6
System.Threading.ThreadPool.Blocking.MaxDelayMs	在達到以 ThreadsToAddWithoutDelay 為依據的執行緒計數之後，此值會指定在建立每個新執行緒之前要使用的最大延遲。	.NET 6
System.Threading.ThreadPool.Blocking.IgnoreMemoryUsage	根據預設，執行緒插入以回應封鎖的速率受限於啟發學習法，以判斷是否有足夠的實體記憶體可用。 在某些情況下，最好在記憶體不足的情況下更快速地插入執行緒。 您可以關閉此參數來停用記憶體使用量啟發學習法。	.NET 7

組態設定如何生效

• 在達到以 MinThreads 為依據的執行緒計數之後，最多可在沒有延遲的情況下建立 ThreadsToAddWithoutDelay 個額外的執行緒。
• 之後，在建立每個額外的執行緒之前，會引發延遲，從 DelayStepMs 開始。
• 對於透過延遲新增的每個 ThreadsPerDelayStep 執行緒，會在該延遲中新增額外的 DelayStepMs 執行緒。
• 延遲可能不會超過 MaxDelayMs。
• 只有在建立執行緒之前才會引發延遲。 如果執行緒已可供使用，則會立即將其釋出，以補償封鎖工作項目。
• 同時，也會使用實體記憶體使用量和限制，而且在超過閾值時，系統會切換到速度較慢的執行緒插入。

範例

runtimeconfig.json 檔案：

{
   "runtimeOptions": {
      "configProperties": {
         "System.Threading.ThreadPool.Blocking.ThreadsToAddWithoutDelay_ProcCountFactor": 5
      }
   }
}

runtimeconfig.template.json 檔案：

{
   "configProperties": {
      "System.Threading.ThreadPool.Blocking.ThreadsToAddWithoutDelay_ProcCountFactor": 5
   }
}

適用於受控執行緒的 AutoreleasePool

此選項會設定在支援的 macOS 平台上執行時，每個受控執行緒是否會收到隱含的 NSAutoreleasePool \(英文\)。

	設定名稱	值	導入的版本
runtimeconfig.json	System.Threading.Thread.EnableAutoreleasePool	true 或 false	.NET 6
MSBuild 屬性	AutoreleasePoolSupport	true 或 false	.NET 6
環境變數	N/A	N/A	N/A

範例

runtimeconfig.json 檔案：

{
   "runtimeOptions": {
      "configProperties": {
         "System.Threading.Thread.EnableAutoreleasePool": true
      }
   }
}

runtimeconfig.template.json 檔案：

{
   "configProperties": {
      "System.Threading.Thread.EnableAutoreleasePool": true
   }
}

專案檔：

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

  <PropertyGroup>
    <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
  </PropertyGroup>

</Project>