.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
    • 設為 false0 時會停用 HTTP/2 支援 (預設啟用)。
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
    • 設為 true1 時會啟用 HTTP/3 支援 (預設停用)。
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
    • 設為 false0 時會覆寫預設值,並停用 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

設定非變異模式

應用程式可透過下列任何方式啟用非變異模式:

  1. 在專案檔中:

    <PropertyGroup>
        <InvariantGlobalization>true</InvariantGlobalization>
    </PropertyGroup>
    
  2. runtimeconfig.json 檔案中:

    {
        "runtimeOptions": {
            "configProperties": {
                "System.Globalization.Invariant": true
            }
        }
    }
    
  3. 將環境變數值 DOTNET_SYSTEM_GLOBALIZATION_INVARIANT 設為 true1

重要

專案檔或 runtimeconfig.json 中設定的值優先順序高於環境變數。

如需詳細資訊,請參閱 .NET 全球化非變異模式

DOTNET_SYSTEM_GLOBALIZATION_USENLS

這僅適用於 Windows。 若要使用全球化的國家語言支援 (NLS),請將 DOTNET_SYSTEM_GLOBALIZATION_USENLS 設為 true1。 若不使用,請將 DOTNET_SYSTEM_GLOBALIZATION_USENLS 設為 false0

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_DISABLEIPV6

協助判斷是否已停用網際網路通訊協定第 6 版 (IPv6)。 設為 true1 時,除非在 System.AppContext 中另行指定,否則會停用 IPv6。

DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER

您可使用下列其中一種機制,以設定處理序使用較舊的 HttpClientHandler

使用程式碼中的 AppContext 類別:

AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);

AppContext 參數也可由組態檔設定。 如需設定參數的詳細資訊,請參閱程式庫取用者的 AppContext

這可透過環境變數 DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER 來達成。 若要選擇不使用,請將值設為 false0

注意

從 .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_CONTAINERDOTNET_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.IsOutputRedirectedtrue 時,您可將 DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION 設為 1true,以發送 ANSI 色彩代碼。

  • DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL:若為 1true,預設的活動識別碼格式為階層式。
  • 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_ROOTDOTNET_ROOT(x86)

指定 .NET 執行階段的位置 (如果它們不會安裝在預設位置的話)。 Windows 上的預設位置為 C:\Program Files\dotnet。 macOS 上的預設位置為 /usr/local/share/dotnet。 Linux 上的預設位置視散發版本和安裝方法而定。 Ubuntu 22.04 上的預設位置為 /usr/share/dotnet (從 packages.microsoft.com 安裝時),或 /usr/lib/dotnet (從 Jammy 摘要安裝時)。 如需詳細資訊,請參閱以下資源:

只有在透過產生的可執行檔 (apphosts) 執行應用程式時,才會使用此環境變數。 在 64 位元作業系統上執行 32 位元的可執行檔時,則會改用 DOTNET_ROOT(x86)

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

指定載入執行階段時,共用主機所使用的服務索引位置。

指定第一次執行時是否要顯示 .NET 歡迎和遙測訊息。 設為 true 讓這些訊息靜音 (接受值 true1yes ) 或設為 false 以允許這些訊息 (接受值 false0no)。 若未設定,則預設值為 false,且會在第一次執行時顯示訊息。 此旗標不會影響遙測 (若要選擇不傳送遙測,請參閱 DOTNET_CLI_TELEMETRY_OPTOUT)。

DOTNET_CLI_PERF_LOG

指定是否要記錄目前 CLI 工作階段的效能詳細資料。 設為 1trueyes 時啟用。 此選項預設為停用狀態。

DOTNET_GENERATE_ASPNET_CERTIFICATE

指定是否要產生 ASP.NET Core 憑證。 預設值為 true,但您可將此環境變數設為 0falseno 以覆寫該值。

DOTNET_ADD_GLOBAL_TOOLS_TO_PATH

指定是否要將全域工具新增至 PATH 環境變數。 預設值為 true。 若不要將全域工具新增至路徑,則設為 0falseno

DOTNET_CLI_TELEMETRY_OPTOUT

指定是否要收集 .NET 工具使用的相關資料,並傳送給 Microsoft。 設為 true 以選擇加入遙測功能 (可接受的值為 true1yes)。 否則,請設為 false 以選擇退出遙測功能 (可接受的值為 false0no)。 如果未設定,預設值為 false,且遙測功能會處於作用狀態。

DOTNET_SKIP_FIRST_TIME_EXPERIENCE

DOTNET_SKIP_FIRST_TIME_EXPERIENCE 設為 trueNuGetFallbackFolder 將不會擴展至磁碟,且會顯示簡短的歡迎訊息和遙測通知。

注意

.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_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.exehostfxrhostpolicy

  • 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=1COREHOST_TRACEFILE=host_trace.txt,接著執行應用程式。 系統會在目前目錄中建立新檔案 host_trace.txt,並包含詳細資訊。

SuppressNETCoreSdkPreviewMessage

若設為 true,在使用預覽 SDK 時叫用 dotnet 便不會產生警告。

在 .NET CLI 中設定 MSBuild

若要跨處理序執行 MSBuild,請將 DOTNET_CLI_RUN_MSBUILD_OUTOFPROC 環境變數設為 1trueyes。 依預設,MSBuild 會在同處理序執行。 若要讓 MSBuild 在建置專案時強制使用外部工作節點、長時間運作的處理序,則將 DOTNET_CLI_USE_MSBUILDNOINPROCNODE 設為 1trueyes。 如此會將 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 環境變數

另請參閱