diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 521cb77a3ea0e..4acefa735a871 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -98,6 +98,7 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- |-------------------------------------------------------------------|-------------------| | [dnx scripts bypass global.json SDK selection](sdk/11/dnx-scripts-bypass-global-json.md) | Behavioral change | | [mono launch target not set for .NET Framework apps](sdk/11/mono-launch-target-removed.md) | Behavioral change | +| [NativeAOT CLI command handling enabled by default](sdk/11/native-cli-command-handling-enabled.md) | Behavioral change | | [NU1703 warns for packages that use deprecated MonoAndroid framework assets](sdk/11/nu1703-deprecated-monoandroid-framework.md) | Source incompatible | | [NuGet pack warns for package IDs with restricted characters](sdk/11/nuget-pack-nu5052-packageid.md) | Behavioral change | | [Template engine packages no longer support netstandard2.0](sdk/11/template-engine-netstandard.md) | Binary/source incompatible | diff --git a/docs/core/compatibility/sdk/11/native-cli-command-handling-enabled.md b/docs/core/compatibility/sdk/11/native-cli-command-handling-enabled.md new file mode 100644 index 0000000000000..a16fb446c4315 --- /dev/null +++ b/docs/core/compatibility/sdk/11/native-cli-command-handling-enabled.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: NativeAOT CLI command handling enabled by default" +description: "Learn about the breaking change in .NET 11 where the NativeAOT-compiled command-handling fast path for the dotnet CLI is enabled by default on all platforms." +ms.date: 08/04/2026 +ai-usage: ai-assisted +--- + +# NativeAOT CLI command handling enabled by default + +Starting in .NET 11, the .NET SDK CLI enables its NativeAOT-compiled command-handling fast path by default on all platforms. This path is controlled by the [`DOTNET_CLI_ENABLEAOT`](../../../tools/dotnet-environment-variables.md#dotnet_cli_enableaot) environment variable, whose default changes from disabled to enabled. Common `dotnet` invocations, such as command-line parsing, `--version`, `--info`, and a growing set of built-in and external commands, are handled by a native entry point that transparently falls back to the managed CLI for anything it doesn't handle. + +## Version introduced + +.NET 11 Preview 7 + +## Previous behavior + +Previously, the NativeAOT CLI fast path was off by default on all platforms. Unless [`DOTNET_CLI_ENABLEAOT`](../../../tools/dotnet-environment-variables.md#dotnet_cli_enableaot) was explicitly set to a truthy value (`true`, `1`, `yes`, or `on`), every `dotnet` invocation was handled by the managed CLI. + +## New behavior + +Starting in .NET 11, the NativeAOT CLI fast path is on by default on all platforms (Windows, macOS, and Linux). Supported commands are handled natively, and anything unsupported transparently falls back to the managed CLI. To opt out and route every invocation to the managed CLI, set [`DOTNET_CLI_ENABLEAOT`](../../../tools/dotnet-environment-variables.md#dotnet_cli_enableaot) to a falsy value: `false`, `0`, `no`, or `off`. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Now that the native command-handling path has reached parity with the managed CLI, enabling it by default provides broad real-world testing and improves CLI startup performance for common commands. + +## Recommended action + +The native path is designed to be behaviorally identical to the managed CLI and should require no action. If you observe a difference in behavior, set the environment variable [`DOTNET_CLI_ENABLEAOT=false`](../../../tools/dotnet-environment-variables.md#dotnet_cli_enableaot) (or `0`, `no`, or `off`) to opt out and route all invocations to the managed CLI. Report the difference at . + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index aee280b97e29f..c23092eb7cf5a 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -78,6 +78,8 @@ items: href: sdk/11/dnx-scripts-bypass-global-json.md - name: mono launch target not set for .NET Framework apps href: sdk/11/mono-launch-target-removed.md + - name: NativeAOT CLI command handling enabled by default + href: sdk/11/native-cli-command-handling-enabled.md - name: NU1703 warns for packages that use deprecated MonoAndroid framework assets href: sdk/11/nu1703-deprecated-monoandroid-framework.md - name: NuGet pack warns for package IDs with restricted characters