Skip to content
W3S101

docker_setting_asp_dotnet_core

Docker - Containerizing Modern ASP.NET Core Applications

Section titled “Docker - Containerizing Modern ASP.NET Core Applications”

ASP.NET Core is Microsoft’s modern, cross-platform, high-performance framework for building web applications and services. Docker provides an excellent way to package, deploy, and run ASP.NET Core applications consistently across different environments.

This tutorial guides you through setting up Docker and containerizing a simple ASP.NET Core application using current best practices.

Prerequisites

Section titled “Prerequisites”

Before you begin, ensure you have the following installed:

  • Docker Desktop: The easiest way to get Docker running on Windows or macOS. It handles the underlying virtualization (WSL 2 on Windows, Hypervisor framework on Mac) and provides the Docker Engine, CLI, and other tools. Download it from the official Docker website. Ensure your system meets the installation requirements (e.g., Windows 10/11 64-bit: Pro, Enterprise, or Education; Home editions require WSL 2). For Linux, follow the official instructions to install Docker Engine.
  • .NET SDK: You need the .NET Software Development Kit (SDK) to create and build ASP.NET Core applications. We’ll use .NET 8.0 (or the latest LTS version) in this tutorial. You can download it from the official .NET website.

Verify your installations by opening a terminal or command prompt and running:

docker --version
dotnet --version

You should see the installed versions of Docker and the .NET SDK printed without errors.

Creating a Sample ASP.NET Core Application

Section titled “Creating a Sample ASP.NET Core Application”

Let’s create a simple web application using the .NET CLI.

Step 1: Open your terminal or command prompt.

Step 2: Navigate to a directory where you want to create your project (e.g., cd C:\projects or cd ~/projects).

Step 3: Run the following command to create a new ASP.NET Core Razor Pages application:

dotnet new webapp -n MyWebApp --use-program-main

This command creates a new directory named MyWebApp containing the project files. The --use-program-main flag ensures it uses a structure familiar from older .NET versions, which can sometimes be simpler for beginners.

Step 4: Navigate into the newly created project directory:

cd MyWebApp

You now have a basic ASP.NET Core application ready to be containerized.

Creating the Dockerfile

Section titled “Creating the Dockerfile”

A Dockerfile is a text document that contains instructions for building a Docker image. We’ll create a multi-stage Dockerfile, which is a best practice for .NET applications. It helps keep the final image small and secure by separating the build environment from the runtime environment.

Step 1: In the root directory of your MyWebApp project (where the .csproj file is located), create a new file named Dockerfile (no extension).

Step 2: Add the following content to the Dockerfile:

# Use the official .NET SDK image as the build environment
# Using AS to name the stage 'build'
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /app


# Copy the project file and restore dependencies
COPY *.csproj ./
RUN dotnet restore


# Copy the remaining source code
COPY . ./


# Publish the application
RUN dotnet publish -c Release -o /app/publish


# Use the official ASP.NET Core runtime image for the final stage
# Using AS to name the stage 'final'
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app


# Copy the published output from the build stage
COPY --from=build /app/publish .


# Expose port 8080 for the application
# ASP.NET Core default port inside container might be 80, but 8080 is commonly used too.
# Check your app's configuration (Properties/launchSettings.json or Program.cs) if needed.
# We'll map to this port when running the container.
EXPOSE 8080


# Set the entry point for the container
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

Explanation of the Dockerfile:

  • FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build: Starts the first stage named build using the .NET 8 SDK image. This image contains all tools needed to build your application.
  • WORKDIR /app: Sets the working directory inside the container.
  • COPY *.csproj ./: Copies the project file.
  • RUN dotnet restore: Restores the NuGet packages.
  • COPY . ./: Copies the rest of the application source code.
  • RUN dotnet publish ...: Builds and publishes the application in Release mode to the /app/publish directory.
  • FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final: Starts the second stage named final using the much smaller ASP.NET Core runtime image. This image only contains the necessary components to run the application.
  • WORKDIR /app: Sets the working directory for the final stage.
  • COPY --from=build /app/publish .: Copies only the published application artifacts from the build stage.
  • EXPOSE 8080: Informs Docker that the container will listen on port 8080. Note: The ASP.NET Core runtime image often defaults to listening on port 80. If your application uses port 80, you should EXPOSE 80. However, Kestrel configuration in newer templates might default to 8080 for HTTP. We use 8080 here assuming a common configuration, adjust if your app differs. You can configure the port via ASPNETCORE_URLS environment variable.
  • ENTRYPOINT ["dotnet", "MyWebApp.dll"]: Specifies the command to run when the container starts.

This multi-stage approach ensures that the final image doesn’t include the .NET SDK or your source code, resulting in a smaller and more secure image.

Building the Docker Image

Section titled “Building the Docker Image”

Now, let’s build the Docker image using the Dockerfile.

Step 1: Ensure you are in the MyWebApp directory in your terminal (the directory containing the Dockerfile).

Step 2: Run the following command:

docker build -t mywebapp-image .

Explanation:

  • docker build: The command to build an image.
  • -t mywebapp-image: Tags the image with the name mywebapp-image. Tagging makes it easier to refer to the image later.
  • .: Specifies that the build context (the files needed for the build, including the Dockerfile) is the current directory.

Docker will execute the steps defined in your Dockerfile. This might take a few minutes the first time as Docker needs to download the base images (sdk and aspnet). Subsequent builds will be faster due to caching.

You can verify the image was created by running docker images.

Running the Docker Container

Section titled “Running the Docker Container”

With the image built, let’s run it as a container.

Step 1: Run the following command in your terminal:

docker run -d -p 8080:8080 --name mywebapp-container mywebapp-image

Explanation:

  • docker run: The command to run a container from an image.
  • -d: Runs the container in detached mode (in the background).
  • -p 8080:8080: Maps port 8080 on your host machine to port 8080 inside the container (HostPort:ContainerPort). If you exposed port 80 in your Dockerfile because your app listens on 80, you would use -p 8080:80.
  • --name mywebapp-container: Assigns a name to the running container for easier management.
  • mywebapp-image: The name of the image to use.

Step 2: Verify the container is running:

docker ps

You should see mywebapp-container listed.

Accessing the Application

Section titled “Accessing the Application”

Open your web browser and navigate to http://localhost:8080.

You should see the default ASP.NET Core welcome page served from within your Docker container!

Common Issue Note: If the site doesn’t load, double-check the port mapping (-p option) matches the port exposed (EXPOSE) and the port your application actually listens on inside the container (check ASPNETCORE_URLS environment variable defaults or settings).

Stopping and Removing the Container

Section titled “Stopping and Removing the Container”

To stop the container:

docker stop mywebapp-container

To remove the stopped container:

docker rm mywebapp-container

Further Learning & Next Steps

Section titled “Further Learning & Next Steps”

You have successfully containerized a basic ASP.NET Core application. Here are some areas to explore next:

  • Volume Mounting: Persist data outside the container (e.g., databases, logs).
  • Docker Compose: Define and run multi-container applications (e.g., web app + database).
  • Environment Variables: Configure your application within the container using environment variables (e.g., database connection strings, API keys). Set them using the -e flag in docker run or in a Docker Compose file.
  • HTTPS in Containers: Configure ASP.NET Core to use HTTPS inside the container, manage development certificates.
  • Container Registries: Push your images to registries like Docker Hub or Azure Container Registry (ACR) to share and deploy them.
  • Windows Containers: If you need to run legacy .NET Framework applications or apps with specific Windows dependencies, explore building and running Windows containers (requires Windows host and switching Docker Desktop to Windows container mode).

Resources: