Why Containerize .NET Applications
Containerizing a .NET app packages the application, its runtime, and its dependencies into a single portable image that runs identically on a developer's laptop, a CI runner, and production, eliminating 'works on my machine' drift. Microsoft publishes official base images under mcr.microsoft.com/dotnet — sdk for building, aspnet for running ASP.NET Core apps, and runtime for running other .NET apps — versioned by .NET release (e.g. mcr.microsoft.com/dotnet/aspnet:8.0), so teams pin a specific, reproducible runtime version rather than whatever happens to be installed on a host.
Cricket analogy: A Docker image is like a standardized, pre-packed cricket kit bag issued to every touring player — bat, pads, gloves, all specified to exact team regulations — so a player performs identically whether playing in Mumbai or Melbourne, with no dependence on local equipment.
Writing a Dockerfile for .NET
A well-formed .NET Dockerfile uses a multi-stage build: an early stage based on the larger sdk image compiles and publishes the app, while the final stage copies only the published output onto a much smaller aspnet or runtime image, keeping the shipped image lean since the SDK's compilers and build tooling never make it into the runtime layer. Ordering COPY *.csproj and dotnet restore before copying the rest of the source code lets Docker's layer cache skip the (often slow) restore step on rebuilds where only application code, not dependencies, changed.
Cricket analogy: Multi-stage builds discarding the SDK stage are like a franchise's extensive pre-season training camp (build stage) producing a fit, ready player who then travels to the actual match (final image) without dragging the entire gym and coaching staff along.
Choosing the Right Base Image
The aspnet image is for ASP.NET Core web apps and APIs; the smaller runtime image suits console apps, workers, or any app that doesn't need ASP.NET Core's hosting libraries; and runtime-deps is the leanest option, providing only native OS dependencies for apps published self-contained. Alpine-based tags (e.g. aspnet:8.0-alpine) shrink the image further using musl libc instead of glibc, which is worth the (usually minor) compatibility risk when image size and pull time genuinely matter, such as in high-scale Kubernetes deployments.
Cricket analogy: Choosing runtime-deps over the full runtime image is like a specialist death-overs bowler being selected for exactly the skill needed rather than carrying an all-rounder's full kit bag onto the field when only one specific tool is required.
Container Orchestration and Configuration
Runtime configuration in containers typically flows through environment variables — ASPNETCORE_ENVIRONMENT=Production, ASPNETCORE_URLS=http://+:8080, or custom ConnectionStrings__Default values that Microsoft.Extensions.Configuration's environment provider automatically maps using the double-underscore convention for nested keys. Since .NET 8, the SDK also supports building container images directly without a Dockerfile via dotnet publish /t:PublishContainer, using the SDK's built-in containerization support, which is convenient for simple apps though a hand-written Dockerfile still offers more control for multi-stage optimizations or non-standard base images.
Cricket analogy: Environment variables configuring a container at runtime are like team lineup changes submitted right before the toss — the core squad (image) is fixed, but final adjustments (Production vs Staging environment, connection strings) are set fresh for each specific match.
# Dockerfile - multi-stage build for an ASP.NET Core API
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MyApi/MyApi.csproj", "MyApi/"]
RUN dotnet restore "MyApi/MyApi.csproj"
COPY . .
WORKDIR /src/MyApi
RUN dotnet publish -c Release -o /app/publish --no-restore
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app
RUN adduser --disabled-password --gecos "" appuser
USER appuser
COPY --from=build /app/publish .
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
ENTRYPOINT ["dotnet", "MyApi.dll"]
Since .NET 8, dotnet publish -r linux-x64 /t:PublishContainer -p:ContainerImageTag=1.0.0 builds and can push a container image directly from the SDK, no Dockerfile required — handy for simple services, but a hand-authored multi-stage Dockerfile remains the better choice when you need custom layer ordering, non-default base images, or extra build steps.
Running a container process as root (the default if you don't set a USER) is a real security risk — if the app is compromised, the attacker inherits root inside the container, which can be a stepping stone to host-level compromise via kernel or runtime vulnerabilities. Always create and switch to a non-root user in the final stage, as shown above with adduser and USER appuser.
- Microsoft's official images (mcr.microsoft.com/dotnet/sdk, aspnet, runtime) are versioned per .NET release for reproducible builds.
- Multi-stage Dockerfiles build with the larger sdk image but ship only the published output on a smaller aspnet or runtime image.
- Copying the .csproj and running dotnet restore before copying the rest of the source lets Docker cache the restore layer across rebuilds.
- runtime-deps is the leanest base image, suited to self-contained published apps; Alpine tags shrink images further using musl libc.
- Runtime configuration flows through environment variables, with double underscores mapping to nested configuration keys.
- dotnet publish /t:PublishContainer builds a container image directly from the SDK without requiring a Dockerfile.
- Always run the container process as a non-root user in the final image stage for basic container security hygiene.
Practice what you learned
1. What is the main purpose of a multi-stage Dockerfile for a .NET app?
2. Why copy only the .csproj file and run dotnet restore before copying the rest of the source code?
3. Which base image is most appropriate for a self-contained published console worker with no ASP.NET Core dependency?
4. What does dotnet publish /t:PublishContainer do, available since .NET 8?
5. Why should a .NET container's final stage switch to a non-root user?
Was this page helpful?
You May Also Like
Worker Services
Learn how to build long-running background processes in .NET using the Worker Service template, BackgroundService, and the generic host.
Self-Contained Deployments
Understand the difference between framework-dependent and self-contained .NET deployments, and how to publish, trim, and single-file your apps for target machines without a shared runtime.
Console Apps in .NET
Learn how .NET console applications are structured, how they read input and produce output, and how they're built and published as standalone command-line tools.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics