.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 流接收窗口的最大大小不能小于 65,535。
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。
设置固定模式
应用程序可以通过以下任意方式启用固定模式:
在项目文件中:
<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 基准可在非常高的负载下生成大量的小型套接字读取和写入,这样单个套接字引擎能够保持高忙碌状态,最多可达三十个 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
帮助确定是否禁用了 Internet 协议版本 6 (IPv6)。 当设置为 true
或 1
时,IPv6 被禁用,除非在 System.AppContext 中另有规定。
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 压力和 GC 缺口压力。 这些功能提供了一种在开发过程中发现边缘案例和更多“真实世界”场景的方法,且无需开发复杂的应用程序。 有以下可用的环境变量:
DOTNET_JitStress
DOTNET_JitStressModeNamesOnly
DOTNET_GCStress
JIT 压力
可以通过多种方式启用 JIT 压力。 将 DOTNET_JitStress
设置为一个非零整数值,根据该方法的名称哈希生成不同级别的 JIT 优化。 例如,若要应用所有优化,则设置 DOTNET_JitStress=2
。 启用 JIT 压力的另一种方法是设置 DOTNET_JitStressModeNamesOnly=1
,然后在 DOTNET_JitStressModeNames
变量中请求压力模式,并以空格分隔。
作为示例,可考虑:
DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
GC 缺口压力
启用 GC 缺口压力会使 GC 始终在特定位置发生,并有助于跟踪 GC 缺口。 可以使用 DOTNET_GCStress
环境变量来启用 GC 缺口压力。
有关详细信息,请参阅调查 JIT 压力和 GC 缺口压力。
JIT 内存障碍
Arm64 的代码生成器允许通过将 DOTNET_JitNoMemoryBarriers
设置为 1
来删除所有 MemoryBarriers
指令。
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
时,默认的活动 Id 格式是分层格式。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 位 OS 上运行 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
全局包文件夹。 如果未设置,则默认为 Unix 上的 ~/.nuget/packages
或 Windows 上的 %userprofile%\.nuget\packages
。
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
指定是否收集并向 Microsoft 发送 .NET 工具使用情况的相关数据。 设置为 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 编码,即使对于不完全支持 UTF-8 的较旧版本的 Windows 10 也是如此。 有关详细信息,请参阅 SDK 在完成后不再更改控制台编码。
DOTNET_CLI_UI_LANGUAGE
使用区域设置值(如 en-us
)设置 CLI UI 的语言。 支持的值与 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
,则调用 dotnet
将不会在使用预览版 SDK 时发出警告。
在 .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 环境变量。