.NET 環境變數
本文適用於: ✔️ .NET Core 3.1 SDK 與更新版本
在本文中,您將了解 .NET 所使用的環境變數。 有些環境變數會由 .NET 執行階段使用,而有些環境變數只會由 .NET SDK 和 .NET CLI 使用。 有些環境變數則會由所有這三個元件使用。
.NET 執行階段環境變數
DOTNET_SYSTEM_NET_HTTP_*
有幾項全域 HTTP 環境變數設定:
DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
- 表示全域 HTTP 設定是否要啟用診斷處理常式的活動傳播。
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
- 設為
false
或0
時會停用 HTTP/2 支援 (預設啟用)。
- 設為
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
- 設為
true
或1
時會啟用 HTTP/3 支援 (預設停用)。
- 設為
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
- 設為
false
或0
時會覆寫預設值,並停用 HTTP/2 動態窗口縮放演算法。
- 設為
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE
- 預設為 16 MB。 覆寫時,HTTP/2 資料流接收窗口的大小上限不得小於 65535。
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER
- 預設為 1.0。 覆寫時,值愈高則窗口愈短,但下載速度較慢。 不得小於 0。
DOTNET_SYSTEM_GLOBALIZATION_*
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
:請參閱設定非變異模式。DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY
:表示是否只載入預先定義的文化特性。DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU
:表示是否要使用應用程式本地的 Unicode (ICU) 國際元件 (ICU)。 如需詳細資訊,請參閱應用程式本地 ICU。
設定非變異模式
應用程式可透過下列任何方式啟用非變異模式:
在專案檔中:
<PropertyGroup> <InvariantGlobalization>true</InvariantGlobalization> </PropertyGroup>
在 runtimeconfig.json 檔案中:
{ "runtimeOptions": { "configProperties": { "System.Globalization.Invariant": true } } }
將環境變數值
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
設為true
或1
。
重要
專案檔或 runtimeconfig.json 中設定的值優先順序高於環境變數。
如需詳細資訊,請參閱 .NET 全球化非變異模式。
DOTNET_SYSTEM_GLOBALIZATION_USENLS
這僅適用於 Windows。 若要使用全球化的國家語言支援 (NLS),請將 DOTNET_SYSTEM_GLOBALIZATION_USENLS
設為 true
或 1
。 若不使用,請將 DOTNET_SYSTEM_GLOBALIZATION_USENLS
設為 false
或 0
。
DOTNET_SYSTEM_NET_SOCKETS_*
本節著重於兩個 System.Net.Sockets
環境變數:
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
事件執行緒的通訊端接續項目會分派至 System.Threading.ThreadPool。 如此可避免接續項目阻擋事件處理。 若要讓接續項目直接在事件執行緒上執行,請將 DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
設為 1
。 此項目預設為停用。
注意
若有高度耗費資源的工作、佔用 IO 執行緒的時間最終超過預期,則此設定可能會讓效能下降。 測試以確定此設定有助於效能。
使用 TechEmpower 基準測試、在極高負載下產生大量小型通訊端的讀取和寫入時,單一通訊端引擎最多可讓 30 個 x64 和 8 個 Arm64 CPU 核心保持運作。 大多數實際案例絕不會產生這類龐大負載 (每秒數百萬個要求),具有單一產生器幾乎隨時都足夠。 不過,若要確定能處理極端負載,您可使用 DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
來覆寫導出值。 未覆寫時,則會使用下列值:
- 當
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
為1
時,則會使用 Environment.ProcessorCount 值。 - 當
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
不是1
時,則會評估 RuntimeInformation.ProcessArchitecture:- 若為 Arm 或 Arm64,各引擎核心值會設為
8
,否則為30
。
- 若為 Arm 或 Arm64,各引擎核心值會設為
- 使用所判斷的各引擎核心時,各引擎的核心上限值為
1
或 Environment.ProcessorCount。
DOTNET_SYSTEM_NET_DISABLEIPV6
協助判斷是否已停用網際網路通訊協定第 6 版 (IPv6)。 設為 true
或 1
時,除非在 System.AppContext 中另行指定,否則會停用 IPv6。
DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER
您可使用下列其中一種機制,以設定處理序使用較舊的 HttpClientHandler
:
使用程式碼中的 AppContext
類別:
AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
AppContext
參數也可由組態檔設定。 如需設定參數的詳細資訊,請參閱程式庫取用者的 AppContext。
這可透過環境變數 DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER
來達成。 若要選擇不使用,請將值設為 false
或 0
。
注意
從 .NET 5 開始,不再提供使用 HttpClientHandler 的這項設定。
DOTNET_Jit*
和 DOTNET_GC*
JIT 及 JIT 產生的 GC 資訊有兩項加強壓力的相關功能:JIT Stress和 GC Hole Stress。 這些功能提供了一種方式,可供開發期間探索邊緣案例和更為「實際」的案例,而無須開發複雜的應用程式。 下列環境變數可供使用:
DOTNET_JitStress
DOTNET_JitStressModeNamesOnly
DOTNET_GCStress
JIT Stress
您可透過幾種方式來使用 JIT Stress。 將 DOTNET_JitStress
設為非零整數值,根據方法名稱的雜湊產生不同層級的 JIT 最佳化。 例如若要套用所有最佳化,則設定 DOTNET_JitStress=2
。 另一項加強 JIT 壓力的方法則是設定 DOTNET_JitStressModeNamesOnly=1
,且在 DOTNET_JitStressModeNames
變數中要求壓力模式,並以空格分隔。
例如,請考慮:
DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
GC Hole stress
啟用 GC Hole Stress 可讓 GC 一律發生在特定位置,且有助於追蹤 GC 空洞。 GC Hole Stress 可透過使用 DOTNET_GCStress
環境變數來啟用。
如需詳細資訊,請參閱深入了解 JIT 和 GC Hole Stress。
JIT 記憶體屏障
Arm64 的程式碼產生器允許移除所有 MemoryBarriers
指示,方法為將 DOTNET_JitNoMemoryBarriers
設為 1
。
DOTNET_RUNNING_IN_CONTAINER
和 DOTNET_RUNNING_IN_CONTAINERS
官方 .NET 映像 (Windows 和 Linux) 會設定已知的環境變數:
DOTNET_RUNNING_IN_CONTAINER
DOTNET_RUNNING_IN_CONTAINERS
這些值可用於判斷在容器情境下 ASP.NET Core 工作負載的執行時機。
DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION
當 Console.IsOutputRedirected 為 true
時,您可將 DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION
設為 1
或 true
,以發送 ANSI 色彩代碼。
DOTNET_SYSTEM_DIAGNOSTICS
和相關變數
DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL
:若為1
或true
,預設的活動識別碼格式為階層式。DOTNET_SYSTEM_RUNTIME_CACHING_TRACING
:以偵錯模式執行時,若此值為true
則可啟用追蹤。
DOTNET_DiagnosticPorts
設定替代端點,以便診斷工具與 .NET 在執行階段通訊。 如需詳細資訊,請參閱診斷連接埠文件。
DOTNET_DefaultDiagnosticPortSuspend
設定執行階段在啟動期間暫停;且在設為 1 時,等候來自指定診斷連接埠的 Diagnostics IPC ResumeStartup 命令。 預設為 0。 如需詳細資訊,請參閱診斷連接埠文件。
DOTNET_EnableDiagnostics
當設定為 0
時,會透過診斷埠來停用偵錯、分析和其他診斷,而且無法被其他診斷設定覆蓋。 預設為 1
。
DOTNET_EnableDiagnostics_IPC
從 .NET 8 開始,當設定為 0
時,會停用診斷埠,而且無法被其他診斷設定覆蓋。 預設為 1
。
DOTNET_EnableDiagnostics_Debugger
從 .NET 8 開始,當設定為 0
時,會停用偵錯,而且無法被其他診斷設定覆蓋。 預設為 1
。
DOTNET_EnableDiagnostics_Profiler
從 .NET 8 開始,當設定為 0
時,會停用分析,而且無法被其他診斷設定覆蓋。 預設為 1
。
EventPipe 變數
如需詳細資訊,請參閱 EventPipe 環境變數。
DOTNET_EnableEventPipe
:設為1
時,可透過 EventPipe 啟用追蹤。DOTNET_EventPipeOutputPath
:該追蹤要寫入的輸出路徑。DOTNET_EventPipeOutputStreaming
:設為1
時,應用程式執行時會啟用串流至輸出檔案。 依預設,系統會將追蹤資訊累積於緩衝區,並於應用程式關機時寫入內容。
.NET SDK 和 CLI 環境變數
DOTNET_ROOT
、 、 DOTNET_ROOT(x86)
、 DOTNET_ROOT_X86
DOTNET_ROOT_X64
指定 .NET 執行階段的位置 (如果它們不會安裝在預設位置的話)。 Windows 上的預設位置為 C:\Program Files\dotnet
。 macOS 上的預設位置為 /usr/local/share/dotnet
。 arm64 OS 上 x64 運行時間的預設位置位於 x64 子資料夾下(例如 C:\Program Files\dotnet\x64
windows 和 /usr/local/share/dotnet/x64
macOS 上。 Linux 上的預設位置視散發版本和安裝方法而定。 Ubuntu 22.04 上的預設位置為 /usr/share/dotnet
(從 packages.microsoft.com
安裝時),或 /usr/lib/dotnet
(從 Jammy 摘要安裝時)。 如需詳細資訊,請參閱以下資源:
- 應用程式啟動失敗的疑難排解
- GitHub 問題 dotnet/core#7699
- GitHub 問題 dotnet/runtime#79237
只有在透過產生的可執行檔 (apphosts) 執行應用程式時,才會使用此環境變數。 在 64 位元作業系統上執行 32 位元的可執行檔時,則會改用 DOTNET_ROOT(x86)
。 DOTNET_ROOT_X64
在 ARM64 OS 上執行 64 位可執行檔案時,會改用 。
DOTNET_HOST_PATH
指定用來啟動目前執行中的 dotnet
處理序的 dotnet
主機 (Windows 上的 dotnet.exe
、Linux 和 macOS 上的 dotnet
) 的絕對路徑。 .NET SDK 會使用此項來協助在 .NET SDK 命令期間所執行的工具,以確保它們對在命令執行期間所建立的任何子 dotnet
處理序使用相同的 dotnet
執行階段。 SDK 中可透過 dotnet
主機叫用二進位檔的工具和 MSBuild 工作,應遵循此環境變數以確保一致的體驗。
在 SDK 命令執行期間叫用 dotnet
的工具應使用下列演算法來找到它:
- 如果設定了
DOTNET_HOST_PATH
,則應直接使用該值 - 否則,應透過系統的
PATH
來找到dotnet
注意
DOTNET_HOST_PATH
不是找到 dotnet
主機的一般解決方案。 它僅供 .NET SDK 叫用的工具所使用。
DOTNET_LAUNCH_PROFILE
dotnet run 命令會將此變數設定到所選的啟動設定檔。
假定有下列的 launchSettings.json 檔:
{
"profiles": {
"First": {
"commandName": "Project",
},
"Second": {
"commandName": "Project",
}
}
}
以及下列的 Program.cs 檔:
var value = Environment.GetEnvironmentVariable("DOTNET_LAUNCH_PROFILE");
Console.WriteLine($"DOTNET_LAUNCH_PROFILE={value}");
以下場景產生了所顯示的輸出:
指定了啟動設定檔,並且存在
$ dotnet run --launch-profile First DOTNET_LAUNCH_PROFILE=First
未指定啟動設定檔,選取了第一個
$ dotnet run DOTNET_LAUNCH_PROFILE=First
指定了啟動設定檔,但不存在
$ dotnet run --launch-profile Third The launch profile "Third" could not be applied. A launch profile with the name 'Third' doesn't exist. DOTNET_LAUNCH_PROFILE=
不含設定檔來啟動
$ dotnet run --no-launch-profile DOTNET_LAUNCH_PROFILE=
NUGET_PACKAGES
全域套件資料夾。 如果未設定,預設為 ~/.nuget/packages
(Unix) 或 %userprofile%\.nuget\packages
(Windows)。
DOTNET_SERVICING
指定載入執行階段時,共用主機所使用的服務索引位置。
DOTNET_NOLOGO
指定第一次執行時是否要顯示 .NET 歡迎和遙測訊息。 設為 true
讓這些訊息靜音 (接受值 true
、1
或 yes
) 或設為 false
以允許這些訊息 (接受值 false
、0
或 no
)。 若未設定,則預設值為 false
,且會在第一次執行時顯示訊息。 此旗標不會影響遙測 (若要選擇不傳送遙測,請參閱 DOTNET_CLI_TELEMETRY_OPTOUT
)。
DOTNET_CLI_PERF_LOG
指定是否要記錄目前 CLI 工作階段的效能詳細資料。 設為 1
、true
或 yes
時啟用。 此選項預設為停用狀態。
DOTNET_GENERATE_ASPNET_CERTIFICATE
指定是否要產生 ASP.NET Core 憑證。 預設值為 true
,但您可將此環境變數設為 0
、false
或 no
以覆寫該值。
DOTNET_ADD_GLOBAL_TOOLS_TO_PATH
指定是否要將全域工具新增至 PATH
環境變數。 預設值為 true
。 若不要將全域工具新增至路徑,則設為 0
、false
或 no
。
DOTNET_CLI_TELEMETRY_OPTOUT
指定是否要收集 .NET 工具使用的相關資料,並傳送給 Microsoft。 設為 true
以選擇加入遙測功能 (可接受的值為 true
、1
或 yes
)。 否則,請將 設定 false
為 ,以選擇加入遙測功能(值 false
、 0
或 no
已接受)。 如果未設定,預設值為 false
,且遙測功能會處於作用狀態。
DOTNET_SKIP_FIRST_TIME_EXPERIENCE
若 DOTNET_SKIP_FIRST_TIME_EXPERIENCE
設為 true
,NuGetFallbackFolder
將不會擴展至磁碟,且會顯示簡短的歡迎訊息和遙測通知。
注意
.NET Core 3.0 和更新版本中不再支援此環境變數。
會使用 DOTNET_NOLOGO
作為取代。
DOTNET_MULTILEVEL_LOOKUP
指定是否從全域位置解析 .NET 執行階段、共用架構或 SDK。 若未設定,則預設為 1 (邏輯 true
)。 將值設為 0 (邏輯 false
),不由全域位置解析,且具有隔離的 .NET 安裝。 如需多層級查閱的詳細資訊,請參閱 Multi-level SharedFX Lookup (多層級 SharedFX 查閱)。
注意
此環境變數僅適用於 .NET 6 及以前版本的應用程式。 從 .NET 7 開始,.NET 只會在一個位置尋找架構。 如需詳細資訊,請參閱已停用多層級查閱。
DOTNET_ROLL_FORWARD
決定向前復原的行為。 如需詳細資訊,請參閱 dotnet
命令的 --roll-forward
選項。
DOTNET_ROLL_FORWARD_TO_PRERELEASE
若設為 1
(啟用),則會從發行版本向前復原至發行前版本。 依預設 (0
- 停用),要求 .NET 執行階段的發行版本時,向前復原只會考慮已安裝的發行版本。
如需詳細資訊,請參閱 dotnet
命令的 --roll-forward
選項
DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX
如果設定為 0
,將停用次要版本向前復原。 在 .NET Core 3.0 中,DOTNET_ROLL_FORWARD
已取代此設定。 應改用這些新設定。
DOTNET_CLI_FORCE_UTF8_ENCODING
在主控台中強制使用 UTF-8 編碼,即使舊版 Windows 10 不支援 UTF-8。 如需詳細資訊,請參閱 SDK 在完成時不再變更控制台編碼。
DOTNET_CLI_UI_LANGUAGE
使用地區設定值來設定 CLI UI 的語言,例如 en-us
。 支援的值與 Visual Studio 相同。 如需詳細資訊,請參閱 Visual Studio 安裝文件中的「變更安裝程式語言」一節。 會套用 .NET 資源管理員規則,因此您不必選擇完全相符的項目 — 您也可以選擇 CultureInfo
樹狀結構中的子系。 例如若設為 fr-CA
,CLI 會尋找並使用 fr
翻譯。 若設為不支援的語言,CLI 會回復為英文。
DOTNET_DISABLE_GUI_ERRORS
若為啟用 GUI 的已產生可執行檔,則會停用快顯對話,該對話通常會針對特定錯誤類別顯示。 只有在這些情況下才會寫入 stderr
並結束。
DOTNET_ADDITIONAL_DEPS
相當於 CLI 選項 --additional-deps
。
DOTNET_RUNTIME_ID
覆寫偵測到的 RID。
DOTNET_SHARED_STORE
「共用存放區」位置,在某些情況下組件解析會回復至此處。
DOTNET_STARTUP_HOOKS
要載入和執行啟動攔截的組件清單。
DOTNET_BUNDLE_EXTRACT_BASE_DIR
指定目錄,先將單一檔案應用程式擷取至其中再執行。
如需詳細資訊,請參閱單一檔案可執行檔。
DOTNET_CLI_HOME
指定應該寫入 .NET CLI 命令支援檔案的位置。 例如:
- 工作負載套件、指令清單和其他支持數據的用戶可寫入路徑。
- .NET CLI 第一次執行移轉和通知體驗的各個層面,第一次執行 sentinel/lock 檔案。
- 預設的 .NET 本機工具安裝位置。
DOTNET_CLI_CONTEXT_*
DOTNET_CLI_CONTEXT_VERBOSE
:若要啟用詳細資訊內容,請設為true
。DOTNET_CLI_CONTEXT_ANSI_PASS_THRU
:若要啟用 ANSI 傳遞,請設為true
。
DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE
停用於背景下載工作負載的廣告資訊清單。 預設值為 false
- 未停用。 若設為 true
,則會停用下載。 如需詳細資訊,請參閱廣告資訊清單。
DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS
指定工作負載的廣告資訊清單在背景下載的間隔時數下限。 預設值為 24
,頻率不超過每天一次。 如需詳細資訊,請參閱公告資訊清單。
DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT
指定 .NET SDK 本機工具是否在 Windows 上的根資料夾中搜尋工具資訊清單檔。 預設值為 false
。
COREHOST_TRACE
控制主控元件的診斷追蹤,例如 dotnet.exe
、hostfxr
和 hostpolicy
。
COREHOST_TRACE=[0/1]
- 預設值為0
- 已停用追蹤。 若設為1
,則會啟用診斷追蹤。COREHOST_TRACEFILE=<file path>
- 僅在設定COREHOST_TRACE=1
啟用追蹤時才會生效。 設定時,追蹤資訊會寫入指定檔案;否則,追蹤資訊會寫入stderr
。COREHOST_TRACE_VERBOSITY=[1/2/3/4]
- 預設值為4
。 該設定僅在透過COREHOST_TRACE=1
啟用追蹤時才會生效。4
- 寫入所有追蹤資訊3
- 只寫入資訊、警告和錯誤訊息2
- 只寫入警告和錯誤訊息1
- 只寫入錯誤訊息
若要取得應用程式啟動詳細追蹤資訊,一般作法為設定 COREHOST_TRACE=1
和 COREHOST_TRACEFILE=host_trace.txt
,接著執行應用程式。 系統會在目前目錄中建立新檔案 host_trace.txt
,並包含詳細資訊。
SuppressNETCoreSdkPreviewMessage
若設為 true
,在使用預覽 SDK 時叫用 dotnet
便不會產生警告。
在 .NET CLI 中設定 MSBuild
若要跨處理序執行 MSBuild,請將 DOTNET_CLI_RUN_MSBUILD_OUTOFPROC
環境變數設為 1
、true
或 yes
。 依預設,MSBuild 會在同處理序執行。 若要讓 MSBuild 在建置專案時強制使用外部工作節點、長時間運作的處理序,則將 DOTNET_CLI_USE_MSBUILDNOINPROCNODE
設為 1
、true
或 yes
。 如此會將 MSBUILDNOINPROCNODE
環境變數設為 1
,亦稱為 MSBuild Server V1,因為輸入處理序會將大多數工作轉送至此。
DOTNET_MSBUILD_SDK_RESOLVER_*
這些為覆寫內容,用於強制讓解析的 SDK 工作和目標來自指定的基底目錄,並將指定版本回報給 MSBuild;若為未知,則可能為 null
。 其中一個主要使用案例即是測試 SDK 工作和目標,而無須使用 .NET Core SDK 進行部署。
DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR
:覆寫 .NET SDK 目錄。DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER
:覆寫 .NET SDK 版本。DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR
:覆寫 dotnet.exe 目錄路徑。
DOTNET_NEW_PREFERRED_LANG
在省略 -lang|--language
參數時,設定 dotnet new
命令的預設程式設計語言。 預設值是 C#
。 有效值為 C#
、F#
或 VB
。 如需詳細資訊,請參閱 dotnet new。
dotnet watch
環境變數
如需可作用環境變數的 dotnet watch
設定相關資訊,請參閱 dotnet watch 環境變數。