1dotnet-environment-variables(7).NET Documentationdotnet-environment-variables(7)
2
3
4

NAME

6       dotnet-environment-variables - .NET environment variables
7

DESCRIPTION

9       This article applies to: ✔️ .NET Core 3.1 SDK and later versions
10
11       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
16   .NET runtime environment variables
17   DOTNET_SYSTEM_NET_HTTP_*
18       There are several global HTTP environment variable settings:
19
20DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
21
22         • Indicates whether or not to enable activity propagation of the  di‐
23           agnostic handler for global HTTP settings.
24
25DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
26
27         • When  set  to false or 0, disables HTTP/2 support, which is enabled
28           by default.
29
30DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
31
32         • When set to true or 1, enables HTTP/3 support, which is disabled by
33           default.
34
35DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDY‐
36         NAMICWINDOWSIZING
37
38         • When set to false or 0, overrides  the  default  and  disables  the
39           HTTP/2 dynamic window scaling algorithm.
40
41DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWIN‐
42         DOWSIZE
43
44         • Defaults to 16 MB.  When overridden, the maximum size of the HTTP/2
45           stream receive window cannot be less than 65,535.
46
47DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWS‐
48         CALETHRESHOLDMULTIPLIER
49
50         • 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
53   DOTNET_SYSTEM_GLOBALIZATION_*
54DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: See set invariant mode.
55
56DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY:       Specifies
57         whether to load only predefined cultures.
58
59DOTNET_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
63   Set invariant mode
64       Applications can enable the invariant mode  in  any  of  the  following
65       ways:
66
67       1. In the project file:
68
69                  <PropertyGroup>
70                      <InvariantGlobalization>true</InvariantGlobalization>
71                  </PropertyGroup>
72
73       2. In the runtimeconfig.json file:
74
75                  {
76                      "runtimeOptions": {
77                          "configProperties": {
78                              "System.Globalization.Invariant": true
79                          }
80                      }
81                  }
82
83       3. By   setting  environment  variable  value  DOTNET_SYSTEM_GLOBALIZA‐
84          TION_INVARIANT to true or 1.
85
86          A value set in the project file or runtimeconfig.json has  a  higher
87          priority than the environment variable.
88
89       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
93   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
99   DOTNET_SYSTEM_NET_SOCKETS_*
100       This section focuses on two System.Net.Sockets environment variables:
101
102DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
103
104DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
105
106       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
112              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
116       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
126       • When   DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS   is    1,    the
127         <xref:System.Environment.ProcessorCount?displayProperty=nameWithType>
128         value is used.
129
130       • When   DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS   is    not    1,
131         <xref:System.Runtime.InteropServices.RuntimeInformation.ProcessArchi‐
132         tecture?displayProperty=nameWithType> is evaluated:
133
134         • When Arm or Arm64 the cores per engine value is set to 8, otherwise
135           30.
136
137       • 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
141   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
147   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
151       From code, use the AppContext class:
152
153              AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
154
155       The  AppContext  switch can also be set by a config file.  For more in‐
156       formation configuring switches, see AppContext for library consumers.
157
158       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
162              Starting  in  .NET   5,   this   setting   to   use   <xref:Sys‐
163              tem.Net.Http.HttpClientHandler> is no longer available.
164
165   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
172DOTNET_JitStress
173
174DOTNET_JitStressModeNamesOnly
175
176DOTNET_GCStress
177
178   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
187       As an example, consider:
188
189              DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
190
191   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
196       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
200   JIT memory barriers
201       The  code generator for Arm64 allows all MemoryBarriers instructions to
202       be removed by setting DOTNET_JitNoMemoryBarriers to 1.
203
204   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
208DOTNET_RUNNING_IN_CONTAINER
209
210DOTNET_RUNNING_IN_CONTAINERS
211
212       These values are used to determine when your ASP.NET Core workloads are
213       running in the context of a container.
214
215   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
220   DOTNET_SYSTEM_DIAGNOSTICS and related variables
221DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL:  When
222         1 or true, the default Activity Id format is hierarchical.
223
224DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: When running as Debug, tracing
225         can be enabled when this is true.
226
227   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
232   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
238   DOTNET_EnableDiagnostics
239       When  set to 1, enables debugging, profiling, and other diagnostics via
240       the Diagnostic Port.  Defaults to 1.
241
242   EventPipe variables
243       See EventPipe environment variables for more information.
244
245DOTNET_EnableEventPipe: When set to 1, enables tracing via EventPipe.
246
247DOTNET_EventPipeOutputPath: The output path where the trace  will  be
248         written.
249
250DOTNET_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
255   .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
264   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
268   DOTNET_SERVICING
269       Specifies the location of the servicing index to use by the shared host
270       when loading the runtime.
271
272   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
280   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
285   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
290   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
295   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
302   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
307   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
316              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
321   DOTNET_ROLL_FORWARD
322       Determines  roll  forward  behavior.   For  more  information,  see the
323       --roll-forward option for the dotnet command.
324
325   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
331       For more information, see the --roll-forward option for the dotnet com‐
332       mand
333
334   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
339   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
349   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
354   DOTNET_ADDITIONAL_DEPS
355       Equivalent to CLI option --additional-deps.
356
357   DOTNET_RUNTIME_ID
358       Overrides the detected RID.
359
360   DOTNET_SHARED_STORE
361       Location  of the “shared store” which assembly resolution falls back to
362       in some cases.
363
364   DOTNET_STARTUP_HOOKS
365       List of assemblies to load and execute startup hooks from.
366
367   DOTNET_BUNDLE_EXTRACT_BASE_DIR
368       Specifies a directory to which a single-file application  is  extracted
369       before it is executed.
370
371       For more information, see Single-file executables.
372
373   DOTNET_CLI_CONTEXT_*
374DOTNET_CLI_CONTEXT_VERBOSE: To enable a verbose context, set to true.
375
376DOTNET_CLI_CONTEXT_ANSI_PASS_THRU:  To  enable  an ANSI pass-through,
377         set to true.
378
379   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
384   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
389   COREHOST_TRACE
390       Controls diagnostics tracing from the hosting components, such as  dot‐
391       net.exe, hostfxr, and hostpolicy.
392
393COREHOST_TRACE=[0/1] - default is 0 - tracing disabled.  If set to 1,
394         diagnostics tracing is enabled.
395
396COREHOST_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
401COREHOST_TRACE_VERBOSITY=[1/2/3/4]  -  default  is 4.  The setting is
402         used only when tracing is enabled via COREHOST_TRACE=1.
403
4044 - all tracing information is written
405
4063 - only informational, warning, and error messages are written
407
4082 - only warning and error messages are written
409
4101 - only error messages are written
411
412       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
417   SuppressNETCoreSdkPreviewMessage
418       If  set to true, invoking dotnet won’t produce a warning when a preview
419       SDK is being used.
420
421   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
431   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
438DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR: Overrides the .NET SDK directo‐
439         ry.
440
441DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER: Overrides the .NET SDK version.
442
443DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: Overrides the dotnet.exe  direc‐
444         tory path.
445
446   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

dotnet watch ENVIRONMENT VARIABLES

452       For information about dotnet watch settings that are available as envi‐
453       ronment variables, see dotnet watch environment variables.
454

SEE ALSO

456       • dotnet command
457
458       • Runtime      Configuration       Files       (https://github.com/dot
459         net/sdk/blob/main/documentation/specs/runtime-configuration-file.md)
460
461       • .NET runtime configuration settings
462
463
464
465                                  2022-09-19   dotnet-environment-variables(7)
Impressum