Поделиться через


Переменные среды .NET

Эта статья относится к: ✔️ пакету SDK для .NET Core 3.1 и более поздних версий

В этой статье вы узнаете о переменных среды, используемых .NET. Одни переменные среды используются средой выполнения .NET, а другие используются только пакетом SDK для .NET и .NET CLI. Некоторые переменные среды используются всеми тремя компонентами.

Переменные среды выполнения .NET

DOTNET_SYSTEM_NET_HTTP_*

Существует несколько глобальных параметров переменной среды HTTP:

  • DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
    • Указывает, следует ли включать распространение действия обработчика диагностики для глобальных параметров HTTP.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
    • Если задано значение false или 0, отключает поддержку HTTP/2, которая включена по умолчанию.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
    • Если задано значение true или 1, отключает поддержку HTTP/3, которая включена по умолчанию.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
    • Если задано значение false или 0, переопределяет значение по умолчанию и отключает алгоритм динамического масштабирования окон HTTP/2.
  • DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE
    • Значение по умолчанию — 16 МБ. Если значение переопределено, максимальный размер окна приема потока 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: указывает, следует ли использовать Международные компоненты для Юникода (ICU) с параметром app-local. Дополнительные сведения см. в разделе ICU с параметром app-local.

Установка инвариантного режима

Приложения могут включать инвариантный режим одним из следующих способов.

  1. В файле проекта:

    <PropertyGroup>
        <InvariantGlobalization>true</InvariantGlobalization>
    </PropertyGroup>
    
  2. В файле runtimeconfig.json:

    {
        "runtimeOptions": {
            "configProperties": {
                "System.Globalization.Invariant": true
            }
        }
    }
    
  3. Путем задания true или 1 в качестве значения переменной среды DOTNET_SYSTEM_GLOBALIZATION_INVARIANT.

Внимание

Значение, заданное в файле проекта или файле runtimeconfig.json имеет более высокий приоритет, чем переменная среды.

Дополнительные сведения см. в статье Инвариантный режим глобализации .NET.

DOTNET_SYSTEM_GLOBALIZATION_USENLS

Применимо только к Windows. Чтобы использовать поддержку национальных языков (NLS) в глобализации, задайте переменной DOTNET_SYSTEM_GLOBALIZATION_USENLS значение true или 1. Чтобы не использовать эту поддержку, задайте переменной DOTNET_SYSTEM_GLOBALIZATION_USENLS значение false или 0.

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. По умолчанию он отключен.

Примечание.

Этот параметр может ухудшить производительность, если имеется дорогостоящая работа, которая в итоге будет удерживать поток ввода-вывода дольше, чем требуется. Проверьте, что этот параметр не приводит к снижению производительности.

Используя тесты TechEmpower, которые создают много небольших сокетов считывает и записывает под очень высокую нагрузку, один обработчик сокетов способен поддерживать нагрузку до тридцати x64 и восемь ядер ЦП Arm64. В подавляющем большинстве реальных сценариев никогда не будет создаваться такая огромная нагрузка (сотни тысяч запросов в секунду), и почти всегда достаточно одного производителя. Однако, чтобы гарантировать возможность обработки экстремальных нагрузок, можно переопределить вычисленное значение с помощью DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT. Если значение не переопределено, используется следующее значение:

  • Если DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS имеет значение 1, используется значение Environment.ProcessorCount.
  • Если DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS это не 1так, RuntimeInformation.ProcessArchitecture вычисляется:
    • Если в arm или Arm64 для ядер для каждого значения ядра задано 8значение , в противном случае 30.
  • При использовании определенных ядер на подсистему максимальное значение количества ядер на подсистему составляет 1 или Environment.ProcessorCount.

DOTNET_SYSTEM_NET_DISABLEIPV6

Помогает определить, отключен ли протокол IP версии 6 (IPv6). Если задано значение true или 1, IPv6 отключен, если в System.AppContext не указано иное.

DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER

Чтобы настроить процесс для использования старого класса HttpClientHandler, можно использовать один из приведенных ниже механизмов.

В коде используйте AppContext класс:

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

Параметр AppContext можно также задать в файле конфигурации. Дополнительные сведения о настройке параметров см. в разделе AppContext для потребителей библиотек.

То же самое можно сделать с помощью переменной среды DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER. Чтобы не использовать эту возможность, задайте значение false или 0.

Примечание.

Начиная с .NET 5 этот параметр HttpClientHandler больше недоступен.

DOTNET_Jit* и DOTNET_GC*.

Существует две функции, связанные с напряжением для JIT и JIT-генерируемых данных для сборки мусора: JIT Stress и GC Hole Stress. Эти функции позволяют в процессе разработки обнаруживать пограничные случаи и более реальные сценарии без необходимости разработки сложных приложений. Доступны следующие переменные среды:

  • DOTNET_JitStress
  • DOTNET_JitStressModeNamesOnly
  • DOTNET_GCStress

JIT Stress

Включить JIT Stress можно несколькими способами. Задайте DOTNET_JitStress ненулевое целочисленное значение, чтобы создать различные уровни JIT-оптимизации на основе хэша имени метода. Для применения всех оптимизаций задайте, к примеру DOTNET_JitStress=2. Другой способ включения JIT Stress заключается в задании DOTNET_JitStressModeNamesOnly=1 и последующем запросе режимов нагрузки, разделенных пробелами, в переменной DOTNET_JitStressModeNames.

Далее приведен пример:

DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS

GC Hole Stress

Включение GC Hole Stress приводит к тому, что сборка мусора всегда происходит в определенных местах, и это помогает отслеживать заглушки сборщиков мусора. GC Hole Stress можно включить с помощью переменной среды DOTNET_GCStress.

Дополнительные сведения см. в статье о JIT Stress и GC Hole Stress.

Барьеры памяти JIT

Генератор кода для Arm64 позволяет удалить все MemoryBarriers инструкции, установив для него значение DOTNET_JitNoMemoryBarriers1.

DOTNET_RUNNING_IN_CONTAINER и DOTNET_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.IsOutputRedirected имеет значение true, можно создать цветовой код ANSI, задав DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION значение 1 или true.

  • DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL: если задано значение 1 или true, форматом идентификатора действия по умолчанию является иерархический.
  • DOTNET_SYSTEM_RUNTIME_CACHING_TRACING: при запуске в режиме отладки трассировку можно включить, задав переменной значение true.

DOTNET_DiagnosticPorts

Настраивает альтернативные конечные точки, в которых средства диагностики могут взаимодействовать с средой выполнения .NET. Дополнительные сведения см. в документации по портам диагностики.

DOTNET_DefaultDiagnosticPortSuspend

Настраивает среду выполнения для приостановки во время запуска и ожидания команды Diagnostics IPC ResumeStartup из указанного порта диагностики при установке значения 1. Значение по умолчанию — 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, включает потоковую передачу в выходной файл во время работы приложения. По умолчанию данные трассировки накапливаются в циклический буфер, а содержимое записывается при завершении работы приложения.

Переменные среды пакета SDK для .NET и CLI

DOTNET_ROOT, , DOTNET_ROOT(x86)DOTNET_ROOT_X86DOTNET_ROOT_X64

Указывает расположение сред выполнения .NET, если оно отличается от задаваемого по умолчанию. В ОС Windows по умолчанию используется расположение C:\Program Files\dotnet. Расположение по умолчанию в macOS /usr/local/share/dotnet. Расположение по умолчанию для сред выполнения x64 в ОС arm64 находится в подпапке x64 (так C:\Program Files\dotnet\x64 в окнах и /usr/local/share/dotnet/x64 macOS). Расположение по умолчанию в Linux зависит от метода дистрибутива и установки. Расположение по умолчанию в Ubuntu 22.04 — /usr/share/dotnet (при установке packages.microsoft.comиз ) или /usr/lib/dotnet (при установке из веб-канала Jammy). Дополнительные сведения см. на следующих ресурсах:

Эта переменная среды используется только при запуске приложений с помощью созданных исполняемых файлов (apphost). При запуске 32-разрядного исполняемого файла в 64-разрядной ОС вместо нее используется DOTNET_ROOT(x86). DOTNET_ROOT_X64 вместо этого используется при запуске 64-разрядного исполняемого файла в ОС ARM64.

DOTNET_HOST_PATH

Указывает абсолютный dotnet путь к узлу (dotnet.exe в Windows, dotnet в Linux и macOS), который использовался для запуска текущего dotnet процесса. Это используется пакетом SDK для .NET, чтобы помочь средствам, выполняемым во время команд пакета SDK для .NET, гарантировать, что они используют ту же dotnet среду выполнения для любых дочерних dotnet процессов, которые они создают в течение длительности команды. Ожидается, что средства и задачи MSBuild в пакете SDK, вызывающие двоичные файлы через dotnet узел, будут учитывать эту переменную среды, чтобы обеспечить согласованный интерфейс.

Средства, вызываемые dotnet во время команды ПАКЕТА SDK, должны использовать следующий алгоритм, чтобы найти его:

  • Если DOTNET_HOST_PATH задано, используйте это значение напрямую
  • в противном случае следует полагаться dotnet через систему PATH

Примечание.

DOTNET_HOST_PATH не является общим решением для поиска dotnet узла. Оно предназначено только для использования средствами, которые вызываются пакетом SDK для .NET.

DOTNET_LAUNCH_PROFILE

Команда dotnet run задает эту переменную выбранному профилю запуска.

Учитывая следующий файл запуска Параметры.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 для отключения звука этих сообщений (принимаются значения true, 1 или yes) или установите значение false для разрешения звука (принимаются значения false, 0 или no). Если значение не задано, по умолчанию используется false, и сообщения будут отображаться при первом запуске. Этот флаг не влияет на данные телеметрии (см. DOTNET_CLI_TELEMETRY_OPTOUT, чтобы отменить отправку телеметрии).

DOTNET_CLI_PERF_LOG

Указывает, записываются ли в журнал сведения о производительности текущего сеанса CLI. Включена, если задано значение 1, true или yes. Эта функция отключена по умолчанию.

DOTNET_GENERATE_ASPNET_CERTIFICATE

Указывает, следует ли создавать сертификат ASP.NET Core. Значение по умолчанию — true, но его можно переопределить, задав для этой переменной среды значения 0, false или no.

DOTNET_ADD_GLOBAL_TOOLS_TO_PATH

Указывает, следует ли добавлять глобальные средства в переменную среды PATH. Значение по умолчанию — true. Чтобы не добавлять глобальные средства, задайте значения 0, false или no.

DOTNET_CLI_TELEMETRY_OPTOUT

Указывает, собираются ли данные по использованию средств .NET для отправки в корпорацию Майкрософт. Установите значение true, чтобы отказаться от функций телеметрии (поддерживаются значения true, 1 или yes). Также можно установить значение false, чтобы согласиться на функции телеметрии (поддерживаются значения false, 0 или no). Если значение не задано, то по умолчанию используется false, то есть функция телеметрии включена.

DOTNET_SKIP_FIRST_TIME_EXPERIENCE

Если для DOTNET_SKIP_FIRST_TIME_EXPERIENCE задано значение true, папка NuGetFallbackFolder не будет развернута на диске и отобразиться более короткое приветственное сообщение и уведомление телеметрии.

Примечание.

Эта переменная среды больше не поддерживается в .NET Core 3.0 и более поздних версиях. Используйте DOTNET_NOLOGO в качестве замены.

DOTNET_MULTILEVEL_LOOKUP

Указывает, разрешена ли среда выполнения .NET, общая платформа или пакет SDK из глобального расположения. Если не задано, используется значение по умолчанию 1 (логическое значение true). Задайте для значения 0 (логического false) значение, чтобы не разрешаться из глобального расположения и изолированы установки .NET. Дополнительные сведения о многоуровневом поиске см. в разделе Многоуровневый поиск SharedFX.

Примечание.

Эта переменная среды применяется только к приложениям, предназначенным для .NET 6 и более ранних версий. Начиная с .NET 7. .NET ищет только платформы в одном расположении. Дополнительные сведения см. в разделе "Поиск на нескольких уровнях" отключен.

DOTNET_ROLL_FORWARD

Определяет поведение наката. Дополнительные сведения см . в --roll-forward параметре dotnet команды.

DOTNET_ROLL_FORWARD_TO_PRERELEASE

Если задано значение 1 (включено), поддерживается накат версии выпуска на предварительную версию. По умолчанию (если 0 отключено) при запросе версии выпуска среды выполнения .NET накат будет выполняться только для установленных версий выпуска.

Дополнительные сведения см . в параметре --roll-forwarddotnet команды

DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX

Отключает накат дополнительных версий, если установлено 0. Этот параметр в .NET Core 3.0 заменяется DOTNET_ROLL_FORWARD. Вместо этого следует использовать новый параметр.

DOTNET_CLI_FORCE_UTF8_ENCODING

Принудительно использует кодировку UTF-8 в консоли, даже для более старых версий Windows 10, которые не полностью поддерживают UTF-8. Дополнительные сведения см. в разделе SDK, который больше не изменяет кодировку консоли после завершения.

DOTNET_CLI_UI_LANGUAGE

Задает язык пользовательского интерфейса CLI с помощью значения языкового стандарта, например en-us. Поддерживаются те же значения, что и для Visual Studio. Дополнительные сведения см. в разделе, посвященном изменению языка установщика, в документации по установке Visual Studio. Применяются правила диспетчера ресурсов .NET, поэтому вам не нужно выбрать точное совпадение, вы также можете выбрать потомков в CultureInfo дереве. Например, если задать значение fr-CA, интерфейс командной строки будет находить и использовать переводы fr. Если задать язык, который не поддерживается, для интерфейса командной строки будет использоваться английский язык.

DOTNET_DISABLE_GUI_ERRORS

Для создаваемых исполняемых файлов с поддержкой графического пользовательского интерфейса отключает всплывающее диалоговое окно, которое обычно выводится для определенных классов ошибок. В таких случаях выполняются только запись в stderr и выход.

DOTNET_ADDITIONAL_DEPS

Эквивалентно параметру --additional-deps интерфейса командной строки.

DOTNET_RUNTIME_ID

Переопределяет обнаруженный RID.

DOTNET_SHARED_STORE

Расположение общего хранилища, которое в некоторых случаях используется для разрешения сборки.

DOTNET_STARTUP_HOOKS

Список сборок, из которого осуществляется загрузка и выполнение перехватчиков запуска.

DOTNET_BUNDLE_EXTRACT_BASE_DIR

Указывает каталог, в который извлекается однофайловое приложение перед выполнением.

Дополнительные сведения об однофайловых исполняемых файлах см. здесь.

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

Указывает, выполняются ли локальные средства sdk для .NET для поиска файлов манифеста инструментов в корневой папке в Windows. Значение по умолчанию — false.

COREHOST_TRACE

Управляет диагностической трассировкой из компонентов размещения, таких как dotnet.exe, hostfxr и hostpolicy.

  • 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=1 и COREHOST_TRACEFILE=host_trace.txt, а затем запускают приложение. В текущем каталоге будет создан новый файл host_trace.txt с подробными сведениями.

SuppressNETCoreSdkPreviewMessage

Если задано значение true, в результате вызова dotnet не будет отображаться предупреждение при использовании предварительной версии пакета SDK.

Настройка MSBuild в .NET CLI

Для внепроцессного выполнения MSBuild задайте переменной среды DOTNET_CLI_RUN_MSBUILD_OUTOFPROC значение 1, true или yes. По умолчанию MSBuild будет выполняться внутри процесса. Чтобы платформа MSBuild использовала внешний долговечный процесс рабочего узла для сборки проектов, задайте DOTNET_CLI_USE_MSBUILDNOINPROCNODE значение 1, true или yes. При этом переменной среды MSBUILDNOINPROCNODE будет задано значение 1, которое называется MSBuild Server V1, так как процесс ввода направляет на него большую часть работы.

DOTNET_MSBUILD_SDK_RESOLVER_*

Это переопределения, которые используются для того, чтобы источником разрешенных задач и целевых объектов пакета SDK был заданный базовый каталог и сообщать версию в MSBuild (она может иметь значение null, если неизвестна). Одним из ключевых вариантов использования является проверка задач и целевых объектов пакета SDK без их развертывания с помощью пакета SDK для .NET Core.

  • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR: переопределяет каталог пакета SDK для .NET.
  • DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER: переопределяет версию пакета SDK для .NET.
  • DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: переопределяет путь к каталогу dotnet.exe.

DOTNET_NEW_PREFERRED_LANG

Настраивает язык программирования по умолчанию для команды dotnet new, когда параметр -lang|--language пропущен. Значение по умолчанию — C#. Допустимые значения: C#, F# или VB. Дополнительные сведения см. в разделе dotnet new.

dotnet watch переменные среды

Сведения о dotnet watch параметрах, доступных в качестве переменных среды, см. в разделе dotnet watch environment переменных.

См. также