Description

The .NET 8 multi-platform container tags have been updated to be Linux-only. This means that the latest, <major>.<minor>, and <major>.<minor>.<patch> tags will be Linux-only going forward.

Multi-platform tags, also known as multi-arch or manifest list tags, are dynamic tags that cause the appropriate image to be retrieved based on the context of the host system. For example, if you pull an image with a multi-platform tag from a Linux Arm64 machine, you'll get an Arm64 image (if the tag supports that).

For more background on this change, you can read the original proposal.

Version

.NET 8 Preview 3

Previous behavior

In previous versions of .NET, users could reference a tag like 7.0 and be able to retrieve a Windows-based container image.

New behavior

In .NET 8, the 8.0 tag will only retrieve a Linux-based image.

Type of breaking change

• Binary incompatible: Existing binaries may 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 may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

This change was made because of usability issues related to the platform matching algorithm for containerd when used in conjunction with Windows desktop OS versions. This aligns .NET's Windows container images with the method of tagging that is used for the actual base Windows Server container images. Read more details in the original proposal for this change.

Recommended action

Users will need to update their tag usage to indicate which Windows version they are targeting.

In the examples below the 8.0 tag prefix is being used which is the value that will exist once .NET 8 ships. While .NET 8 is still in preview, however, users can replace 8.0 with 8.0-preview instead.

Instead of using an image name like mcr.microsoft.com/dotnet/aspnet:8.0, users will now need to use something like one of the following:

• mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-1809
• mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022
• mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2019
• mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022

The one selected here would be based on whether you're using Nano Server or Windows Server Core and which version of that OS. A full list of all supported tags can be found on .NET's Docker Hub page.

Feature area

Deployment

Affected APIs

No response

Associated WorkItem - 118222