3.3.2.5 Dotnet Runtime Images

.NET runtime images provide the .NET runtime pre-installed on top of an operating system base, used to run compiled .NET applications, with separate SDK and runtime-only variants following the same build-versus-run separation common to other compiled language ecosystems.

SDK Images for Building

The full .NET SDK image includes the compiler and build tooling needed to compile and publish a .NET application, typically used only during the build stage of a multi-stage build.

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

Runtime-Only Images for the Final Container

The smaller runtime image includes only what is needed to execute an already-published .NET application, without the SDK's build tooling.

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Using the ASP.NET-specific runtime image here provides the additional libraries an ASP.NET web application needs beyond the base .NET runtime.

Choosing the Right Runtime Variant

Microsoft publishes several runtime image variants depending on the kind of .NET application being run — a base runtime for console applications, an ASP.NET-specific runtime for web applications — each including exactly the libraries that category of application typically needs.

FROM mcr.microsoft.com/dotnet/runtime:8.0

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

Self-Contained Deployment as an Alternative

.NET also supports publishing a self-contained deployment that bundles the runtime directly into the application's own output, which can then run from a more minimal base image without needing a separate .NET runtime image at all.

dotnet publish -c Release -r linux-x64 --self-contained true

FROM debian:bookworm-slim
COPY --from=build /app /app
ENTRYPOINT ["/app/MyApp"]

Why .NET Runtime Images Matter

The separation between SDK and runtime images, paired with the option of self-contained deployment, gives .NET applications the same flexibility other compiled-language ecosystems have for producing lean final images, while still benefiting from official, well-maintained base images for the more common containerization approach.