From 08f261a5cf5ff448330973aebdfe35a2b0d5322f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:55:00 +0000 Subject: [PATCH 1/2] Initial plan From 820fb1edd7f3cafa2161590315c0765bc3e94587 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:59:13 +0000 Subject: [PATCH 2/2] Document SDK local container runtime selection Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/11.md | 1 + .../sdk/11/native-local-container-runtimes.md | 51 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + docs/core/containers/publish-configuration.md | 15 ++++-- 4 files changed, 64 insertions(+), 5 deletions(-) create mode 100644 docs/core/compatibility/sdk/11/native-local-container-runtimes.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 51b5589505918..554493c010be9 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -102,5 +102,6 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | [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 | +| [SDK local container runtime selection prefers platform-native tools](sdk/11/native-local-container-runtimes.md) | Behavioral change | | [Template engine packages no longer support netstandard2.0](sdk/11/template-engine-netstandard.md) | Binary/source incompatible | | [VSTest removes dependency on Newtonsoft.Json](sdk/11/vstest-removes-newtonsoft-json.md) | Binary/source incompatible | diff --git a/docs/core/compatibility/sdk/11/native-local-container-runtimes.md b/docs/core/compatibility/sdk/11/native-local-container-runtimes.md new file mode 100644 index 0000000000000..8779db9fdefae --- /dev/null +++ b/docs/core/compatibility/sdk/11/native-local-container-runtimes.md @@ -0,0 +1,51 @@ +--- +title: "Breaking change: SDK local container runtime selection prefers platform-native tools" +description: "Learn about the breaking change in .NET 11 where SDK local container runtime selection prefers platform-native tools on Windows and macOS." +ms.date: 08/04/2026 +ai-usage: ai-assisted +--- + +# SDK local container runtime selection prefers platform-native tools + +Starting in .NET 11, when you publish an SDK container to a local container runtime, the SDK automatically prefers platform-native CLIs when they're available: `wslc` on Windows and Apple's `container` CLI on macOS. This change affects which local runtime receives the image when Docker or Podman is also installed. + +## Version introduced + +.NET 11 Preview 7 + +## Previous behavior + +Previously, when `LocalRegistry` wasn't explicitly set, the SDK probed Docker and Podman and loaded the published image into the selected Docker or Podman runtime. + +## New behavior + +Starting in .NET 11, on Windows, the SDK first probes `wslc`. On macOS, the SDK first probes Apple's `container` CLI. If the platform-native tool is available and its service runs, the SDK loads the published image there. Docker and Podman remain fallback options. + +You can explicitly select Docker, Podman, `wslc`, or Apple's `container` CLI through the `LocalRegistry` MSBuild property. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Windows and macOS now provide platform-native container tooling. The SDK gives you the native platform experience while it preserves Docker and Podman fallback behavior. + +For more information, see the [related implementation](https://github.com/dotnet/sdk/pull/55249) and tracking issues [dotnet/sdk-container-builds#651](https://github.com/dotnet/sdk-container-builds/issues/651) and [dotnet/sdk-container-builds#636](https://github.com/dotnet/sdk-container-builds/issues/636). + +## Recommended action + +If automatic selection works for your workflow, no action is required. + +To keep using a specific runtime, set the `LocalRegistry` MSBuild property explicitly: + +```dotnetcli +dotnet publish /t:PublishContainer -p:LocalRegistry=Docker +``` + +Use `Docker` or `Podman` to select Docker or Podman. Use `Wslc` on Windows or `MacOSContainer` on macOS to select the platform-native runtime explicitly. + +## Affected APIs + +- `Microsoft.NET.Build.Containers.KnownLocalRegistryTypes.Wslc` +- `Microsoft.NET.Build.Containers.KnownLocalRegistryTypes.MacOSContainer` diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 0582ff971eadc..55b806dc95f0e 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -86,6 +86,8 @@ items: href: sdk/11/nu1703-deprecated-monoandroid-framework.md - name: NuGet pack warns for package IDs with restricted characters href: sdk/11/nuget-pack-nu5052-packageid.md + - name: SDK local container runtime selection prefers platform-native tools + href: sdk/11/native-local-container-runtimes.md - name: Template engine packages no longer support netstandard2.0 href: sdk/11/template-engine-netstandard.md - name: VSTest removes dependency on Newtonsoft.Json diff --git a/docs/core/containers/publish-configuration.md b/docs/core/containers/publish-configuration.md index 98ba8997b21c3..125af6dd55b87 100644 --- a/docs/core/containers/publish-configuration.md +++ b/docs/core/containers/publish-configuration.md @@ -2,7 +2,8 @@ title: Containerize a .NET app reference description: Reference material for containerizing a .NET app and configuring the container image. ms.topic: reference -ms.date: 05/27/2026 +ms.date: 08/04/2026 +ai-usage: ai-assisted --- # Containerize a .NET app reference @@ -33,7 +34,7 @@ The following MSBuild properties and items are available for container configura | [`ContainerRuntimeIdentifier(s)`](#containerruntimeidentifiers) | The OS and architecture for the container. | | [`ContainerUser`](#containeruser) | The default user the container runs as. | | [`ContainerWorkingDirectory`](#containerworkingdirectory) | The working directory inside the container. | -| [`LocalRegistry`](#localregistry) | The local container tool to use: `docker` or `podman`. | +| [`LocalRegistry`](#localregistry) | The local container tool to use, such as Docker, Podman, `wslc`, or Apple's `container` CLI. | ## Configure container properties @@ -522,18 +523,22 @@ For notes on working with these registries, see the [registry-specific notes](ht ### `LocalRegistry` -The `LocalRegistry` MSBuild property specifies the local container tooling to use when pushing to local sources. Supported values are `docker` and `podman`. If not set, the SDK determines the tool based on availability: +The `LocalRegistry` MSBuild property specifies the local container tooling to use when pushing to local sources. Supported values are `Docker`, `Podman`, `Wslc`, and `MacOSContainer`. +If not set, the SDK determines the tool based on availability. Starting in .NET 11, the SDK prefers platform-native tools before Docker and Podman: + +- On Windows, if `wslc` exists and its service runs, `wslc` is used. +- On macOS, if Apple's `container` CLI exists and its service runs, `container` is used. - If both `docker` and `podman` exist, and `docker` is an alias for `podman`, then `podman` is used. - If only `docker` exists, `docker` is used. - If only `podman` exists, `podman` is used. -- If neither exists, an error is thrown. +- If no supported local tool exists, an error is thrown. To explicitly set the local registry tool, use the following configuration: ```xml - podman + Podman ```