1dotnet-environment-variables(7).NET Documentationdotnet-environment-variables(7)
2
6 dotnet-environment-variables - .NET environment variables
7
9 This article applies to: ✔️ .NET Core 3.1 SDK and later versions
10 In this article, you’ll learn about the environment variables used by
12 .NET SDK, .NET CLI, and .NET runtime. Some environment variables are
13 used by the .NET runtime, while others are only used by the .NET SDK
14 and .NET CLI. Some environment variables are used by all.
15 .NET runtime environment variables
17 DOTNET_SYSTEM_NET_HTTP_*
18 There are several global HTTP environment variable settings:
19 • DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
21 • Indicates whether or not to enable activity propagation of the di‐
23 agnostic handler for global HTTP settings.
24 • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
26 • When set to false or 0, disables HTTP/2 support, which is enabled
28 by default.
29 • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
31 • When set to true or 1, enables HTTP/3 support, which is disabled by
33 default.
34 • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDY‐
36 NAMICWINDOWSIZING
37 • When set to false or 0, overrides the default and disables the
39 HTTP/2 dynamic window scaling algorithm.
40 • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWIN‐
42 DOWSIZE
43 • Defaults to 16 MB. When overridden, the maximum size of the HTTP/2
45 stream receive window cannot be less than 65,535.
46 • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWS‐
48 CALETHRESHOLDMULTIPLIER
49 • Defaults to 1.0. When overridden, higher values result in a short‐
51 er window but slower downloads. Can’t be less than 0.
52 DOTNET_SYSTEM_GLOBALIZATION_*
54 • DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: See set invariant mode.
55 • DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY: Specifies
57 whether to load only predefined cultures.
58 • DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU: Indicates whether to use the
60 app-local International Components of Unicode (ICU). For more infor‐
61 mation, see App-local ICU.
62 Set invariant mode
64 Applications can enable the invariant mode in any of the following
65 ways:
66 1. In the project file:
68 <PropertyGroup>
70 <InvariantGlobalization>true</InvariantGlobalization>
71 </PropertyGroup>
72 2. In the runtimeconfig.json file:
74 {
76 "runtimeOptions": {
77 "configProperties": {
78 "System.Globalization.Invariant": true
79 }
80 }
81 }
82 3. By setting environment variable value DOTNET_SYSTEM_GLOBALIZA‐
84 TION_INVARIANT to true or 1.
85 A value set in the project file or runtimeconfig.json has a higher
87 priority than the environment variable.
88 For more information, see .NET Globalization Invariant Mode
90 (https://github.com/dotnet/runtime/blob/main/docs/design/features/glob‐
91 alization-invariant-mode.md).
92 DOTNET_SYSTEM_GLOBALIZATION_USENLS
94 This applies to Windows only. For globalization to use National Lan‐
95 guage Support (NLS), set DOTNET_SYSTEM_GLOBALIZATION_USENLS to either
96 true or 1. To not use it, set DOTNET_SYSTEM_GLOBALIZATION_USENLS to
97 either false or 0.
98 DOTNET_SYSTEM_NET_SOCKETS_*
100 This section focuses on two System.Net.Sockets environment variables:
101 • DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
103 • DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
105 Socket continuations are dispatched to the <xref:System.Thread‐
107 ing.ThreadPool?displayProperty=fullName> from the event thread. This
108 avoids continuations blocking the event handling. To allow continua‐
109 tions to run directly on the event thread, set DOTNET_SYSTEM_NET_SOCK‐
110 ETS_INLINE_COMPLETIONS to 1. It’s disabled by default.
111 This setting can make performance worse if there is expensive
113 work that will end up holding onto the IO thread for longer than
114 needed. Test to make sure this setting helps performance.
115 Using TechEmpower benchmarks that generate a lot of small socket reads
117 and writes under a very high load, a single socket engine is capable of
118 keeping busy up to thirty x64 and eight Arm64 CPU cores. The vast ma‐
119 jority of real-life scenarios will never generate such a huge load
120 (hundreds of thousands of requests per second), and having a single
121 producer is almost always enough. However, to be sure that extreme
122 loads can be handled, you can use DOTNET_SYSTEM_NET_SOCK‐
123 ETS_THREAD_COUNT to override the calculated value. When not overrid‐
124 den, the following value is used:
125 • When DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS is 1, the
127 <xref:System.Environment.ProcessorCount?displayProperty=nameWithType>
128 value is used.
129 • When DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS is not 1,
131 <xref:System.Runtime.InteropServices.RuntimeInformation.ProcessArchi‐
132 tecture?displayProperty=nameWithType> is evaluated:
133 • When Arm or Arm64 the cores per engine value is set to 8, otherwise
135 30.
136 • Using the determined cores per engine, the maximum value of either 1
138 or <xref:System.Environment.ProcessorCount?displayProperty=name‐
139 WithType> over the cores per engine.
140 DOTNET_SYSTEM_NET_DISABLEIPV6
142 Helps determine whether or not Internet Protocol version 6 (IPv6) is
143 disabled. When set to either true or 1, IPv6 is disabled unless other‐
144 wise specified in the <xref:System.AppContext?displayProperty=name‐
145 WithType>.
146 DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER
148 You can use one of the following mechanisms to configure a process to
149 use the older HttpClientHandler:
150 From code, use the AppContext class:
152 AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
154 The AppContext switch can also be set by a config file. For more in‐
156 formation configuring switches, see AppContext for library consumers.
157 The same can be achieved via the environment variable DOTNET_SYS‐
159 TEM_NET_HTTP_USESOCKETSHTTPHANDLER. To opt-out, set the value to ei‐
160 ther false or 0.
161 Starting in .NET 5, this setting to use <xref:Sys‐
163 tem.Net.Http.HttpClientHandler> is no longer available.
164 DOTNET_Jit* and DOTNET_GC*
166 There are two stressing-related features for the JIT and JIT-generated
167 GC information: JIT Stress and GC Hole Stress. These features provide
168 a way during development to discover edge cases and more “real world”
169 scenarios without having to develop complex applications. The follow‐
170 ing environment variables are available:
171 • DOTNET_JitStress
173 • DOTNET_JitStressModeNamesOnly
175 • DOTNET_GCStress
177 JIT stress
179 Enabling JIT Stress can be done in several ways. Set DOTNET_JitStress
180 to a non-zero integer value to generate varying levels of JIT optimiza‐
181 tions based on a hash of the method’s name. To apply all optimizations
182 set DOTNET_JitStress=2, for example. Another way to enable JIT Stress
183 is by setting DOTNET_JitStressModeNamesOnly=1 and then requesting the
184 stress modes, space-delimited, in the DOTNET_JitStressModeNames vari‐
185 able.
186 As an example, consider:
188 DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
190 GC Hole stress
192 Enabling GC Hole Stress causes GCs to always occur in specific loca‐
193 tions and that helps to track down GC holes. GC Hole Stress can be en‐
194 abled using the DOTNET_GCStress environment variable.
195 For more information, see Investigating JIT and GC Hole stress
197 (https://github.com/dotnet/runtime/blob/main/docs/design/core‐
198 clr/jit/investigate-stress.md).
199 JIT memory barriers
201 The code generator for Arm64 allows all MemoryBarriers instructions to
202 be removed by setting DOTNET_JitNoMemoryBarriers to 1.
203 DOTNET_RUNNING_IN_CONTAINER and DOTNET_RUNNING_IN_CONTAINERS
205 The official .NET images (Windows and Linux) set the well-known envi‐
206 ronment variables:
207 • DOTNET_RUNNING_IN_CONTAINER
209 • DOTNET_RUNNING_IN_CONTAINERS
211 These values are used to determine when your ASP.NET Core workloads are
213 running in the context of a container.
214 DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION
216 When <xref:System.Console.IsOutputRedirected?displayProperty=name‐
217 WithType> is true, you can emit ANSI color code by setting DOTNET_SYS‐
218 TEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION to either 1 or true.
219 DOTNET_SYSTEM_DIAGNOSTICS and related variables
221 • DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL: When
222 1 or true, the default Activity Id format is hierarchical.
223 • DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: When running as Debug, tracing
225 can be enabled when this is true.
226 DOTNET_DiagnosticPorts
228 Configures alternate endpoints where diagnostic tools can communicate
229 with the .NET runtime. See the Diagnostic Port documentation for more
230 information.
231 DOTNET_DefaultDiagnosticPortSuspend
233 Configures the runtime to pause during startup and wait for the Diag‐
234 nostics IPC ResumeStartup command from the specified diagnostic port
235 when set to 1. Defaults to 0. See the Diagnostic Port documentation
236 for more information.
237 DOTNET_EnableDiagnostics
239 When set to 1, enables debugging, profiling, and other diagnostics via
240 the Diagnostic Port. Defaults to 1.
241 EventPipe variables
243 See EventPipe environment variables for more information.
244 • DOTNET_EnableEventPipe: When set to 1, enables tracing via EventPipe.
246 • DOTNET_EventPipeOutputPath: The output path where the trace will be
248 written.
249 • DOTNET_EventPipeOutputStreaming: When set to 1, enables streaming to
251 the output file while the app is running. By default trace informa‐
252 tion is accumulated in a circular buffer and the contents are written
253 at app shutdown.
254 .NET SDK and CLI environment variables
256 DOTNET_ROOT, DOTNET_ROOT(x86)
257 Specifies the location of the .NET runtimes, if they are not installed
258 in the default location. The default location on Windows is C:\Program
259 Files\dotnet. The default location on Linux and macOS is /usr/lo‐
260 cal/share/dotnet. This environment variable is used only when running
261 apps via generated executables (apphosts). DOTNET_ROOT(x86) is used
262 instead when running a 32-bit executable on a 64-bit OS.
263 NUGET_PACKAGES
265 The global packages folder. If not set, it defaults to ~/.nuget/pack‐
266 ages on Unix or %userprofile%\.nuget\packages on Windows.
267 DOTNET_SERVICING
269 Specifies the location of the servicing index to use by the shared host
270 when loading the runtime.
271 DOTNET_NOLOGO
273 Specifies whether .NET welcome and telemetry messages are displayed on
274 the first run. Set to true to mute these messages (values true, 1, or
275 yes accepted) or set to false to allow them (values false, 0, or no ac‐
276 cepted). If not set, the default is false and the messages will be
277 displayed on the first run. This flag does not affect telemetry (see
278 DOTNET_CLI_TELEMETRY_OPTOUT for opting out of sending telemetry).
279 DOTNET_CLI_PERF_LOG
281 Specifies whether performance details about the current CLI session are
282 logged. Enabled when set to 1, true, or yes. This is disabled by de‐
283 fault.
284 DOTNET_GENERATE_ASPNET_CERTIFICATE
286 Specifies whether to generate an ASP.NET Core certificate. The default
287 value is true, but this can be overridden by setting this environment
288 variable to either 0, false, or no.
289 DOTNET_ADD_GLOBAL_TOOLS_TO_PATH
291 Specifies whether to add global tools to the PATH environment variable.
292 The default is true. To not add global tools to the path, set to 0,
293 false, or no.
294 DOTNET_CLI_TELEMETRY_OPTOUT
296 Specifies whether data about the .NET tools usage is collected and sent
297 to Microsoft. Set to true to opt-out of the telemetry feature (values
298 true, 1, or yes accepted). Otherwise, set to false to opt into the
299 telemetry features (values false, 0, or no accepted). If not set, the
300 default is false and the telemetry feature is active.
301 DOTNET_SKIP_FIRST_TIME_EXPERIENCE
303 If DOTNET_SKIP_FIRST_TIME_EXPERIENCE is set to true, the NuGetFallback‐
304 Folder won’t be expanded to disk and a shorter welcome message and
305 telemetry notice will be shown.
306 DOTNET_MULTILEVEL_LOOKUP
308 Specifies whether the .NET runtime, shared framework, or SDK are re‐
309 solved from the global location. If not set, it defaults to 1 (logical
310 true). Set the value to 0 (logical false) to not resolve from the
311 global location and have isolated .NET installations. For more infor‐
312 mation about multi-level lookup, see Multi-level SharedFX Lookup
313 (https://github.com/dotnet/core-setup/blob/master/Documentation/design-
314 docs/multilevel-sharedfx-lookup.md).
315 This environment variable only applies to applications that tar‐
317 get .NET 6 and earlier versions. Starting in .NET 7, .NET only
318 looks for frameworks in one location. For more information, see
319 Multi-level lookup is disabled.
320 DOTNET_ROLL_FORWARD
322 Determines roll forward behavior. For more information, see the
323 --roll-forward option for the dotnet command.
324 DOTNET_ROLL_FORWARD_TO_PRERELEASE
326 If set to 1 (enabled), enables rolling forward to a pre-release version
327 from a release version. By default (0 - disabled), when a release ver‐
328 sion of .NET runtime is requested, roll-forward will only consider in‐
329 stalled release versions.
330 For more information, see the --roll-forward option for the dotnet com‐
332 mand
333 DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX
335 Disables minor version roll forward, if set to 0. This setting is su‐
336 perseded in .NET Core 3.0 by DOTNET_ROLL_FORWARD. The new settings
337 should be used instead.
338 DOTNET_CLI_UI_LANGUAGE
340 Sets the language of the CLI UI using a locale value such as en-us.
341 The supported values are the same as for Visual Studio. For more in‐
342 formation, see the section on changing the installer language in the
343 Visual Studio installation documentation. The .NET resource manager
344 rules apply, so you don’t have to pick an exact match—you can also pick
345 descendants in the CultureInfo tree. For example, if you set it to fr-
346 CA, the CLI will find and use the fr translations. If you set it to a
347 language that is not supported, the CLI falls back to English.
348 DOTNET_DISABLE_GUI_ERRORS
350 For GUI-enabled generated executables - disables dialog popup, which
351 normally shows for certain classes of errors. It only writes to stderr
352 and exits in those cases.
353 DOTNET_ADDITIONAL_DEPS
355 Equivalent to CLI option --additional-deps.
356 DOTNET_RUNTIME_ID
358 Overrides the detected RID.
359 DOTNET_SHARED_STORE
361 Location of the “shared store” which assembly resolution falls back to
362 in some cases.
363 DOTNET_STARTUP_HOOKS
365 List of assemblies to load and execute startup hooks from.
366 DOTNET_BUNDLE_EXTRACT_BASE_DIR
368 Specifies a directory to which a single-file application is extracted
369 before it is executed.
370 For more information, see Single-file executables.
372 DOTNET_CLI_CONTEXT_*
374 • DOTNET_CLI_CONTEXT_VERBOSE: To enable a verbose context, set to true.
375 • DOTNET_CLI_CONTEXT_ANSI_PASS_THRU: To enable an ANSI pass-through,
377 set to true.
378 DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE
380 Disables background download of advertising manifests for workloads.
381 Default is false - not disabled. If set to true, downloading is dis‐
382 abled. For more information, see Advertising manifests.
383 DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS
385 Specifies the minimum number of hours between background downloads of
386 advertising manifests for workloads. Default is 24 - no more frequent‐
387 ly than once a day. For more information, see Advertising manifests.
388 COREHOST_TRACE
390 Controls diagnostics tracing from the hosting components, such as dot‐
391 net.exe, hostfxr, and hostpolicy.
392 • COREHOST_TRACE=[0/1] - default is 0 - tracing disabled. If set to 1,
394 diagnostics tracing is enabled.
395 • COREHOST_TRACEFILE=<file path> - has an effect only if tracing is en‐
397 abled by setting COREHOST_TRACE=1. When set, the tracing information
398 is written to the specified file; otherwise, the trace information is
399 written to stderr.
400 • COREHOST_TRACE_VERBOSITY=[1/2/3/4] - default is 4. The setting is
402 used only when tracing is enabled via COREHOST_TRACE=1.
403 • 4 - all tracing information is written
405 • 3 - only informational, warning, and error messages are written
407 • 2 - only warning and error messages are written
409 • 1 - only error messages are written
411 The typical way to get detailed trace information about application
413 startup is to set COREHOST_TRACE=1 andCOREHOST_TRACEFILE=host_trace.txt
414 and then run the application. A new file host_trace.txt will be creat‐
415 ed in the current directory with the detailed information.
416 SuppressNETCoreSdkPreviewMessage
418 If set to true, invoking dotnet won’t produce a warning when a preview
419 SDK is being used.
420 Configure MSBuild in the .NET CLI
422 To execute MSBuild out-of-process, set the DOTNET_CLI_RUN_MSBUILD_OUT‐
423 OFPROC environment variable to either 1, true, or yes. By default, MS‐
424 Build will execute in-proc. To force MSBuild to use an external work‐
425 ing node long-living process for building projects, set DOT‐
426 NET_CLI_USE_MSBUILDNOINPROCNODE to 1, true, or yes. This will set the
427 MSBUILDNOINPROCNODE environment variable to 1, which is referred to as
428 MSBuild Server V1, as the entry process forwards most of the work to
429 it.
430 DOTNET_MSBUILD_SDK_RESOLVER_*
432 These are overrides that are used to force the resolved SDK tasks and
433 targets to come from a given base directory and report a given version
434 to MSBuild, which may be null if unknown. One key use case for this is
435 to test SDK tasks and targets without deploying them by using the .NET
436 Core SDK.
437 • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR: Overrides the .NET SDK directo‐
439 ry.
440 • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER: Overrides the .NET SDK version.
442 • DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: Overrides the dotnet.exe direc‐
444 tory path.
445 DOTNET_NEW_PREFERRED_LANG
447 Configures the default programming language for the dotnet new command
448 when the -lang|--language switch is omitted. The default value is C#.
449 Valid values are C#, F#, or VB. For more information, see dotnet new.
450
452 For information about dotnet watch settings that are available as envi‐
453 ronment variables, see dotnet watch environment variables.
454
456 • dotnet command
457 • Runtime Configuration Files (https://github.com/dot‐
459 net/sdk/blob/main/documentation/specs/runtime-configuration-file.md)
460 • .NET runtime configuration settings
462 2022-09-19 dotnet-environment-variables(7)