latest tag doesn't reference the latest version of .NET and doesn't include any 2025 Windows images

[MichaelSimons]

Currently the latest tag points to the .NET 4.8 image and includes all Windows versions where there is a 4.8 image (2026, 2019, and 2022).

The tag policy documentation states that latest "references the most recent .NET version."

[lbussell]

Thanks for filing this issue Michael Simons (@MichaelSimons).

I think we should move the latest tag to 4.8.1 for Windows versions that support it.

Then the question is what do we do about Windows versions that don't support 4.8.1 (Server 2016 and 2019)? We could either remove them from the manifest list or leave them pointing at 4.8.

.NET Framework 4.8.1 doesn't contain any breaking changes from 4.8 [source]:

No breaking changes or other changes in behavior which is expected to impact application compatibility are included as a part of .NET Framework 4.8.1

Given the high compatibility of .NET Framework 4.8 and 4.8.1 I think it'd be safe to leave them pointing at 4.8. I think that both of those options fit within the spirit of the tagging policy. But we should clarify the policy after we make a decision.

Windows Server / .NET Framework version compatibility for reference: https://learn.microsoft.com/en-us/dotnet/framework/get-started/system-requirements#server-operating-systems

[mthalman]

Given the high compatibility of .NET Framework 4.8 and 4.8.1 I think it'd be safe to leave them pointing at 4.8.

In other words...

latest manifest list tag:

• WS 2016 points to 4.8 image
• WS 2019 points to 4.8 image
• WS 2022 points to 4.8.1 image
• WS 2025 points to 4.8.1 image

I think that the manifest.json file would be able to express this.

[lbussell]

Given the high compatibility of .NET Framework 4.8 and 4.8.1 I think it'd be safe to leave them pointing at 4.8.

In other words...

latest manifest list tag:

• WS 2016 points to 4.8 image
• WS 2019 points to 4.8 image
• WS 2022 points to 4.8.1 image
• WS 2025 points to 4.8.1 image

I think that the manifest.json file would be able to express this.

Correct.

And just to be crystal clear, I think the most literal interpretation of the tag policy is still correct (it should be the latest version). The only reason we'd consider making an exception is because the tag wasn't moved when 4.8.1 was released in 2022, and because of the compatibility/non-breaking nature of the update.

We could change the policy to "latest version per OS" but that could be confusing for users.

[lbussell]

[Triage] The discussion in triage settled on clarifying the policy to "The latest tag points to the latest .NET Framework version for the given OS". The justification is that the latest tag is rarely used. If the change causes any confusion or undesired behavior, users should use the versioned tags.

[lbussell]

This doesn't play nice with our infrastructure:

---> Microsoft.DotNet.ImageBuilder.ValidationException: Duplicate tags found: 
latest

The only way around that would be to define all "latest" versions in one "image" in the manifest. That'd mean shoving additional 4.8 versions into this image:

dotnet-framework-docker/manifest.json

Lines 31 to 58 in 2a1a5aa

	{
	"productVersion": "4.8.1",
	"sharedTags": {
	"4.8.1": {}
	},
	"platforms": [
	{
	"dockerfile": "src/runtime/4.8.1/windowsservercore-ltsc2022",
	"dockerfileTemplate": "eng/dockerfile-templates/runtime/Dockerfile",
	"os": "windows",
	"osVersion": "windowsservercore-ltsc2022",
	"tags": {
	"4.8.1-$(4.8.1-ltsc2022-Runtime-DateStamp)-windowsservercore-ltsc2022": {},
	"4.8.1-windowsservercore-ltsc2022": {}
	}
	},
	{
	"dockerfile": "src/runtime/4.8.1/windowsservercore-ltsc2025",
	"dockerfileTemplate": "eng/dockerfile-templates/runtime/Dockerfile",
	"os": "windows",
	"osVersion": "windowsservercore-ltsc2025",
	"tags": {
	"4.8.1-$(4.8.1-ltsc2025-Runtime-DateStamp)-windowsservercore-ltsc2025": {},
	"4.8.1-windowsservercore-ltsc2025": {}
	}
	}
	]
	},

Things will probably get weird if we start defining images twice and I'm also not sure if there are any testing side effects from the productVersion being 4.8.1 on that collection of platforms.

Was there a different way you were thinking about implementing this Matt Thalman (@mthalman)?

[mthalman]

I concede that the productVersion field is an issue since there's no single product version that applies to all of these Dockerfiles.

For the duplicate tags issue, it is important to not list simple tags more than once. That's ok. This scenario is analogous to what we did in dotnet-docker with the 6.0 and 6.0-bullseye-slim tags. In that configuration, 6.0 was its own manifest list tag that included both Bullseye and NanoServer images. A separate manifest list tag was defined for 6.0-bullseye-slim which included the same Bullseye Dockerfiles as the 6.0 tag. Here's what that looked like.

6.0:
https://github.com/dotnet/dotnet-docker/blob/fbfe62fa425b7127f41d086a5f2f7d26cf62a203/manifest.json#L2297-L2368

6.0-bullseye-slim: https://github.com/dotnet/dotnet-docker/blob/fbfe62fa425b7127f41d086a5f2f7d26cf62a203/manifest.json#L2369-L2412

You'll notice that the simple tags within 6.0-bullseye-slim are left empty, because those tags had already been defined as part of the 6.0 definition:

"tags": {}

The same would be done here. 6.0 is equivalent to latest here and 6.0-bullseye-slim is equivalent to 4.8 and 4.8.1. I did try this and it is running into an error in readme generation:

Unhandled exception: System.InvalidOperationException: The following tags are not included in the tags metadata:
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2022 AMD64
Missing Tags: 4.8.1
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2025 AMD64
Missing Tags: 4.8.1
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2016 AMD64
Missing Tags: 4.8
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2019 AMD64
Missing Tags: 4.8

It looks like there may be an issue there specific to the scenario of Windows versions.

So this scenario isn't way outside the intended support for Image Builder or anything. But again, the productVersion field is a bit of an issue that will take some investigation.

[lbussell]

Unhandled exception: System.InvalidOperationException: The following tags are not included in the tags metadata:
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2022 AMD64
Missing Tags: 4.8.1
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2025 AMD64
Missing Tags: 4.8.1
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2016 AMD64
Missing Tags: 4.8
Repo: dotnet/framework/runtime, Platform: Windows Server Core 2019 AMD64
Missing Tags: 4.8

Yeah, I think this is an ImageBuilder bug. It probably isn't combining the two platforms across images.