Dockerize a .NET App with Multi-Stage Builds

By Khimananda Oli | Last reviewed: August 2026

Shipping bloated containers is one of the most common performance and security failures I see in .NET teams transitioning to cloud-native infrastructure. When you Dockerize a .NET app with multi-stage builds, you separate the heavy SDK compilation environment from the lean runtime artifact, often reducing final image size by over 90%. This guide walks through the exact Dockerfile patterns, layer caching strategies, and security hardening steps required for production-grade ASP.NET Core applications in 2026.

How do you write a multi-stage Dockerfile for ASP.NET Core?

The foundation of efficient .NET containerization is understanding that the SDK image (often >900MB) is only needed during compilation. Your production environment requires only the ASP.NET Core Runtime or even just the base .NET Runtime for AOT-compiled apps. Writing an effective Dockerfile means structuring these stages to maximize both security and layer caching.

Optimized Dockerfile structure

This Dockerfile targets .NET 9 in 2026, using Alpine for the smallest possible footprint while maintaining glibc compatibility for most native dependencies. Note the deliberate separation of restore and build steps to leverage Docker’s layer cache.

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:9.0-alpine AS build
WORKDIR /src

# Copy csproj first for better layer caching
COPY ["MyApp.csproj", "."]
RUN dotnet restore "MyApp.csproj"

# Copy everything else and publish
COPY . .
RUN dotnet publish "MyApp.csproj" -c Release -o /app/publish \
    --no-restore \
    -p:PublishTrimmed=true \
    -p:TrimMode=partial

# Stage 2: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine AS final
WORKDIR /app

# Security: Create non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

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

A common mistake is copying all source files before running dotnet restore. Every code change invalidates the restore cache, forcing a full NuGet download. By isolating the project file copy, unchanged dependencies remain cached across builds. For teams managing complex dependency trees, this mirrors the discipline discussed in our guide to build caching in CI pipelines.

Why Alpine matters in 2026

Microsoft now ships official Alpine-based images for both SDK and runtime. These images use musl libc instead of glibc, reducing the base layer by approximately 100MB compared to Debian-based variants. However, if your application depends on native libraries that require glibc (like certain PDF generators or legacy cryptography providers), stick with the standard Debian images or use the new Ubuntu Chiseled images which offer a middle ground between size and compatibility.

Why does image size matter for .NET microservices?

In high-scale Kubernetes environments, image size directly correlates with deployment velocity, cold start latency, and storage costs. When orchestrating hundreds of pods across clusters like those described in our Kubernetes resource management guide, every megabyte compounds into significant operational overhead.

Beyond raw performance, smaller images reduce your compliance scope. SOC 2 and ISO 27001 auditors scrutinize unnecessary software in production containers because each additional package represents a potential vulnerability vector. Removing the SDK eliminates hundreds of CVE-prone components that have no business existing in a runtime environment.

How do you secure a .NET container for production compliance?

Security in containerized .NET applications extends beyond the multi-stage pattern itself. In regulated environments, I enforce three non-negotiable controls: non-root execution, read-only filesystems, and explicit user identity mapping.

• Non-root user: Always create and switch to a dedicated user. Running as root inside a container grants unnecessary privileges that can be exploited during container escape attacks.
• Read-only root filesystem: Configure your orchestrator to mount the root FS as read-only. Applications should write only to explicitly mounted temporary volumes.
• No shell in production: Use Chiseled or distroless images when possible. The absence of /bin/sh eliminates an entire class of post-exploitation tooling.
• Explicit port declaration: Document exposed ports via EXPOSE. While not enforcing behavior, it serves as critical documentation for network policy generation.

For teams handling sensitive data, integrating secrets management at the container level is essential. Never bake connection strings or API keys into image layers. Instead, inject them at runtime through environment variables or mounted secret files, following patterns outlined in our Kubernetes secrets management guide.

Handling globalization and timezone data

Alpine images strip ICU libraries and timezone databases by default to save space. If your application performs culture-sensitive formatting or date arithmetic, you must either install these packages explicitly or set the DOTNET_SYSTEM_GLOBALIZATION_INVARIANT environment variable to true for invariant mode. Be aware that invariant mode disables locale-specific sorting and formatting, which may break business logic in Nepali or other non-Latin contexts.

What are the trade-offs between trimming, AOT, and standard publishing?

.NET 9 offers multiple publishing strategies that interact directly with your containerization approach. Choosing incorrectly can lead to runtime crashes or unexpectedly large images.

In practice, I recommend starting with TrimMode=partial for existing applications. It removes unused framework code without aggressively trimming application assemblies, providing meaningful size reductions with minimal regression risk. Full trimming and Native AOT require extensive testing; they fundamentally change how the runtime resolves types and can silently break JSON serialization, Entity Framework, or dependency injection if not configured with proper root annotations.

How do you debug and validate your .NET container locally?

Before pushing to any registry, validate your container behaves identically to local development. A frequent pitfall is assuming that because tests pass on your machine, they will pass in a minimal Alpine environment missing expected system libraries or locale data.

1. Build with progress output: Use docker build --progress=plain to see real-time layer construction. Hidden failures in restore or publish often surface here.
2. Inspect layer contents: Run dive <image-tag> to visualize layer efficiency and spot accidentally included files like .git directories or test artifacts.
3. Test as non-root: Execute docker run --user 1000:1000 to verify file permissions and avoid last-minute surprises in hardened clusters.
4. Validate health endpoints: Confirm ASP.NET Core health checks respond correctly inside the container, not just on localhost.
5. Scan for vulnerabilities: Integrate Trivy or Grype into your local workflow before CI catches issues. This aligns with the scanning practices detailed in our container image scanning guide.

If your application fails to start in the container but works locally, check for hardcoded paths, Windows-specific APIs, or missing environment variables. The .NET runtime throws descriptive errors for missing native dependencies; capture logs with docker logs <container> rather than guessing.

Deploying Secure .NET Containers at Scale

When you Dockerize a .NET app with multi-stage builds correctly, you gain more than just smaller images—you establish a repeatable, auditable artifact pipeline that satisfies both engineering velocity and compliance requirements. The patterns covered here represent the current production standard for 2026, balancing developer ergonomics with operational rigor. Start with the basic multi-stage template, measure your actual image size and build times, then incrementally adopt trimming or AOT only where justified by concrete metrics. If your team needs help auditing existing Dockerfiles or designing a compliant container strategy, reach out to discuss your specific architecture.