diff --git a/docs/core/compatibility/10.md b/docs/core/compatibility/10.md index e3705fdec883e..e8433d0e82b72 100644 --- a/docs/core/compatibility/10.md +++ b/docs/core/compatibility/10.md @@ -121,6 +121,7 @@ See [Breaking changes in EF Core 10](/ef/core/what-is-new/ef-core-10.0/breaking- | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | | [`DefineConstants` for target frameworks not available at evaluation time](sdk/10.0/defineconstants-not-available-at-evaluation.md) | Behavioral change | | [Code coverage EnableDynamicNativeInstrumentation defaults to false](sdk/10.0/code-coverage-dynamic-native-instrumentation.md) | Behavioral change | +| [dnx scripts bypass global.json SDK selection](sdk/10.0/dnx-scripts-bypass-global-json.md) | Behavioral change | | [dnx.ps1 file is no longer included in .NET SDK](sdk/10.0/dnx-ps1-removed.md) | Source incompatible | | [Double quotes in file-level directives are disallowed](sdk/10.0/file-level-directive-double-quotes.md) | Source incompatible | | [`dotnet new sln` defaults to SLNX file format](sdk/10.0/dotnet-new-sln-slnx-default.md) | Behavioral change | diff --git a/docs/core/compatibility/sdk/10.0/dnx-scripts-bypass-global-json.md b/docs/core/compatibility/sdk/10.0/dnx-scripts-bypass-global-json.md new file mode 100644 index 0000000000000..762fa4dfe4d45 --- /dev/null +++ b/docs/core/compatibility/sdk/10.0/dnx-scripts-bypass-global-json.md @@ -0,0 +1,42 @@ +--- +title: "Breaking change: dnx scripts bypass global.json SDK selection" +description: "Learn about the breaking change in .NET 10 SDK 10.0.302 where the dnx and dnx.cmd scripts no longer respect global.json for SDK selection." +ms.date: 07/05/2026 +ai-usage: ai-assisted +--- + +# dnx scripts bypass global.json SDK selection + +The `dnx` and `dnx.cmd` scripts no longer use the .NET muxer to select the SDK version. Instead, they find the newest installed SDK and invoke it directly, which bypasses any `global.json` file in the working directory. + +## Version introduced + +.NET 10 SDK 10.0.302, 10.0.400, and .NET 11 Preview 6 + +## Previous behavior + +Previously, the `dnx` scripts invoked `dotnet dnx`, which relied on the .NET muxer to select the SDK version based on any `global.json` file in the working directory. If `global.json` pinned an SDK version that predated .NET 10, the scripts failed with the following error: + +```output +Unrecognized command or argument 'execute' +``` + +## New behavior + +Starting in .NET 10 SDK 10.0.302, the `dnx` and `dnx.cmd` scripts use `dotnet --list-sdks` to identify the newest installed SDK. They then invoke `dotnet exec /dotnet.dll dnx` directly, bypassing the .NET muxer and any `global.json` SDK pinning. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Some .NET CLI commands, including `dnx`, are considered version-independent features that should always run with the newest installed SDK. Relying on `global.json` meant that users who pinned an older SDK version to reduce risk from build-impacting changes also inadvertently broke `dnx`. In folders where a pre-.NET 10 SDK was pinned, the `dnx` command was unavailable, which caused confusing errors and, in some cases, timeouts in tools like Copilot CLI. + +## Recommended action + +Run `dotnet dnx` explicitly instead of the `dnx` script to restore the previous behavior where the .NET muxer and `global.json` control SDK selection. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 1395fa691738d..b6115ab412e8d 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -194,6 +194,8 @@ items: href: sdk/10.0/dotnet-cli-stderr-output.md - name: .NET tool packaging creates RuntimeIdentifier-specific tool packages href: sdk/10.0/dotnet-tool-pack-publish.md + - name: dnx scripts bypass global.json SDK selection + href: sdk/10.0/dnx-scripts-bypass-global-json.md - name: dnx.ps1 file is no longer included in .NET SDK href: sdk/10.0/dnx-ps1-removed.md - name: Double quotes in file-level directives are disallowed diff --git a/docs/core/tools/dotnet-tool-exec.md b/docs/core/tools/dotnet-tool-exec.md index 173958aa876d6..9b4ddba3e90eb 100644 --- a/docs/core/tools/dotnet-tool-exec.md +++ b/docs/core/tools/dotnet-tool-exec.md @@ -41,7 +41,7 @@ When you run `dotnet tool exec`, the command: This command also exists in two other forms for easier use * `dotnet dnx` - A hidden alias for `dotnet tool exec` that is used as a way to easily implement the `dnx` script itself -* `dnx` - A shell script that invokes `dotnet dnx` from the SDK. This script is provided by the installer and is available on `PATH`. It allows for very simple use of tools directly via `dnx `. +* `dnx` - A shell script provided by the installer and available on `PATH`. It allows for very simple use of tools directly via `dnx `. Starting in .NET 10 SDK 10.0.302, the script bypasses the .NET muxer and any `global.json` SDK pinning—it finds the newest installed SDK using `dotnet --list-sdks` and invokes it directly. To use `global.json` SDK selection instead, run `dotnet dnx` explicitly. ## Arguments