Dockerizing a .NET Application: Lessons from the Real World

Docker looked simple at first: write a Dockerfile, build an image, and run a container.

After migrating a real-world .NET application to Docker, I realized the real challenge wasn’t writing the Dockerfile — it was understanding everything the application depends on.

01

Multi-Stage Builds Matter

For .NET applications, I used a multi-stage Docker build.

Dockerfile

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# Build and publish

FROM mcr.microsoft.com/dotnet/aspnet:8.0
# Run the published application

The SDK is used only for building, while the final image contains just what’s needed to run the application. This keeps the production image smaller and cleaner.

02

localhost Isn’t What You Think

This was one of the biggest lessons. If the .NET application and SQL Server are running in separate containers, this won’t work:

Connection string

Server=localhost

Inside a container, localhost refers to that container itself.

With Docker Compose, services can communicate using their service names:

Connection string

Server=sqlserver

Understanding Docker networking made troubleshooting much easier.

03

Containers Are Disposable

Your application container can be recreated at any time. Your database shouldn’t be.

For SQL Server, I used Docker volumes to persist database files:

docker-compose.yml

volumes:
  - sql_data:/var/opt/mssql

The important distinction is:

• Container — runtime.
• Volume — persistent data.

04

depends_on Doesn’t Mean “Ready”

Starting SQL Server before the .NET application doesn’t guarantee SQL Server is ready to accept connections.

That’s where health checks and application-level retry logic become important.

This also taught me an important distributed-systems principle: dependencies can be temporarily unavailable, and applications should handle it.

05

Docker Compose Simplifies Everything

Once the application required .NET, SQL Server, Redis, and Nginx, Docker Compose became extremely useful.

Instead of manually starting each service, the entire stack could be managed with two commands:

Shell

docker compose up -d
docker compose down