faysilalshareef/dockerfile

Dockerfile — Multi-Stage .NET Builds

Core Principles

• Multi-stage build: base -> build -> publish -> final
• Copy .csproj files first for layer caching (restore step)
• Non-root user for security (USER app or numeric UID)
• Expose ports 8080 (HTTP) and 8081 (HTTPS/gRPC)
• Health check endpoint for container orchestration
• Version-aware base images: mcr.microsoft.com/dotnet/aspnet:{version}

Key Patterns

Standard ASP.NET Dockerfile

# Base runtime image
FROM mcr.microsoft.com/dotnet/aspnet:{version}-alpine AS base
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:{version}-alpine AS build
WORKDIR /src

# Copy csproj files first for layer caching
COPY ["src/{Company}.{Domain}.Command/{Company}.{Domain}.Command.csproj", "src/{Company}.{Domain}.Command/"]
COPY ["src/{Company}.{Domain}.Shared/{Company}.{Domain}.Shared.csproj", "src/{Company}.{Domain}.Shared/"]
COPY ["Directory.Build.props", "."]
COPY ["Directory.Packages.props", "."]

RUN dotnet restore "src/{Company}.{Domain}.Command/{Company}.{Domain}.Command.csproj"

# Copy everything and build
COPY . .
WORKDIR "/src/src/{Company}.{Domain}.Command"
RUN dotnet build -c Release -o /app/build

# Publish stage
FROM build AS publish
RUN dotnet publish -c Release -o /app/publish /p:UseAppHost=false

# Final stage
FROM base AS final
WORKDIR /app

# Non-root user
USER app

COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "{Company}.{Domain}.Command.dll"]

With Health Check

FROM base AS final
WORKDIR /app
USER app
COPY --from=publish /app/publish .

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

ENTRYPOINT ["dotnet", "{Company}.{Domain}.Command.dll"]

Processor Service (No HTTP)

FROM mcr.microsoft.com/dotnet/runtime:{version}-alpine AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:{version}-alpine AS build
WORKDIR /src
# ... same build pattern ...

FROM base AS final
WORKDIR /app
USER app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "{Company}.{Domain}.Processor.dll"]

.dockerignore

**/.git
**/.vs
**/bin
**/obj
**/node_modules
**/.env
**/Dockerfile*
**/.dockerignore
**/docker-compose*
**/*.md
**/tests

Version-Aware Image Tags

| .NET Version | SDK Image | Runtime Image | |---|---|---| | .NET 8 | sdk:8.0-alpine | aspnet:8.0-alpine | | .NET 9 | sdk:9.0-alpine | aspnet:9.0-alpine | | .NET 10 | sdk:10.0-alpine | aspnet:10.0-alpine |

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Single-stage build (bloated image) | Multi-stage: separate build and runtime | | Copying all files before restore | Copy csproj first for layer caching | | Running as root | Use USER app or numeric UID | | Missing .dockerignore | Exclude bin, obj, .git, tests | | Hardcoded .NET version | Match project TargetFramework |

Detect Existing Patterns

# Find existing Dockerfiles
find . -name "Dockerfile*" -type f

# Check .NET version
grep -r "TargetFramework" --include="*.csproj" src/ | head -5

# Find .dockerignore
find . -name ".dockerignore" -type f

Adding to Existing Project

1. Match the .NET version from Directory.Build.props or .csproj
2. Follow existing Dockerfile structure if one exists
3. Use Alpine images for smaller container size
4. Add health check if the service exposes HTTP endpoints
5. Update .dockerignore to exclude new test or doc directories