.NET and Docker

Analogy categoryAnalogies

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

# 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.