Aspnet Docker

title: ASP.NET Core Docker — Complete Guide to Containerization description: 'Learn Docker for ASP.NET Core: Dockerfile optimization, multi-stage builds, docker-compose with SQL Server, environment configuration, and production container best practices.' date: 2026-06-28 lastmod: 2026-06-28 weight: 32 tags: [backend, aspnet]

Docker containers package ASP.NET Core applications with their dependencies for consistent deployment across development, staging, and production environments.

## What You'll Learn

By the end of this tutorial, you'll create optimized Dockerfiles for ASP.NET Core, configure docker-compose with SQL Server, use environment variables, implement multi-stage builds, and follow production best practices.

## Real-World Use

A microservices platform runs 12 ASP.NET Core services in Docker containers on Kubernetes. Each service has its own Dockerfile. CI/CD builds and pushes images to Azure Container Registry.

## Docker Learning Path

```mermaid
flowchart LR
  A[Health Checks] --> B[Docker]
  B --> C[Deployment]
  C --> D[Reference]
  B --> E{You Are Here}
  style E fill:#f90,color:#fff

Dockerfile

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

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
EXPOSE 80
EXPOSE 443
COPY --from=build /app .
ENV ASPNETCORE_URLS=http://+:80
ENV ASPNETCORE_ENVIRONMENT=Production
USER appuser
ENTRYPOINT ["dotnet", "MyApp.Web.dll"]

docker-compose.yml

services:
  api:
    build:
      context: .
      dockerfile: MyApp.Web/Dockerfile
    ports:
      - "5000:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ConnectionStrings__DefaultConnection=Server=db;Database=MyApp;User=sa;Password=Your_password123;
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "Your_password123"
    ports:
      - "1433:1433"
    volumes:
      - sql_data:/var/opt/mssql
    healthcheck:
      test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "Your_password123" -C -Q "SELECT 1" || exit 1
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  sql_data:

.dockerignore

**/.classpath
**/.dockerignore
**/.git
**/.gitignore
**/.vs/
**/bin/
**/obj/
**/node_modules/
**/npm-debug.log
**/secrets.yaml
**/__pycache__
*.md
Dockerfile
docker-compose*

Environment Configuration

// Program.cs
builder.Configuration
    .AddJsonFile("appsettings.json", optional: false)
    .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
    .AddEnvironmentVariables();

// Docker environment variable naming convention
// ConnectionStrings__DefaultConnection maps to ConnectionStrings:DefaultConnection

Common Mistakes

1. Not Using Multi-Stage Builds

Without multi-stage, SDK dependencies bloat the runtime image. Build in SDK stage, publish to runtime stage.

2. Running as Root

Running containers as root is a security risk. Add USER appuser in the Dockerfile.

3. Hardcoding Connection Strings

Connection strings belong in environment variables, not in the Dockerfile.

4. Ignoring .dockerignore

Large context (obj/, bin/, .git) makes builds slow. Always exclude unnecessary files.

5. Not Handling SQL Server Startup Time

SQL Server takes time to start. Use health checks and depends_on with condition: service_healthy.

Practice Questions

1. Why use multi-stage Docker builds?

Build stage compiles the code. Runtime stage is minimal (only runtime). Smaller, more secure images.

2. How do you pass connection strings to a container?

Use environment variables. In docker-compose: ConnectionStrings__DefaultConnection=Server=db;...

3. What base image should ASP.NET Core use?

mcr.microsoft.com/dotnet/aspnet:8.0 for runtime, mcr.microsoft.com/dotnet/sdk:8.0 for building.

4. How do you handle SQL Server in Docker?

Use the mcr.microsoft.com/mssql/server image. Configure volumes for data persistence.

5. Challenge: Create a Dockerfile that builds, publishes, and runs an ASP.NET Core API.

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /app
COPY *.csproj . && dotnet restore
COPY . . && dotnet publish -c Release -o out
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/out .
ENV ASPNETCORE_URLS=http://+:80
ENTRYPOINT ["dotnet", "MyApp.dll"]

FAQ

Mini Project: Dockerized ASP.NET Core API

Create a complete docker-compose setup for an ASP.NET Core API with SQL Server.

services:
  api:
    build: .
    ports: ["8080:80"]
    environment:
      - ConnectionStrings__DefaultConnection=Server=db;Database=App;User=sa;Password=Pass123!
    depends_on: [db]
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment: [ACCEPT_EULA=Y, MSSQL_SA_PASSWORD=Pass123!]

What's Next

ASP.NET Core Deployment ASP.NET Core Reference