Hi, I want to ask about version confusion!

Question

In this doc https://learn.microsoft.com/en-us/dotnet/core/docker/build-container?tabs=linux&pivots=dotnet-10-0,
I noticed that the version in the chosen tab is .NET 10 but in the example using .NET9
Is it a mistake or on purpose?
Thank you

Answer 1

Hi @Phung Thai Bao 20227189

Thank you for reaching out to Microsoft Q&A.

The version difference you’re seeing in the Containerize an app with Docker tutorial is intentional and not a documentation mistake. While the selected tab and prerequisites mention .NET 10, the actual sample project and Dockerfile are built targeting .NET 9. The tab selection indicates which SDK versions are supported to run the tutorial, but the example deliberately uses a stable, widely supported runtime version. The documentation also emphasizes that the Docker base image must match the target framework of the application, which is why net9.0 and .NET 9 container images are consistently used in the example. This approach ensures reliability and avoids runtime compatibility issues for users following the tutorial as-is.

Refer below points to resolve this issue or as a workaround:

This is expected behavior, not a bug The tutorial supports multiple SDK versions (8, 9, 10+), but the sample application itself is intentionally created with net9.0 to ensure consistency and stability.

• Docker base image must match the app’s target framework If the app is targeting net9.0, the Dockerfile must use: FROM mcr.microsoft.com/dotnet/sdk:9.0 FROM mcr.microsoft.com/dotnet/aspnet:9.0 Mismatching the TFM and runtime image (for example, net10.0 with aspnet:9.0) will lead to runtime failures.
• If you want to use .NET 10 explicitly, update everything together
  • Update the project file

        <TargetFramework>net10.0</TargetFramework>
    

  • Accept that the publish path changes to:

        bin/Release/net10.0/publish
    

  • Update the Dockerfile images:

        FROM mcr.microsoft.com/dotnet/sdk:10.0
        FROM mcr.microsoft.com/dotnet/aspnet:10.0\
        
    

Answer 2

In the .NET 10 containerization article, the Dockerfile example still shows mcr.microsoft.com/dotnet/aspnet:9.0 because that section is reused across the .NET 8, 9, and 10 pivots and has not been updated to a 10.0 tag. The text explicitly states that the example demonstrates pulling an ASP.NET Core 9.0 image:

FROM mcr.microsoft.com/dotnet/aspnet:9.0

For .NET 10, the FROM statement should be updated to use the 10.0 tag when targeting .NET 10, for example:

FROM mcr.microsoft.com/dotnet/aspnet:10.0

This aligns with the guidance that when upgrading to a new .NET version, FROM statements must be changed to include the new version number. The use of 9.0 in a .NET 10 pivot is therefore an inconsistency in the documentation rather than intentional versioning guidance.

---

References:

• Tutorial: Containerize a .NET app (dotnet-10-0)
• Upgrade to a new .NET version
• Default .NET images use Ubuntu