Containerize a .NET Core App
Applies to: Windows Server 2022, Windows Server 2019, Windows Server 2016
This topic describes how to package an existing sample .NET app for deployment as a Windows container, after setting up your environment as described in Get started: Prep Windows for containers, and running your first container as described in Run your first Windows container.
You'll also need the Git source control system installed on your computer. To install it, visit Git.
Clone the sample code from GitHub
All container sample source code is kept under the Virtualization-Documentation git repository (known informally as a repo) in a folder called
Open a PowerShell session and change directories to the folder in which you want to store this repository. (Other command prompt window types work as well, but our example commands use PowerShell.)
Clone the repo to your current working directory:
git clone https://github.com/MicrosoftDocs/Virtualization-Documentation.git
Navigate to the sample directory found under
Virtualization-Documentation\windows-container-samples\asp-net-getting-startedand create a Dockerfile, using the following commands.
A Dockerfile is like a makefile—it's a list of instructions that tell the container engine how to build the container image.
# Navigate into the sample directory Set-Location -Path Virtualization-Documentation\windows-container-samples\asp-net-getting-started # Create the Dockerfile for our project New-Item -Name Dockerfile -ItemType file
Write the Dockerfile
Open the Dockerfile you just created with whichever text editor you like and then add the following content:
FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build-env WORKDIR /app COPY *.csproj ./ RUN dotnet restore COPY . ./ RUN dotnet publish -c Release -o out FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 WORKDIR /app COPY --from=build-env /app/out . ENTRYPOINT ["dotnet", "asp-net-getting-started.dll"]
Let's break it down line-by-line and explain what each instructions does.
FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build-env WORKDIR /app
The first group of lines declares from which base image we will use to build our container on top of. If the local system does not have this image already, then docker will automatically try and fetch it. The
mcr.microsoft.com/dotnet/core/sdk:2.1 comes packaged with the .NET core 2.1 SDK installed, so it's up to the task of building ASP .NET core projects targeting version 2.1. The next instruction changes the working directory in our container to be
/app, so all commands following this one execute under this context.
COPY *.csproj ./ RUN dotnet restore
Next, these instructions copy over the .csproj files into the
/app directory. After copying this file, .NET will read from it and then to go out and fetch all the dependencies and tools needed by our project.
COPY . ./ RUN dotnet publish -c Release -o out
Once .NET has pulled all the dependencies into the
build-env container, the next instruction copies all project source files into the container. We then tell .NET to publish our application with a release configuration and specify the output path in the .
The compilation should succeed. Now we must build the final image.
This quickstart builds a .NET core project from source. When building container images, it's good practice to include only the production payload and its dependencies in the container image. We don't want the .NET core SDK included in our final image because we only need the .NET core runtime, so the dockerfile is written to use a temporary container that is packaged with the SDK called
build-env to build the app.
FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 WORKDIR /app COPY --from=build-env /app/out . ENTRYPOINT ["dotnet", "asp-net-getting-started.dll"]
Since our application is ASP.NET, we specify an image with this runtime included. We then copy over all files from the output directory of our temporary container into our final container. We configure our container to run with our new app as its entrypoint when the container starts
We have written the dockerfile to perform a multi-stage build. When the dockerfile is executed, it will use the temporary container,
build-env, with the .NET core 2.1 SDK to build the sample app and then copy the outputted binaries into another container containing only the .NET core 2.1 runtime so that we minimized the size of the final container.
Build and run the app
With the Dockerfile written, we can point Docker at our Dockerfile and tell it to build and then run our image:
In a command prompt window, navigate to the directory where the dockerfile resides and then run the docker build command to build the container from the Dockerfile.
docker build -t my-asp-app .
To run the newly built container, run the docker run command.
docker run -d -p 5000:80 --name myapp my-asp-app
Let's dissect this command:
-dtells Docker to run the container 'detached', meaning no console is hooked up to the console inside the container. The container runs in the background.
-p 5000:80tells Docker to map port 5000 on the host to port 80 in the container. Each container gets its own IP address. ASP .NET listens by default on port 80. Port mapping allows us to go to the host's IP address at the mapped port and Docker will forward all traffic to the destination port inside the container.
--name myapptells Docker to give this container a convenient name to query by (instead of having to look up the container ID assigned at runtime by Docker).
my-asp-appis the image we want Docker to run. This is the container image produced as the culmination of the
Open a web browser and navigate to
http://localhost:5000to see your containerized application, as shown in this screenshot:
The next step is to publish your containerized ASP.NET web app to a private registry using Azure Container Registry. This allows you to deploy it in your org.
When you get to the section where you push your container image to the registry, specify the name of the ASP.NET app you just packaged (
my-asp-app) along with your container registry (for example:
docker tag my-asp-app contoso-container-registry.azurecr.io/my-asp-app:v1
To see more app samples and their associated dockerfiles, see additional container samples.
Once you've published your app to the container registry, the next step would be to deploy the app to a Kubernetes cluster that you create with Azure Kubernetes Service.
Submit and view feedback for