Docker for .NET Developers: Multi-Stage Dockerfile Guide

A container isn't a tiny virtual machine. It's your app, wrapped just tightly enough to carry its own dependencies with it — while still sharing the same kernel as everything around it.

"It works on my machine." Every developer has said it, and every developer has watched it fail to be reassuring. The app runs fine locally, then breaks in staging because staging has a different .NET runtime patch version, or a missing native library, or an environment variable nobody documented. Lesson 297 talked about keeping configuration separate from the build so the same artifact runs everywhere — but that only works if "the same artifact" also carries the same runtime and dependencies with it, everywhere it goes.

That's the problem containers solve. Not by virtualizing an entire computer — that's what a virtual machine does, and it's heavier than this needs to be — but by packaging your app together with exactly the runtime and dependencies it needs, in a form that runs identically on a laptop, in a CI pipeline, and in production.

In this lesson, you'll learn precisely what a container is (and precisely how it differs from a VM), why that distinction matters for .NET deployment specifically, and how to write a correct, efficient, multi-stage Dockerfile for a .NET application.

What Is It?

The Simple Explanation

A container is your application, plus everything it needs to run — the .NET runtime, libraries, config defaults — bundled together into one package that behaves the same way no matter what machine it's started on.

The Technical Definition

A container is a lightweight, isolated process running on a host machine. It has its own filesystem view, its own network interface, and its own set of installed dependencies — all isolated from other containers and from the host — but it runs as an ordinary process using the host operating system's own kernel. This last part is the single most important, and most commonly misunderstood, fact about containers, and it's worth stating precisely before going any further.

Why Does It Exist?

The Problem — "The Machine" Is Never Really the Same Twice

Before containers, deploying a .NET app meant hoping the target machine already had the right .NET runtime version installed, the right native libraries, the right OS patches, and no conflicting software fighting for the same resources. A developer's laptop, a CI runner, and a production server are, in practice, three different "machines" — three different opportunities for "works here, breaks there."

The Solution — Package the Relevant Parts of "The Machine" With the App

A container packages the runtime, the dependencies, and the app's own configuration defaults together, so "the machine" the app actually runs on is defined by the container image, not by whatever happens to be installed on the host. The same container image runs identically on the developer's laptop, in the CI pipeline, and in production — because in every one of those cases, it's genuinely running the same bundled runtime and dependencies, just on top of a different host kernel underneath.

Big Picture

Notice what's missing from the container stack: there's no per-container guest OS. Every container on a host shares that one host kernel underneath it. That's the entire source of the weight difference — a VM's guest OS has to boot, allocate its own memory for OS-level bookkeeping, and run its own kernel processes; a container just starts as a regular, isolated process on a kernel that's already running.

How It Works — The Multi-Stage Dockerfile Pattern

A Dockerfile is a script of instructions describing how to build a container image. For .NET apps, the real, standard, Microsoft-recommended pattern is a multi-stage build: one stage does the compiling, using the full SDK; a second, separate stage runs the compiled output, using only a lightweight runtime image. Only the compiled output crosses from the first stage into the second.

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build

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

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

COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Simple Example — A Complete Multi-Stage Dockerfile

Putting the whole pattern together for a simple web API:

Meaning: Building this Dockerfile produces one final image, based on the small aspnet runtime, containing nothing but the published app. The entire SDK — everything used in Stage 1 — never appears in that final image at all; Docker simply discards Stage 1's filesystem once COPY --from=build has pulled out the one directory it needed.

Real-World Example

A team building an order-processing API containerizes it with exactly this pattern. Their CI pipeline runs docker build on every commit to main, producing one image tagged with the commit SHA. That image — built once, with the multi-stage pattern keeping it small — gets pushed to a container registry and is the same image that later gets deployed to staging, then promoted unmodified to production (exactly the Twelve-Factor build-once, promote-everywhere flow from Lesson 297). Because the image only carries the ASP.NET runtime and the app's own DLLs, it pulls quickly on every deploy and gives an attacker who somehow got shell access far less to work with than a full SDK image would.

Analogy

Under the Hood — Image Layers and the Build Cache

A container image isn't one monolithic blob — it's a stack of layers, one per Dockerfile instruction that changes the filesystem (COPY, RUN, etc.). Docker caches each layer, and if a given instruction and everything before it are unchanged since the last build, Docker reuses the cached layer instead of re-running that instruction.

This is exactly why the example Dockerfile above copies only the .csproj file and runs dotnet restore before copying the rest of the source code:

This ordering trick doesn't change what the final image contains — it only changes how much unnecessary work Docker redoes on every build. For a project with many NuGet dependencies, this is often the difference between a build that takes seconds and one that takes minutes, every single time.

Common Confusion

1. "A container is just a lightweight VM" — no, it's a different mechanism entirely

This phrase gets repeated so often it's worth actively unlearning. A VM virtualizes hardware and runs a genuinely separate guest kernel; a container is an isolated process sharing the host's one kernel. The word "lightweight" is doing a lot of hiding here — it's not just a smaller VM, it's a fundamentally different isolation mechanism, which is why it's so much lighter.

2. "The SDK image and the runtime image are just different sizes of the same thing" — no, they serve different jobs entirely

The SDK image is a build tool — it exists to compile and publish. The aspnet/runtime images are execution environments — they exist only to run already-compiled code. Using the SDK image for your final, deployed container isn't just "wasting some disk space" — it means shipping compiler and build tooling into a production environment that will never legitimately use it.

Common Mistakes

Mistake 1 — Using a single-stage Dockerfile based on the SDK image

FROM mcr.microsoft.com/dotnet/sdk:10.0 as the only stage, with the app run directly from it — simple to write, but ships the entire build toolchain into production. Always use the two-stage pattern: build with the SDK, run from aspnet or runtime.

Mistake 2 — Copying all source before restoring dependencies

COPY . . followed by RUN dotnet restore means the restore layer gets invalidated on every source change, even trivial ones. Copy the .csproj alone, restore, then copy the rest of the source — as shown in the Simple Example above.

Mistake 3 — Reaching for a VM out of habit when a container would do

Provisioning a full VM per service because "that's how deployment has always worked" — when the workload is just "run this .NET app," a full guest kernel adds boot time, resource overhead, and operational cost with no corresponding benefit. Use containers for ordinary application workloads; reserve VMs for cases that genuinely need a separate kernel or full OS-level isolation.

When Should I Use It?

• Any .NET web API, worker service, or background service you plan to deploy to a cloud platform or orchestrator — containers are the default deployment unit across this entire Part.
• Use mcr.microsoft.com/dotnet/aspnet as the final-stage base for web apps (ASP.NET Core APIs, MVC apps, Blazor Server), and mcr.microsoft.com/dotnet/runtime for non-web workloads like console apps or worker services that don't need ASP.NET Core at all — it's smaller still.
• A VM (not a container) is still the right tool when a workload genuinely needs a separate kernel, custom OS-level configuration, or the strongest possible isolation boundary between tenants — that's a real, if less common, requirement.

Mental Model

Key Takeaway

Check Your Understanding

You've seen what a container actually is, how it differs from a VM, and how to write a proper multi-stage .NET Dockerfile. Let's check it clicked.

You now understand what a container actually is, how it differs from a VM, and how to build a proper multi-stage Dockerfile for .NET. Next: the ASP.NET-Core-specific details of running well inside one.