One of the main advantages of Docker is that it allows you to run software projects without the need to set up complex development environments.
This guide will show you how to create a Docker image of a .NET 5 Web API. You can then use the image to run the backend code from any PC that has Docker installed and interact with the API from your front-end web project or a mobile app.
Creating a .NET 5 Web API
Both Docker and .NET 5 are open-source and cross-platform, therefore you can follow this guide whether you're using macOS, Windows, or Linux.
Use the dotnet CLI to create an ASP.NET Web API project with the following command:
dotnet new webapi -o aspdockerapi
The command above creates a project named aspdockerapi and places it in a folder bearing the same name. In addition, the application scaffolds an API controller with some sample weather-forecast data.
Note: If you don't have .NET 5 installed on your PC, you can download it from the link below.
Download: .NET 5 For Windows, macOS, and Linux
Once the project is created you can go into the project's root folder using the following command.
cd aspdockerapi
You can run and serve the web API using the command below.
dotnet run
By default, the application will be served on port 5001. You can view the application's sample data in your browser on the following URL: https://localhost:5001/weatherforecast and the APIs data should look as below.
Creating Docker Image Instructions
To create a Docker image, you need to give the Docker Engine some instructions on how to build it. These instructions should be placed in a file named Dockerfile. Note that the file does not have an extension.
Use the following command to create the Dockerfile in your application project root folder.
touch Dockerfile
After creating the Dockerfile, your projects folder structure should be similar to the one below:
Now, copy and paste the code below into your Dockerfile.
FROM mcr.microsoft.com/dotnet/aspnet:5.0-focal AS base
WORKDIR /app
EXPOSE 80
FROM mcr.microsoft.com/dotnet/sdk:5.0-focal AS build
WORKDIR /src
COPY ["aspdockerapi.csproj", "./"]
RUN dotnet restore "./aspdockerapi.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "aspdockerapi.csproj" -c Release -o /app/build
FROM build AS publish
RUN dotnet publish "aspdockerapi.csproj" -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "aspdockerapi.dll"]
Note: In the Dockerfile above, the project and dll names are aspdockerapi.csproj and aspdockerapi.dll respectively, if your project has a different name, make sure to update your Dockerfile with the correct names.
Understanding the Dockerfile Instructions
The Dockerfile is mainly comprised of Dockerfile keywords, which by convention are capital letter words. The keywords specify the instruction to execute in each layer of the Docker image. Below are the main Docker keywords that the Dockerfile above uses.
1. FROM
The FROM keyword specifies the base image on which we want our image to be built. In the Dockerfile above, the initial base image is a .NET 5 image from Microsoft. The .NET 5 base image contains the necessary components for running the application.
2. WORKDIR
WORKDIR sets the working directory or context inside the image. In this example, the /app directory is assigned as the default root working directory using the following statement WORKDIR /app.
3. COPY
The COPY keyword simply copies content from one folder and places it into another. In this example, it's initially used to copy the main project file, that is, aspdockerapi.csproj into the images working directory.
4. RUN
The RUN keyword is used to run a specific Linux command within a Docker image. In the Dockerfile above, the RUN command is used to restore dependencies, build the ASP.NET project and publish the project.
5. CMD
The CMD keyword is a bit similar to the RUN keyword discussed above. It's also used in running a Linux command, but unlike the RUN keyword that runs commands for building the image, the CMD keyword is used to run Linux commands when the image is started, in a container instance.
6.EXPOSE
The EXPOSE keyword is used to expose a port inside of the Docker image to the outside world. In this case, the image exposes port 80, which is used for exposing the API when running the Docker container.
Building the Docker Image
To build the Docker image based on the Dockerfile, simply run the following command inside the project's root folder, that is, where the Dockerfile is placed.
docker build -t dockerwebapi -f Dockerfile .
The command above tags the Docker image with the name dockerwebapi and also specifies that the instructions for building this image are in the Dockerfile.
After the image is finished building, you can check if it's listed as a local Docker image using the following command:
docker images
The output from the command above should be similar to the one below, and the image (dockerwebapi) appears on the first line in this case.
If you don't have Docker installed on your PC, here's how to install docker on Ubuntu Linux, otherwise use the link below to download and install Docker.
Download: Docker download and installation guide
Running the Docker Image
To run the newly created Docker image, use the following command. The -ti option specifies that the image should be run in an interactive terminal mode, and --rm specifies that the container should be removed immediately after it exits.
docker run -ti --rm -p 8080:80 dockerwebapi
Also, the command specifies that the Docker container should run on the HTTP port 8080, which maps to port 80 inside the contianer.
Go to the URL: http://localhost:8080/WeatherForecast in your browser and you'll find your API data being served from the Docker instance that you're running.
Why Use Docker?
This guide showed you how to create a Docker image of a .NET 5 web API.
With Docker, you can automate how you deploy your applications, simplify the setting up of software development environments, and ease collaboration with fellow software engineers.
Docker also offers several advantages over other virtualization technologies, which is why you should probably consider using it in your software engineering projects.