.NET runtime environment variables¶

DOTNET_SYSTEM_NET_HTTP_*¶

There are several global HTTP environment variable settings:

•

DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION

•

DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT

•

DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT

•

DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING

•

DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE

•

DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER

DOTNET_SYSTEM_GLOBALIZATION_*¶

•

DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: See set invariant mode.

•

DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY: Specifies whether to load only predefined cultures.

•

DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU: Indicates whether to use the app-local International Components of Unicode (ICU). For more information, see App-local ICU.

Set invariant mode¶

Applications can enable the invariant mode in any of the following ways:

1.

In the project file:

2.

In the runtimeconfig.json file:

3.

By setting environment variable value DOTNET_SYSTEM_GLOBALIZATION_INVARIANT to true or 1.

For more information, see .NET Globalization Invariant Mode (https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md).

DOTNET_SYSTEM_GLOBALIZATION_USENLS¶

This applies to Windows only. For globalization to use National Language Support (NLS), set DOTNET_SYSTEM_GLOBALIZATION_USENLS to either true or 1. To not use it, set DOTNET_SYSTEM_GLOBALIZATION_USENLS to either false or 0.

DOTNET_SYSTEM_NET_SOCKETS_*¶

This section focuses on two System.Net.Sockets environment variables:

•

DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS

•

DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT

Socket continuations are dispatched to the <xref:System.Threading.ThreadPool?displayProperty=fullName> from the event thread. This avoids continuations blocking the event handling. To allow continuations to run directly on the event thread, set DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS to 1. It’s disabled by default.

Using TechEmpower benchmarks that generate a lot of small socket reads and writes under a very high load, a single socket engine is capable of keeping busy up to thirty x64 and eight Arm64 CPU cores. The vast majority of real-life scenarios will never generate such a huge load (hundreds of thousands of requests per second), and having a single producer is almost always enough. However, to be sure that extreme loads can be handled, you can use DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT to override the calculated value. When not overridden, the following value is used:

•

When DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS is 1, the <xref:System.Environment.ProcessorCount?displayProperty=nameWithType> value is used.

•

When DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS is not 1, <xref:System.Runtime.InteropServices.RuntimeInformation.ProcessArchitecture?displayProperty=nameWithType> is evaluated:

•

Using the determined cores per engine, the maximum value of either 1 or <xref:System.Environment.ProcessorCount?displayProperty=nameWithType> over the cores per engine.

DOTNET_SYSTEM_NET_DISABLEIPV6¶

Helps determine whether or not Internet Protocol version 6 (IPv6) is disabled. When set to either true or 1, IPv6 is disabled unless otherwise specified in the <xref:System.AppContext?displayProperty=nameWithType>.

DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER¶

You can use one of the following mechanisms to configure a process to use the older HttpClientHandler:

From code, use the AppContext class:

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

The AppContext switch can also be set by a config file. For more information configuring switches, see AppContext for library consumers.

The same can be achieved via the environment variable DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER. To opt-out, set the value to either false or 0.

DOTNET_Jit* and DOTNET_GC*¶

There are two stressing-related features for the JIT and JIT-generated GC information: JIT Stress and GC Hole Stress. These features provide a way during development to discover edge cases and more “real world” scenarios without having to develop complex applications. The following environment variables are available:

•

DOTNET_JitStress

•

DOTNET_JitStressModeNamesOnly

•

DOTNET_GCStress

JIT stress¶

Enabling JIT Stress can be done in several ways. Set DOTNET_JitStress to a non-zero integer value to generate varying levels of JIT optimizations based on a hash of the method’s name. To apply all optimizations set DOTNET_JitStress=2, for example. Another way to enable JIT Stress is by setting DOTNET_JitStressModeNamesOnly=1 and then requesting the stress modes, space-delimited, in the DOTNET_JitStressModeNames variable.

As an example, consider:

DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
    

GC Hole stress¶

Enabling GC Hole Stress causes GCs to always occur in specific locations and that helps to track down GC holes. GC Hole Stress can be enabled using the DOTNET_GCStress environment variable.

For more information, see Investigating JIT and GC Hole stress (https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/jit/investigate-stress.md).

JIT memory barriers¶

The code generator for Arm64 allows all MemoryBarriers instructions to be removed by setting DOTNET_JitNoMemoryBarriers to 1.

DOTNET_RUNNING_IN_CONTAINER and DOTNET_RUNNING_IN_CONTAINERS¶

The official .NET images (Windows and Linux) set the well-known environment variables:

•

DOTNET_RUNNING_IN_CONTAINER

•

DOTNET_RUNNING_IN_CONTAINERS

These values are used to determine when your ASP.NET Core workloads are running in the context of a container.

DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION¶

When <xref:System.Console.IsOutputRedirected?displayProperty=nameWithType> is true, you can emit ANSI color code by setting DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION to either 1 or true.

DOTNET_SYSTEM_DIAGNOSTICS and related variables¶

•

DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL: When 1 or true, the default Activity Id format is hierarchical.

•

DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: When running as Debug, tracing can be enabled when this is true.

DOTNET_DiagnosticPorts¶

Configures alternate endpoints where diagnostic tools can communicate with the .NET runtime. See the Diagnostic Port documentation for more information.

DOTNET_DefaultDiagnosticPortSuspend¶

Configures the runtime to pause during startup and wait for the Diagnostics IPC ResumeStartup command from the specified diagnostic port when set to 1. Defaults to 0. See the Diagnostic Port documentation for more information.

DOTNET_EnableDiagnostics¶

When set to 1, enables debugging, profiling, and other diagnostics via the Diagnostic Port. Defaults to 1.

EventPipe variables¶

See EventPipe environment variables for more information.

•

DOTNET_EnableEventPipe: When set to 1, enables tracing via EventPipe.

•

DOTNET_EventPipeOutputPath: The output path where the trace will be written.

•

DOTNET_EventPipeOutputStreaming: When set to 1, enables streaming to the output file while the app is running. By default trace information is accumulated in a circular buffer and the contents are written at app shutdown.

.NET SDK and CLI environment variables¶

DOTNET_ROOT, DOTNET_ROOT(x86)¶

Specifies the location of the .NET runtimes, if they are not installed in the default location. The default location on Windows is C:\Program Files\dotnet. The default location on macOS is /usr/local/share/dotnet. The default location on Linux varies depending on distro and installment method. The default location on Ubuntu 22.04 is /usr/share/dotnet (when installed from packages.microsoft.com) or /usr/lib/dotnet (when installed from Jammy feed). For more information, see the following resources:

•

Troubleshoot app launch failures

•

GitHub issue dotnet/core#7699 (https://github.com/dotnet/core/issues/7699)

•

GitHub issue dotnet/runtime#79237 (https://github.com/dotnet/runtime/issues/79237)

This environment variable is used only when running apps via generated executables (apphosts). DOTNET_ROOT(x86) is used instead when running a 32-bit executable on a 64-bit OS.

DOTNET_HOST_PATH¶

Specifies the absolute path to a dotnet host (dotnet.exe on Windows, dotnet on Linux and macOS) that was used to launch the currently-running dotnet process. This is used by the .NET SDK to help tools that run during .NET SDK commands ensure they use the same dotnet runtime for any child dotnet processes they create for the duration of the command. Tools and MSBuild Tasks within the SDK that invoke binaries via the dotnet host are expected to honor this environment variable to ensure a consistent experience.

Tools that invoke dotnet during an SDK command should use the following algorithm to locate it:

•

if DOTNET_HOST_PATH is set, use that value directly

•

otherwise, rely on dotnet via the system’s PATH

NUGET_PACKAGES¶

The global packages folder. If not set, it defaults to ~/.nuget/packages on Unix or %userprofile%\.nuget\packages on Windows.

DOTNET_SERVICING¶

Specifies the location of the servicing index to use by the shared host when loading the runtime.

DOTNET_NOLOGO¶

Specifies whether .NET welcome and telemetry messages are displayed on the first run. Set to true to mute these messages (values true, 1, or yes accepted) or set to false to allow them (values false, 0, or no accepted). If not set, the default is false and the messages will be displayed on the first run. This flag does not affect telemetry (see DOTNET_CLI_TELEMETRY_OPTOUT for opting out of sending telemetry).

DOTNET_CLI_PERF_LOG¶

Specifies whether performance details about the current CLI session are logged. Enabled when set to 1, true, or yes. This is disabled by default.

DOTNET_GENERATE_ASPNET_CERTIFICATE¶

Specifies whether to generate an ASP.NET Core certificate. The default value is true, but this can be overridden by setting this environment variable to either 0, false, or no.

DOTNET_ADD_GLOBAL_TOOLS_TO_PATH¶

Specifies whether to add global tools to the PATH environment variable. The default is true. To not add global tools to the path, set to 0, false, or no.

DOTNET_CLI_TELEMETRY_OPTOUT¶

Specifies whether data about the .NET tools usage is collected and sent to Microsoft. Set to true to opt-out of the telemetry feature (values true, 1, or yes accepted). Otherwise, set to false to opt into the telemetry features (values false, 0, or no accepted). If not set, the default is false and the telemetry feature is active.

DOTNET_SKIP_FIRST_TIME_EXPERIENCE¶

If DOTNET_SKIP_FIRST_TIME_EXPERIENCE is set to true, the NuGetFallbackFolder won’t be expanded to disk and a shorter welcome message and telemetry notice will be shown.

DOTNET_MULTILEVEL_LOOKUP¶

Specifies whether the .NET runtime, shared framework, or SDK are resolved from the global location. If not set, it defaults to 1 (logical true). Set the value to 0 (logical false) to not resolve from the global location and have isolated .NET installations. For more information about multi-level lookup, see Multi-level SharedFX Lookup (https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/multilevel-sharedfx-lookup.md).

DOTNET_ROLL_FORWARD¶

Determines roll forward behavior. For more information, see the --roll-forward option for the dotnet command.

DOTNET_ROLL_FORWARD_TO_PRERELEASE¶

If set to 1 (enabled), enables rolling forward to a pre-release version from a release version. By default (0 - disabled), when a release version of .NET runtime is requested, roll-forward will only consider installed release versions.

For more information, see the --roll-forward option for the dotnet command

DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX¶

Disables minor version roll forward, if set to 0. This setting is superseded in .NET Core 3.0 by DOTNET_ROLL_FORWARD. The new settings should be used instead.

DOTNET_CLI_FORCE_UTF8_ENCODING¶

Forces the use of UTF-8 encoding in the console, even for older versions of Windows 10 that don’t fully support UTF-8. For more information, see SDK no longer changes console encoding when finished.

DOTNET_CLI_UI_LANGUAGE¶

Sets the language of the CLI UI using a locale value such as en-us. The supported values are the same as for Visual Studio. For more information, see the section on changing the installer language in the Visual Studio installation documentation. The .NET resource manager rules apply, so you don’t have to pick an exact match—you can also pick descendants in the CultureInfo tree. For example, if you set it to fr-CA, the CLI will find and use the fr translations. If you set it to a language that is not supported, the CLI falls back to English.

DOTNET_DISABLE_GUI_ERRORS¶

For GUI-enabled generated executables - disables dialog popup, which normally shows for certain classes of errors. It only writes to stderr and exits in those cases.

DOTNET_ADDITIONAL_DEPS¶

Equivalent to CLI option --additional-deps.

DOTNET_RUNTIME_ID¶

Overrides the detected RID.

DOTNET_SHARED_STORE¶

Location of the “shared store” which assembly resolution falls back to in some cases.

DOTNET_STARTUP_HOOKS¶

List of assemblies to load and execute startup hooks from.

DOTNET_BUNDLE_EXTRACT_BASE_DIR¶

Specifies a directory to which a single-file application is extracted before it is executed.

For more information, see Single-file executables.

DOTNET_CLI_CONTEXT_*¶

•

DOTNET_CLI_CONTEXT_VERBOSE: To enable a verbose context, set to true.

•

DOTNET_CLI_CONTEXT_ANSI_PASS_THRU: To enable an ANSI pass-through, set to true.

DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE¶

Disables background download of advertising manifests for workloads. Default is false - not disabled. If set to true, downloading is disabled. For more information, see Advertising manifests.

DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS¶

Specifies the minimum number of hours between background downloads of advertising manifests for workloads. The default is 24, which is no more frequently than once a day. For more information, see Advertising manifests.

DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT¶

Specifies whether .NET SDK local tools search for tool manifest files in the root folder on Windows. The default is false.

COREHOST_TRACE¶

Controls diagnostics tracing from the hosting components, such as dotnet.exe, hostfxr, and hostpolicy.

•

COREHOST_TRACE=[0/1] - default is 0 - tracing disabled. If set to 1, diagnostics tracing is enabled.

•

COREHOST_TRACEFILE=<file path> - has an effect only if tracing is enabled by setting COREHOST_TRACE=1. When set, the tracing information is written to the specified file; otherwise, the trace information is written to stderr.

•

COREHOST_TRACE_VERBOSITY=[1/2/3/4] - default is 4. The setting is used only when tracing is enabled via COREHOST_TRACE=1.

The typical way to get detailed trace information about application startup is to set COREHOST_TRACE=1 andCOREHOST_TRACEFILE=host_trace.txt and then run the application. A new file host_trace.txt will be created in the current directory with the detailed information.

SuppressNETCoreSdkPreviewMessage¶

If set to true, invoking dotnet won’t produce a warning when a preview SDK is being used.

Configure MSBuild in the .NET CLI¶

To execute MSBuild out-of-process, set the DOTNET_CLI_RUN_MSBUILD_OUTOFPROC environment variable to either 1, true, or yes. By default, MSBuild will execute in-proc. To force MSBuild to use an external working node long-living process for building projects, set DOTNET_CLI_USE_MSBUILDNOINPROCNODE to 1, true, or yes. This will set the MSBUILDNOINPROCNODE environment variable to 1, which is referred to as MSBuild Server V1, as the entry process forwards most of the work to it.

DOTNET_MSBUILD_SDK_RESOLVER_*¶

These are overrides that are used to force the resolved SDK tasks and targets to come from a given base directory and report a given version to MSBuild, which may be null if unknown. One key use case for this is to test SDK tasks and targets without deploying them by using the .NET Core SDK.

•

DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR: Overrides the .NET SDK directory.

•

DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER: Overrides the .NET SDK version.

•

DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: Overrides the dotnet.exe directory path.

DOTNET_NEW_PREFERRED_LANG¶

Configures the default programming language for the dotnet new command when the -lang|--language switch is omitted. The default value is C#. Valid values are C#, F#, or VB. For more information, see dotnet new.