How to Create Multi-Stage Dockerfile for .NET Core

Hey there, fellow developers! If you’re working with .NET Core and Docker, you’ve probably wondered how to make your containerized apps leaner, faster, and more secure. I know I did when I first started playing around with Docker a few years back. One game-changer I stumbled upon? Multi-stage Dockerfiles. They’re like the secret sauce for taking your .NET Core app from a messy build process to a smooth, efficient runtime. Let me walk you through what I’ve learned and show you how to craft one yourself.

Why Multi-stage Dockerfiles?

Picture this: you’ve got a .NET Core app — maybe a little API or a web app—and you want to containerize it. You could just shove everything into a single Dockerfile, but then you’re hauling around the whole .NET SDK, build tools, and a bunch of stuff you don’t need when the app actually runs. It’s like packing your entire toolbox for a trip when all you need is a screwdriver.

Multi-stage Dockerfiles split the process into—you guessed it—stages. One stage handles the heavy lifting of building your app, and another takes just the finished product and runs it. The result? Smaller images, less bloat, and a happier deployment pipeline. Plus, it’s a chance to flex some Docker skills and feel like a bit of a wizard.

Let’s Build One

Alright, enough talk—let’s get our hands dirty. Here’s a real-world example of a multi-stage Dockerfile for a .NET Core app. I’ll break it down as we go.

# Stage 1: Build environment
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

# Copy csproj and restore dependencies
COPY *.csproj ./
RUN dotnet restore

# Copy the rest of the code
COPY . ./
RUN dotnet build -c Release --no-restore

# Publish the app
RUN dotnet publish -c Release -o /app --no-restore

# Stage 2: Runtime environment
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app

# Add a non-root user for security
RUN useradd -m -r -u 1000 appuser

# Copy the published files
COPY --from=build /app ./

# Set ownership
RUN chown -R appuser:appuser /app

# Switch to non-root user
USER appuser

# Expose the port
EXPOSE 8080

# Set the entry point
ENTRYPOINT ["dotnet", "YourAppName.dll"]

Stage 1: The Build

The first part—labeled build — is where all the magic happens. We start with the .NET SDK image (mcr.microsoft.com/dotnet/sdk:8.0). It’s got everything we need to compile our code: the SDK, tools, the works. I set the working directory to /src just to keep things tidy.

First, I copy over the .csproj file and run dotnet restore. Why just the project file? It’s a trick I picked up — Docker caches layers, so if your dependencies haven’t changed, it skips the restore step on the next build. Saves a ton of time.

Then, I bring in the rest of the code with COPY . ./ and run dotnet build. The --no-restore flag tells it we already handled dependencies. Finally, dotnet publish spits out the compiled app into an /app folder. That’s our golden ticket for the next stage.

Stage 2: The Runtime

Now, we switch gears. The runtime stage uses a slimmer image: mcr.microsoft.com/dotnet/aspnet:8.0. This one’s just the ASP.NET runtime — no SDK, no extra baggage. I set the working directory to /app because that’s where we’re going to live.

Security’s a big deal, so I add a non-root user called appuser. Running as root in a container is like leaving your front door unlocked—not a great idea. Then, I grab the published files from the build stage with COPY --from=build /app ./. A quick chown hands ownership to appuser, and USER appuser makes sure we’re not running as root.

I expose port 8080 (you can change this if your app uses something else), and the ENTRYPOINT fires up the app with dotnet YourAppName.dll. Make sure to swap in your actual DLL name here!

Running It

To see it in action, pop open a terminal in your project folder and run:

docker build -t mycoolapp .
docker run -p 8080:8080 mycoolapp

Hit http://localhost:8080 in your browser, and boom—your app’s live. The first time I got this working, I felt like I’d cracked some secret code. It’s a good day when that happens.
Why It’s Worth It

So, what’s the payoff? For one, the final image is tiny compared to a single-stage build. You’re not dragging along the SDK or build tools—just the runtime and your app. It’s also more secure with that non-root user. And because of Docker’s caching, tweaking your code doesn’t mean rebuilding everything from scratch.

I’ve used this setup for a bunch of projects now, and it’s saved me headaches in production. Smaller images mean faster deploys, and the consistency of Docker means I’m not wrestling with “works on my machine” issues.

Tweaks and Tips

This is a solid starting point, but you can tweak it to fit your needs. Need a health check? Toss in:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:8080/health || exit 1

Got some persistent data? Add a volume:

VOLUME /app/data

And if you’re targeting multiple architectures, tweak the FROM line with --platform=$BUILDPLATFORM. Little adjustments like these can go a long way.

Wrapping Up

Multi-stage Dockerfiles have become my go-to for .NET Core apps. They take a bit of setup, but once you’ve got the hang of it, it’s smooth sailing. You get a leaner, meaner container that’s ready to roll from build to runtime. Give it a shot on your next project — I bet you’ll wonder how you ever got by without it.

Happy coding, folks! Let me know in the comments if you’ve got any tricks of your own — I’m always up for learning something new.