Skip to content

Latest commit

 

History

History
433 lines (264 loc) · 23.1 KB

dotnet-environment-variables.md

File metadata and controls

433 lines (264 loc) · 23.1 KB
Raw
title description ms.date
.NET environment variables
Learn about the environment variables that you can use to configure the .NET SDK, .NET CLI, and .NET runtime.
11/08/2023

.NET environment variables

This article applies to: ✔️ .NET Core 3.1 SDK and later versions

In this article, you'll learn about the environment variables used by .NET. Some environment variables are used by the .NET runtime, while others are only used by the .NET SDK and .NET CLI. Some environment variables are used by all three components.

.NET runtime environment variables

DOTNET_SYSTEM_NET_HTTP_*

There are several global HTTP environment variable settings:

  • DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
    • Indicates whether or not to enable activity propagation of the diagnostic handler for global HTTP settings.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
    • When set to false or 0, disables HTTP/2 support, which is enabled by default.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
    • When set to true or 1, enables HTTP/3 support, which is disabled by default.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
    • When set to false or 0, overrides the default and disables the HTTP/2 dynamic window scaling algorithm.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE
    • Defaults to 16 MB. When overridden, the maximum size of the HTTP/2 stream receive window cannot be less than 65,535.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER
    • Defaults to 1.0. When overridden, higher values result in a shorter window but slower downloads. Can't be less than 0.

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:

    <PropertyGroup>
    <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

  2. In the runtimeconfig.json file:

    {
    "runtimeOptions": {
        "configProperties": {
            "System.Globalization.Invariant": true
        }
    }
}

  3. By setting environment variable value DOTNET_SYSTEM_GLOBALIZATION_INVARIANT to true or 1.

Important

A value set in the project file or runtimeconfig.json has a higher priority than the environment variable.

For more information, see .NET Globalization Invariant Mode.

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.

Note

This setting can make performance worse if there is expensive work that will end up holding onto the IO thread for longer than needed. Test to make sure this setting helps performance.

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:
    • When Arm or Arm64 the cores per engine value is set to 8, otherwise 30.
  • 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.

Note

Starting in .NET 5, this setting to use xref:System.Net.Http.HttpClientHandler is no longer available.

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.

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 0, disables debugging, profiling, and other diagnostics via the Diagnostic Port and can't be overridden by other diagnostics settings. Defaults to 1.

DOTNET_EnableDiagnostics_IPC

Starting with .NET 8, when set to 0, disables the Diagnostic Port and can't be overridden by other diagnostics settings. Defaults to 1.

DOTNET_EnableDiagnostics_Debugger

Starting with .NET 8, when set to 0, disables debugging and can't be overridden by other diagnostics settings. Defaults to 1.

DOTNET_EnableDiagnostics_Profiler

Starting with .NET 8, when set to 0, disables profiling and can't be overridden by other diagnostics settings. 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), DOTNET_ROOT_X86, DOTNET_ROOT_X64

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 for the x64 runtimes on an arm64 OS is under an x64 subfolder (so C:\Program Files\dotnet\x64 on windows and /usr/local/share/dotnet/x64 on macOS. 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:

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_ROOT_X64 is used instead when running a 64-bit executable on an ARM64 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

Note

DOTNET_HOST_PATH is not a general solution for locating the dotnet host. It is only intended to be used by tools that are invoked by the .NET SDK.

DOTNET_LAUNCH_PROFILE

The dotnet run command sets this variable to the selected launch profile.

Given the following launchSettings.json file:

{
  "profiles": {
    "First": {
      "commandName": "Project",
    },
    "Second": {
      "commandName": "Project",
    }
  }
}

And the following Program.cs file:

var value = Environment.GetEnvironmentVariable("DOTNET_LAUNCH_PROFILE");
Console.WriteLine($"DOTNET_LAUNCH_PROFILE={value}");

The following scenarios produce the output shown:

  • Launch profile specified and exists

    $ dotnet run --launch-profile First
DOTNET_LAUNCH_PROFILE=First

  • Launch profile not specified, first one selected

    $ dotnet run
DOTNET_LAUNCH_PROFILE=First

  • Launch profile specified but does not exist

    $ 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=

  • Launch with no profile

    $ dotnet run --no-launch-profile
DOTNET_LAUNCH_PROFILE=

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 in to 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.

Note

This environment variable is no longer supported in .NET Core 3.0 and later. Use DOTNET_NOLOGO as a replacement.

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.

Note

This environment variable only applies to applications that target .NET 6 and earlier versions. Starting in .NET 7, .NET only looks for frameworks in one location. For more information, see Multi-level lookup is disabled.

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_HOME

Specifies the location that supporting files for .NET CLI commands should be written to. For example:

  • User-writable paths for workload packs, manifests, and other supporting data.
  • First-run sentinel/lock files for aspects of the .NET CLI's first-run migrations and notification experiences.
  • The default .NET local tool installation location.

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.

    • 4 - all tracing information is written
    • 3 - only informational, warning, and error messages are written
    • 2 - only warning and error messages are written
    • 1 - only error messages are written

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.

dotnet watch environment variables

For information about dotnet watch settings that are available as environment variables, see dotnet watch environment variables.

See also