Introduction

A .NET console application is one of the easiest workloads to containerize because it has no web server, no browser-facing assets, and a simple entry point. The usual Docker workflow is to create the project, publish it into a clean runtime image, and then run the resulting container exactly the same way on any machine with Docker.

Create the Console Project

Start by generating a new console application.

dotnet new console -n HelloDocker
cd HelloDocker

Replace the default program with something easy to verify.

using System;

Console.WriteLine("Hello from Dockerized .NET");

Run it locally first so you know the application itself works before adding Docker to the picture.

dotnet run

Use a Multi-Stage Dockerfile

A multi-stage build keeps the final image small by using the SDK image for build time and a lighter runtime image for execution.

1FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
2WORKDIR /src
3
4COPY . .
5RUN dotnet publish -c Release -o /app/publish
6
7FROM mcr.microsoft.com/dotnet/runtime:8.0 AS final
8WORKDIR /app
9COPY --from=build /app/publish .
10
11ENTRYPOINT ["dotnet", "HelloDocker.dll"]

The important detail is the published DLL name in ENTRYPOINT. It must match the actual project output.

Build and Run the Image

Build the container image from the project directory.

docker build -t hello-docker .

Then run it:

docker run --rm hello-docker

If everything is wired correctly, the container prints the console output and exits.

Pass Arguments and Environment Variables

Console apps often need input from arguments or environment variables. Docker supports both.

Update the app slightly:

1using System;
2
3var name = args.Length > 0 ? args[0] : Environment.GetEnvironmentVariable("APP_NAME") ?? "world";
4Console.WriteLine($"Hello, {name}");

Run with an argument:

docker run --rm hello-docker Ava

Or with an environment variable:

docker run --rm -e APP_NAME=Noah hello-docker

This is useful for making one image configurable across environments.

Keep the Container Build Predictable

A few habits make Dockerized .NET work smoother:

• build from a clean project directory
• use a .dockerignore file to avoid copying bin and obj
• prefer dotnet publish over dotnet build in the final image flow
• keep the runtime image as small as possible

A basic .dockerignore helps:

bin/
obj/
.git/

That reduces build context size and avoids stale artifacts leaking into the container build.

Understand Why Publishing Matters

dotnet publish prepares the app for deployment by collecting the compiled output and required runtime assets into one output directory. That makes it the right step for container images.

If you copy source files into a runtime-only image without publishing first, the container will not have what it needs to execute correctly. Publishing is what turns the project into a deployment artifact.

Common Pitfalls

• Using the wrong DLL name in ENTRYPOINT.
• Building directly into the final image instead of using a multi-stage Dockerfile.
• Forgetting .dockerignore and copying unnecessary build artifacts.
• Debugging Docker before confirming that dotnet run works locally.
• Using SDK images in production when a smaller runtime image would be enough.

Summary

• Create and verify the .NET console app locally first.
• Use a multi-stage Dockerfile with an SDK build stage and a runtime final stage.
• Build the image with docker build and run it with docker run.
• Pass configuration through arguments or environment variables as needed.
• Prefer dotnet publish and a small runtime image for cleaner container builds.