Getting Started with Docker for .NET Developers

Docker has revolutionized the way we build, ship, and run applications. For .NET developers, it provides a powerful way to create lightweight, portable, and self-contained application packages that can run on any machine, from a local development laptop to a production Kubernetes cluster, without any changes.

This guide will walk you through the process of containerizing a simple ASP.NET Core web application.

Why Docker?

• Consistency: A container runs the same way everywhere. This eliminates the classic "it works on my machine" problem.
• Isolation: Containers run in isolated environments, so you don't have to worry about conflicting dependencies on the host machine.
• Portability: You can build a container image once and run it on any platform that supports Docker (Windows, macOS, Linux, cloud).
• Scalability: Containers are a foundational technology for modern cloud-native architectures and orchestration systems like Kubernetes.

Step 1: Create a Simple ASP.NET Core App

If you don't have one already, create a new web API:

dotnet new webapi -n MyDockerizedApp
cd MyDockerizedApp

This creates a basic ASP.NET Core application.

Step 2: Create the Dockerfile

The Dockerfile is a text file that contains a set of instructions for building a Docker image. It's the recipe for your container. Create a file named Dockerfile in the root of your project with the following content:

# Stage 1: Build the application
# Use the official .NET SDK image as a build environment
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

# Copy the project file and restore dependencies
COPY ["MyDockerizedApp.csproj", "."]
RUN dotnet restore "MyDockerizedApp.csproj"

# Copy the rest of the source code
COPY . .
WORKDIR "/src/."
RUN dotnet build "MyDockerizedApp.csproj" -c Release -o /app/build

# Publish the application
FROM build AS publish
RUN dotnet publish "MyDockerizedApp.csproj" -c Release -o /app/publish /p:UseAppHost=false

# Stage 2: Create the final runtime image
# Use the smaller ASP.NET runtime image
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app
COPY --from=publish /app/publish .

# Expose port 8080
EXPOSE 8080

# Define the entry point for the container
ENTRYPOINT ["dotnet", "MyDockerizedApp.dll"]

This is a multi-stage build, which is a best practice for .NET applications. Let's break it down:

• Stage 1 (build and publish): We use the full .NET SDK image (mcr.microsoft.com/dotnet/sdk:8.0) which contains all the tools needed to build and publish our application. We copy the source code in, restore dependencies, and then publish the release build to an /app/publish directory.
• Stage 2 (final): We start from a new, much smaller base image: the ASP.NET runtime image (mcr.microsoft.com/dotnet/aspnet:8.0). This image doesn't contain the SDK, only the runtime needed to run the application. This makes our final image significantly smaller and more secure.
• COPY --from=publish: This magic command copies the published application files from the previous stage into our final image.
• EXPOSE 8080: This informs Docker that the application in the container will listen on port 8080. ASP.NET Core defaults to this port in container environments.
• ENTRYPOINT: This is the command that will be run when the container starts.

Step 3: Build the Docker Image

Now that you have your Dockerfile, you can build the image. Open a terminal in the root of your project and run:

docker build -t my-dockerized-app .

• docker build is the command to build an image.
• -t my-dockerized-app tags (names) your image so you can easily refer to it later.
• . tells Docker to look for the Dockerfile in the current directory.

Docker will now execute the steps in your Dockerfile. This might take a minute the first time as it downloads the base images.

Step 4: Run the Docker Container

Once the image is built, you can run it as a container:

docker run -p 8081:8080 my-dockerized-app

• docker run is the command to start a container.
• -p 8081:8080 publishes a port. This maps port 8081 on your host machine to port 8080 inside the container. This is how you can access the application running inside the isolated container.
• my-dockerized-app is the name of the image you want to run.

You should see the familiar ASP.NET Core startup logs in your terminal.

Now, open a web browser and navigate to http://localhost:8081/weatherforecast. You should see the JSON output from the API running inside your Docker container!

To stop the container, go back to your terminal and press Ctrl+C.

Conclusion

You've successfully containerized your first .NET application! This is the foundational skill for modern .NET development in the cloud. From here, you can explore more advanced topics like Docker Compose for multi-container applications and deploying your images to cloud services like AWS Fargate or Azure Container Apps.