Stage 1: Build

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

# Copy project file first to leverage Docker layer caching
COPY ["MyApp.csproj", "./"]
RUN dotnet restore --disable-parallel

# Copy remaining source and publish
COPY . .
RUN dotnet publish -c Release -o /app/publish \
    --no-restore \
    -r linux-musl-x64 \
    --self-contained false \
    -p:PublishSingleFile=true

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

# Create non-root user
RUN addgroup -g 1001 dotnetgroup && \
    adduser -u 1001 -G dotnetgroup -D appuser

# Copy published output
COPY --from=build /app/publish .

# Set ownership and permissions
RUN chown -R appuser:dotnetgroup /app

# Switch to non-root user
USER appuser

ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080

ENTRYPOINT ["dotnet", "MyApp.dll"]

ta registration.

Implementation:

Update the .csproj file:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <OutputType>Exe</OutputType>
    
    <!-- Enable Native AOT -->
    <PublishAot>true</PublishAot>
    
    <!-- Aggressive trimming to minimize binary size -->
    <TrimMode>full</TrimMode>
    
    <!-- Enable trimming warnings to catch reflection issues -->
    <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
    
    <!-- Disable features incompatible with AOT -->
    <UseAppHost>false</UseAppHost>
  </PropertyGroup>
</Project>

Dockerfile for AOT:

FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /src
COPY ["MyApp.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-alpine AS final
WORKDIR /app
COPY --from=build /app .
RUN chown -R 1001:1001 /app
USER 1001
ENTRYPOINT ["./MyApp"]

Rationale:

• runtime-deps is the smallest possible base image, containing only native dependencies.
• The entry point is the binary executable, not dotnet.
• TrimMode=full removes unused code paths, reducing the binary size significantly.

3. Configuration Management

Deployment strategies must integrate with configuration providers to support environment-specific settings without code changes.

var builder = WebApplication.CreateBuilder(args);

// Load configuration based on ASPNETCORE_ENVIRONMENT
builder.Configuration
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
    .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true, reloadOnChange: true)
    .AddEnvironmentVariables();

// Health checks for orchestration
builder.Services.AddHealthChecks()
    .AddDbContextCheck<MyDbContext>()
    .AddUrlGroup(new Uri("http://external-service/health"));

var app = builder.Build();
app.MapHealthChecks("/health");
app.MapGet("/", () => "Hello World!");
app.Run();

Pitfall Guide

1. Ignoring AOT Trimming Warnings:

   • Mistake: Enabling PublishAot without addressing IL3050 warnings.
   • Impact: Runtime crashes due to missing metadata or reflection failures. The binary may build successfully but fail when invoking serializers or DI registrations.
   • Best Practice: Treat trimming warnings as errors in CI. Use [DynamicDependency] or source generators to preserve metadata.

2. Copying bin/Debug Instead of Publishing:

   • Mistake: Using COPY bin/Debug/net8.0 /app in Dockerfiles.
   • Impact: Includes debug symbols, PDBs, and intermediate files, bloating the image. Misses the optimization step of dotnet publish.
   • Best Practice: Always use dotnet publish to generate the deployment artifact.

3. Running Containers as Root:

   • Mistake: Defaulting to the root user in Docker containers.
   • Impact: If the container is compromised, the attacker has root privileges, potentially escalating to the host kernel.
   • Best Practice: Always define a non-root user and switch context using USER.

4. Layer Caching Anti-Patterns:

   • Mistake: COPY . . before RUN dotnet restore.
   • Impact: Any source code change invalidates the restore layer, forcing dependency re-download on every build.
   • Best Practice: Copy .csproj and run restore before copying the rest of the source code.

5. Mismatched Runtime Versions in FDD:

   • Mistake: Building with .NET 8.0 SDK but running on a container with .NET 8.0.1 runtime without explicit version pinning.
   • Impact: While minor versions are compatible, major version mismatches cause immediate failure. Relying on floating tags like latest can introduce breaking changes.
   • Best Practice: Pin Docker image tags to specific minor versions (e.g., 8.0-alpine) and validate compatibility in CI.

6. Overusing Self-Contained Deployments (SCD):

   • Mistake: Using SCD for all microservices in a Kubernetes cluster.
   • Impact: Each pod carries a full copy of the .NET runtime, wasting memory and storage. Security patches to the runtime require rebuilding all images.
   • Best Practice: Use FDD in shared infrastructure to leverage runtime sharing and centralized patching. Reserve SCD for air-gapped or offline scenarios.

7. Missing Health Checks:

   • Mistake: Deploying without health endpoints configured.
   • Impact: Orchestrators cannot detect degraded states, leading to traffic routing to unhealthy instances and cascading failures.
   • Best Practice: Implement /health endpoints and configure readiness/liveness probes in Kubernetes or ECS.

Production Bundle

Action Checklist

• Enable Trimming Analysis: Set <EnableTrimAnalyzer>true</EnableTrimAnalyzer> and resolve all warnings before enabling AOT.
• Implement Multi-Stage Dockerfiles: Separate build and runtime stages; use alpine or chiseled base images.
• Enforce Non-Root Execution: Configure USER directive and file permissions in all Dockerfiles.
• Configure Health Checks: Add /health endpoints and integrate with orchestration probes.
• Pin Runtime Versions: Avoid latest tags; use specific version tags for reproducible builds.
• Validate AOT Compatibility: Run dotnet publish with PublishAot and test critical paths for reflection failures.
• Optimize Layer Caching: Structure Dockerfiles to copy project files and restore dependencies before source code.
• Scan for Vulnerabilities: Integrate container scanning (e.g., Trivy) into the CI/CD pipeline.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Serverless Function	Native AOT	Eliminates cold starts; minimizes memory footprint; reduces invocation duration costs.	High Savings: Reduces compute time per invocation by ~80%.
High-Traffic Microservice	FDD (Alpine)	Small image size; shared runtime efficiency; fast startup; easy runtime patching.	Medium Savings: Lower storage and network transfer costs; efficient scaling.
Legacy On-Prem VM	SCD	Isolation from host environment; no dependency on host runtime version.	Neutral: Higher disk usage; simplified deployment but harder runtime updates.
Background Worker	FDD or AOT	AOT for bursty workloads; FDD for long-running steady state.	Variable: AOT reduces idle cost; FDD reduces rebuild overhead.
Air-Gapped Environment	SCD	No internet access for runtime installation; self-contained binary required.	High Cost: Larger artifacts; manual runtime updates required.

Configuration Template

Dockerfile (Production Ready):

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src

COPY ["MyApp.csproj", "./"]
RUN dotnet restore -a x64

COPY . .
WORKDIR "/src/."
RUN dotnet publish "MyApp.csproj" -c $BUILD_CONFIGURATION -o /app/publish \
    -r linux-musl-x64 \
    --self-contained false \
    -p:PublishSingleFile=true \
    --no-restore

FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS final
WORKDIR /app
RUN addgroup -g 1001 dotnetgroup && \
    adduser -u 1001 -G dotnetgroup -D appuser
COPY --from=build /app/publish .
RUN chown -R appuser:dotnetgroup /app
USER appuser

ENV ASPNETCORE_ENVIRONMENT=Production
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

ENTRYPOINT ["dotnet", "MyApp.dll"]

.csproj (AOT Ready):

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    
    <PublishAot>true</PublishAot>
    <TrimMode>full</TrimMode>
    <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
    <StripSymbols>true</StripSymbols>
  </PropertyGroup>
</Project>

Quick Start Guide

1. Create the Application:

   dotnet new web -n MyApp
   cd MyApp
   

2. Add Docker Support: Create a Dockerfile using the Production Ready template above. Ensure the project name matches the DLL name in the ENTRYPOINT.

3. Build and Run Locally:

   docker build -t myapp:latest .
   docker run -d -p 8080:8080 --name myapp-container myapp:latest
   

4. Verify Deployment: Access http://localhost:8080 and http://localhost:8080/health. Confirm the container runs as a non-root user:

   docker exec myapp-container whoami
   # Expected output: appuser
   

5. Optimize for Production: Switch to Native AOT by updating .csproj and the Dockerfile. Rebuild and measure startup time improvement:

   time docker run --rm myapp-aot:latest
   

This guide provides the technical foundation to select, implement, and optimize .NET deployment strategies based on workload characteristics, ensuring performance, security, and cost efficiency in production environments.