From 40922aed8f94da7eed6f36ba82f2de5da470469d Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 6 Jul 2026 09:30:29 -0500 Subject: [PATCH 1/5] Document DOTNET_CLI_ENABLEAOT environment variable Adds the DOTNET_CLI_ENABLEAOT variable (NativeAOT CLI command-handling fast path, enabled by default) to the .NET SDK and CLI environment variables reference. Fixes #54648 --- docs/core/tools/dotnet-environment-variables.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 3db2af9a1a1c3..fc7c4b716edc0 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -192,6 +192,7 @@ This section describes the following environment variables: - [`DOTNET_SERVICING`](#dotnet_servicing) - [`DOTNET_NOLOGO`](#dotnet_nologo) - [`DOTNET_CLI_PERF_LOG`](#dotnet_cli_perf_log) +- [`DOTNET_CLI_ENABLEAOT`](#dotnet_cli_enableaot) - [`DOTNET_GENERATE_ASPNET_CERTIFICATE`](#dotnet_generate_aspnet_certificate) - [`DOTNET_ADD_GLOBAL_TOOLS_TO_PATH`](#dotnet_add_global_tools_to_path) - [`DOTNET_CLI_TELEMETRY_OPTOUT`](#dotnet_cli_telemetry_optout) @@ -324,6 +325,12 @@ Specifies whether .NET welcome and telemetry messages are displayed on the first 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_CLI_ENABLEAOT` + +Specifies whether the .NET SDK uses its native (ahead-of-time compiled) CLI command-handling fast path. When enabled, common commands (such as command parsing, `dotnet --version`, and `dotnet --info`) are handled by a native entry point for faster startup, transparently falling back to the managed CLI for anything the fast path doesn't handle. + +This fast path is enabled by default. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it, set it to `true`, `1`, `yes`, or `on`, or leave it unset. + ### `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`. From d34b1423e21ffb571c33d8ebcc2d10df1c73599f Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 6 Jul 2026 09:47:07 -0500 Subject: [PATCH 2/5] Note macOS exclusion for DOTNET_CLI_ENABLEAOT The fast path is disabled by default on macOS pending dotnet/command-line-api#2812. --- docs/core/tools/dotnet-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index fc7c4b716edc0..4bfbab00ca970 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -329,7 +329,7 @@ Specifies whether performance details about the current CLI session are logged. Specifies whether the .NET SDK uses its native (ahead-of-time compiled) CLI command-handling fast path. When enabled, common commands (such as command parsing, `dotnet --version`, and `dotnet --info`) are handled by a native entry point for faster startup, transparently falling back to the managed CLI for anything the fast path doesn't handle. -This fast path is enabled by default. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it, set it to `true`, `1`, `yes`, or `on`, or leave it unset. +This fast path is enabled by default on all platforms except macOS. On macOS it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)) and will be enabled once that issue is resolved. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it (for example, on macOS), set it to `true`, `1`, `yes`, or `on`. ### `DOTNET_GENERATE_ASPNET_CERTIFICATE` From b88ddc022836e27d82fd4afe97e15537c7acd117 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 6 Jul 2026 10:32:40 -0500 Subject: [PATCH 3/5] Update DOTNET_CLI_ENABLEAOT: default-on Windows only (macOS + Linux blocked by command-line-api#2812) --- docs/core/tools/dotnet-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 4bfbab00ca970..3227130b994ea 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -329,7 +329,7 @@ Specifies whether performance details about the current CLI session are logged. Specifies whether the .NET SDK uses its native (ahead-of-time compiled) CLI command-handling fast path. When enabled, common commands (such as command parsing, `dotnet --version`, and `dotnet --info`) are handled by a native entry point for faster startup, transparently falling back to the managed CLI for anything the fast path doesn't handle. -This fast path is enabled by default on all platforms except macOS. On macOS it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)) and will be enabled once that issue is resolved. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it (for example, on macOS), set it to `true`, `1`, `yes`, or `on`. +This fast path is enabled by default only on Windows. On macOS and Linux it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)): when the native CLI is loaded as a NativeAOT shared library, `Environment.GetCommandLineArgs()` returns an empty array on those platforms, which causes command parsing to throw. It will be enabled on macOS and Linux once that issue is resolved. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it (for example, on macOS or Linux), set it to `true`, `1`, `yes`, or `on`. ### `DOTNET_GENERATE_ASPNET_CERTIFICATE` From 3fcddf835e38a98b0122c0f49e34aac1b888d662 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 6 Jul 2026 13:41:50 -0500 Subject: [PATCH 4/5] DOTNET_CLI_ENABLEAOT: rework flow and move default-platform caveat into a Note --- docs/core/tools/dotnet-environment-variables.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 3227130b994ea..dcf07e47a6639 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -327,9 +327,15 @@ Specifies whether performance details about the current CLI session are logged. ### `DOTNET_CLI_ENABLEAOT` -Specifies whether the .NET SDK uses its native (ahead-of-time compiled) CLI command-handling fast path. When enabled, common commands (such as command parsing, `dotnet --version`, and `dotnet --info`) are handled by a native entry point for faster startup, transparently falling back to the managed CLI for anything the fast path doesn't handle. +Specifies whether the .NET SDK uses its native (ahead-of-time compiled) CLI command-handling fast path. When enabled, common commands (such as command-line parsing, `dotnet --version`, and `dotnet --info`) are handled by a native entry point for faster startup, transparently falling back to the managed CLI for anything the fast path doesn't handle. -This fast path is enabled by default only on Windows. On macOS and Linux it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)): when the native CLI is loaded as a NativeAOT shared library, `Environment.GetCommandLineArgs()` returns an empty array on those platforms, which causes command parsing to throw. It will be enabled on macOS and Linux once that issue is resolved. To opt out and route every invocation to the managed CLI, set this variable to `false`, `0`, `no`, or `off`. To explicitly enable it (for example, on macOS or Linux), set it to `true`, `1`, `yes`, or `on`. +Set this variable to control the fast path explicitly: + +- To enable it, set the variable to `true`, `1`, `yes`, or `on`. +- To disable it and route every invocation to the managed CLI, set the variable to `false`, `0`, `no`, or `off`. + +> [!NOTE] +> This fast path is enabled by default only on Windows. On macOS and Linux it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)): when the native CLI is loaded as a NativeAOT shared library, `Environment.GetCommandLineArgs()` returns an empty array on those platforms, which causes command-line parsing to throw. It will be enabled by default on macOS and Linux once that issue is resolved. In the meantime, you can opt in early on those platforms by setting the variable to a value that enables it. ### `DOTNET_GENERATE_ASPNET_CERTIFICATE` From e9a52b27579b0d412893fd1f5a23766f8e7ffb84 Mon Sep 17 00:00:00 2001 From: Chet Husk Date: Mon, 6 Jul 2026 13:55:06 -0500 Subject: [PATCH 5/5] DOTNET_CLI_ENABLEAOT: note that Windows default becomes true in .NET 11 Preview 7 --- docs/core/tools/dotnet-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index dcf07e47a6639..141dcafcef2c3 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -335,7 +335,7 @@ Set this variable to control the fast path explicitly: - To disable it and route every invocation to the managed CLI, set the variable to `false`, `0`, `no`, or `off`. > [!NOTE] -> This fast path is enabled by default only on Windows. On macOS and Linux it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)): when the native CLI is loaded as a NativeAOT shared library, `Environment.GetCommandLineArgs()` returns an empty array on those platforms, which causes command-line parsing to throw. It will be enabled by default on macOS and Linux once that issue is resolved. In the meantime, you can opt in early on those platforms by setting the variable to a value that enables it. +> Starting in .NET 11 Preview 7, this fast path is enabled by default (`true`) on Windows. On macOS and Linux it's disabled by default because of a command-line parsing issue ([dotnet/command-line-api#2812](https://github.com/dotnet/command-line-api/issues/2812)): when the native CLI is loaded as a NativeAOT shared library, `Environment.GetCommandLineArgs()` returns an empty array on those platforms, which causes command-line parsing to throw. It will be enabled by default on macOS and Linux once that issue is resolved. In the meantime, you can opt in early on those platforms by setting the variable to a value that enables it. ### `DOTNET_GENERATE_ASPNET_CERTIFICATE`