Multi-Stage Builds

Look at what a single-stage image actually contains: the .NET SDK, the C# compiler, your source code, the NuGet package cache, and the compiled application. Only the last of those runs in production.

A multi-stage build separates the two jobs. One stage compiles, using an image that has the tooling. A second stage starts from a small runtime image, copies the compiled output across, and becomes the image you ship. Everything left in the first stage is discarded.

This is the largest single reduction in image size available to you, and it costs a handful of extra lines.

# syntax=docker/dockerfile:1

# ---------- build stage ----------
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src

COPY EmployeesApi.csproj ./
RUN dotnet restore

COPY . ./
RUN dotnet publish -c Release -o /app/publish --no-restore

# ---------- runtime stage ----------
FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app

# The only thing that crosses the boundary
COPY --from=build /app/publish ./

ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
USER $APP_UID

ENTRYPOINT ["dotnet", "EmployeesApi.dll"]

• AS build names the first stage so later instructions can refer to it. The name is yours to choose.
• The build stage is the ordering from the previous lesson, unchanged. Caching still works the same way within a stage.
• The second FROM begins a new image from scratch. Nothing from the build stage exists here — not the source, not the SDK, not the package cache.
• COPY --from=build reaches into the finished build stage and takes one directory. The path is a path inside that stage, so it has to match where publish wrote its output.
• The aspnet image contains the ASP.NET Core runtime and no compiler. It can run the application and cannot build one, which is the point.
• The official .NET runtime images define APP_UID as a ready-made non-root account, so USER $APP_UID switches to it without creating a user first.
• ENTRYPOINT is relative to WORKDIR now, so the path is shorter than in the single-stage version.

Those sizes are indicative. They depend on the base images you pick, your dependencies and the platform, and they change as Microsoft publishes new images. Measure your own with docker images. The ratio is the durable part: shipping a build environment roughly quadruples what you deploy.

Smaller options exist below this. Alpine-based runtime images cut further, and self-contained or trimmed publishes on a runtime-dependencies base go smaller still. Each trades something away — a different C library, no shell for debugging, occasional trouble with native dependencies or reflection-heavy libraries. The SDK-to-runtime split is the change worth making first, because it is large and carries almost no risk.