[Breaking change]: SDK container publishing prefers platform-native local runtimes

[baronfel]

Description

Starting in .NET 11, SDK container publishing to a local container runtime automatically prefers the platform-native CLI when available: wslc on Windows and container on macOS. This changes which local runtime receives the image when Docker or Podman is also installed.

Related implementation: dotnet/sdk#55249
Tracking issues: dotnet/sdk-container-builds#651 and dotnet/sdk-container-builds#636

Version

.NET 11 Preview 7

Previous behavior

When LocalRegistry was not explicitly set, the SDK probed Docker and Podman and loaded the published image into the selected Docker/Podman runtime.

New behavior

On Windows, the SDK first probes wslc; on macOS, it first probes Apple's container CLI. If the platform-native tool is available and its service is running, the SDK loads the published image there. Docker and Podman remain fallbacks. Users can explicitly select Docker, Podman, Wslc, or Container through the LocalRegistry MSBuild property.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Windows and macOS now provide platform-native container tooling. Preferring those tools gives users the native platform experience while preserving Docker and Podman fallback behavior.

Recommended action

If automatic selection is acceptable, no action is required. To keep using a specific runtime, set the LocalRegistry MSBuild property explicitly, for example -p:LocalRegistry=Docker or -p:LocalRegistry=Podman. Use Wslc or Container to explicitly select the platform-native Windows or macOS runtime.

Feature area

Containers; SDK

Affected APIs

No APIs are removed. Microsoft.NET.Build.Containers.KnownLocalRegistryTypes adds the Wslc and Container constants, and local runtime auto-detection behavior changes.