.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 流接收窗口的最大大小不能小于 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

设置固定模式

应用程序可以通过以下任意方式启用固定模式:

  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 基准可在非常高的负载下生成大量的小型套接字读取和写入,这样单个套接字引擎能够保持高忙碌状态,最多可达三十个 x64 和 8 个 Arm64 CPU 内核。 绝大多数真实世界场景永远不会产生如此巨大的负载(每秒数十万个请求),因此一个生产程序大多数情况下就够用了。 但是,若要确保可以处理极端负载,可以使用 DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT 来重写计算的值。 如果未重写,则使用以下值:

DOTNET_SYSTEM_NET_DISABLEIPV6

帮助确定是否禁用了 Internet 协议版本 6 (IPv6)。 当设置为 true1 时,IPv6 被禁用,除非在 System.AppContext 中另有规定。

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 压力和 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_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 时,默认的活动 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 源安装)。 有关详细信息,请参阅以下资源:

此环境变量仅在通过生成的可执行文件 (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

指定加载运行时期间共享主机要使用的服务索引的位置。

指定是否在首次运行时显示 .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

指定是否收集并向 Microsoft 发送 .NET 工具使用情况的相关数据。 设置为 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 编码,即使对于不完全支持 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.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,则调用 dotnet 将不会在使用预览版 SDK 时发出警告。

在 .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 环境变量

另请参阅