Complete Guide to Docker and ASP.NET Core

You are currently viewing Complete Guide to Docker and ASP.NET Core

Containers have exploded in popularity since the introduction of Docker in 2013. Many companies have already integrated containers into their workflows to make it easier to deploy, distribute, manage, and scale their software. In this article, I will give you an overview of containers and containerization. I will also explain the difference between containers and virtual machines. I will also show you how to install Docker on Windows and how to dockerize both a new and an existing ASP.NET Core application.

Overview of Containers and Containerization

A container is a portable and self-contained unit of software that includes everything needed to run an application, including the code, dependencies, runtime, tools, settings, and libraries. Using containers, the developers can ensure that their code runs reliably and consistently, regardless of the underlying infrastructure.

Containerization is the process of creating and managing containers. This technology has revolutionized the way software is developed, deployed, and managed in the recent past by providing developers with a lightweight and isolated environment for applications. This not only enhance applications scalability and portability but also allowed businesses to build and deliver applications quickly and effectively. 

Containers and Containerization

What is Docker?

Docker is an open-source container management system that enables developers to develop, run, test, and deploy their applications in lightweight virtualized environments called containers. These containers include all required dependencies, tools, libraries, and configuration settings, making it easy to package and distribute your application for different environments and operation systems consistently.

What is Docker Image?

Docker image is a self-contained, read-only file that acts as a template or blueprint for creating Docker containers. It includes a lightweight operating system, application code, runtime libraries, system tools, and any other dependencies required to run a particular software application. Docker images are built using a layered approach, with each layer representing a specific set of changes or additions to the base image. These images can be shared, distributed, and deployed across various systems and platforms, providing a consistent and reliable environment for running applications.

What is Dockerfile?

A Dockerfile is a text file that contains a set of instructions and commands for building a Docker image. It serves as a recipe for creating customizable Docker images. A Dockerfile allows a developer to automate the process of building his Docker images, ensuring consistency and easy deployment across different environments. The Dockerfile contains commands for defining the base image, adding dependencies, copying files to the image, setting environment variables, running commands, exposing ports, and configuring other aspects of the image. Each command in the Dockerfile represents a layer in the resulting image, enabling efficient caching and incremental builds.

Docker, DockerImage, Dockerfile

Docker Containers vs Virtual Machines

CategoryDocker ContainersVirtual Machines
ArchitectureShared Host Operating System

Docker containers share the host operating system kernel. They are suited for situations where you want to run multiple applications over a single operating system kernel.
Separate Operating System

Virtual machines run on a hypervisor that emulates an entire operating system, including its kernel. They are suited for applications or servers that need to run on different operating system flavors
Resource UtilizationLess Resource Usage

Containers are more lightweight than VMs because they do not require a separate guest operating system. Multiple containers can run on a single host, sharing the host’s resources efficiently.
More Resource Usage

Virtual machines have their own guest OS, which consumes additional resources and limits the number of VMs that can be run on a given host.
Isolation and SecurityProcess Level Isolation

Containers provide process-level isolation, meaning each container is isolated from others on the same host.

Fully Isolated

Virtual machines offer stronger isolation by providing full isolation at the OS level. This makes VMs more suitable for running applications that require strict security or incompatible software requirements.
PortabilityHighly Portable

Docker containers are highly portable since they encapsulate all the necessary dependencies within the container image. Containers can easily be moved across different environments, hosts, and cloud platforms.
Less Portable

Virtual machines require a hypervisor and an operating system to be installed, making them less portable and requiring more configuration when moving between environments.
Boot timeFast boot time

Containers can be instantiated in seconds.
Slow boot time

VMs can take several minutes to instantiate.
Containers vs Virtual Machines

Docker Support in ASP.NET Core Projects

ASP.NET Core projects can use Docker to containerize applications to simplify deployment to different environments. Following are some key points to remember if you want to use Docker or containerization in ASP.NET Core projects.

  1. For building, debugging, and running containerized ASP.NET Core applications for .NET Core, you have to use Visual Studio 2017 or later versions.
  2. To containerize an ASP.NET Core project, the project must target .NET Core.
  3. Both Windows or Linux containers are supported for ASP.NET Core applications
  4. If you want to add Docker support to your project using either Windows or Linux containers, make sure that a container of the same type must be running on the Docker host.
  5. Visual Studio Container Tools does not support adding Docker to existing ASP.NET Core projects targeting the .NET Framework. 
  6. Docker support can be added to both new and existing ASP.NET Core projects in Visual Studio.
  7. You can debug your ASP.NET Core application running inside a Docker container using Visual Studio or Visual Studio Code.
  8. A Dockerfile that contains instructions to build a Docker image for your application can be added in ASP.NET Core applications in which you specify the base image, copy the necessary files, and configure the container environment.
  9. To simplify the process of running multi-container Docker applications, you can add a Docker Compose file that describes the services, networks, and volumes required for your application and any dependencies.
  10. Container registry integration: ASP.NET Core projects can be published to container registries, such as Docker Hub or Azure Container Registry.
READ ALSO:  How to Use JQuery DataTables with ASP.NET Core Web API

Benefits of using Docker with ASP.NET Core

Running your ASP.NET Core or .NET application in a Docker container has following benefits.


Docker allows you to package your ASP.NET Core application and its dependencies into a self-contained and isolated container. These containers can run consistently across different environments, such as development machines, testing servers, and production servers. This portability simplifies deployment and reduces the chances of environment-related issues.


Docker makes it easy to scale ASP.NET Core applications with the help of a container orchestration platform such as Kubernetes. You can automatically scale the number of containers based on application demand. This flexibility allows applications to efficiently handle different workloads. 

Debugging Support in Containers

You can debug ASP.NET Core applications running in Docker containers using Visual Studio or Visual Studio Code. Debugging in a container allows you to step through your code and diagnose problems in your container environment. 

Container Registries Integration

ASP.NET Core projects can be published to container registries such as Docker Hub and Azure Container Registry to store and distribute Docker images. This way the application can be easily shared with others or deployed in different environments. 

Dependency Management

Docker simplifies dependency management for ASP.NET Core projects. You can specify required dependencies and their versions in the Dockerfile to ensure consistent and reproducible builds. This helps avoid conflicts and compatibility issues between the various components of your application. 

Docker Compose Integration

Docker Compose provides a way to orchestrate multiple containers that work together. ASP.NET Core projects can use the Docker Compose file to describe the services, networks, and volumes required for your application and any dependencies. This simplifies the process of running multiple containers together.

READ ALSO:  How To Support Multiple Versions of ASP.NET Core Web API

Environment Specific Configurations

ASP.NET Core projects often use environment variables and configuration providers to dynamically configure an application based on the environment in which it is deployed. If you are working with Docker then you can set these environment variables at container creation time or via Docker Compose, making it easy to configure your application for different environments. 

Multi-stage Builds

ASP.NET Core supports multi-stage builds, so you can optimize your Docker image size. You can compile your application with a different build image and copy only the desired output files into the final runtime image. 

DevOps Integration

Docker fits well into a DevOps workflow, enabling continuous integration and continuous deployment (CI/CD) using some of the popular CI/CD tools and platforms like Jenkins, GitLab CI/CD, and Azure DevOps. Developers can automate the build, test, and deployment processes using Docker images for faster and more reliable deployments.

Version Control

Docker images can be added to the version control system along with ASP.NET Core projects. This means that changes to Dockerfiles and application dependencies can be tracked, making it easy to roll back to previous versions if necessary. It also enables you to consistently rebuild and deploy your applications at any time. 

Security and Isolation

Docker containers provide isolation between your ASP.NET Core application and the host environment, making it more difficult for vulnerabilities and misconfigurations to affect the underlying system. Containers are also resource-constrained and appropriate security measures can be configured to mitigate risk. 

Installing Docker on Windows 11

If you want to use Docker, you can install Docker Desktop as a standalone application or integrate it with Windows. Your system must meet the following requirements to successfully install Docker Desktop on Windows.

  • WSL version or above.
  • Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher.
  • Windows 10 64-bit: Home or Pro 21H2 (build 19044) or higher, or Enterprise or Education 21H2 (build 19044) or higher.
  • Hyper-V and Containers Windows features must be enabled.
  • 4GB system RAM
  • BIOS-level hardware virtualization support must be enabled in the BIOS settings.
READ ALSO:  Implement Authentication using ASP.NET Core Identity

To install Docker Desktop, you can follow the steps below:

  • Visit the Docker website and download the installer on your machine.
  • Double-click Docker Desktop Installer.exe to run the installer.
  • On the Configuration dialog, make sure that the Use WSL 2 instead of Hyper-V (recommended) option is selected.
Configuration Dialog in Docker for Desktop Installer Wizard
  • The installer will start unpacking files and this process may continue for a few minutes.
Unpacking Files in Docker for Desktop Installer Wizard
  • After a few minutes, the wizard will start the installation and it can take a few minutes to complete.
Installing Docker for Desktop on Windows
  • When the installation is completed, you may be asked to restart Windows to complete the installation process.
Docker for Desktop on Windows Installation Completed
  • Click the Close and restart button to restart your computer.
  • You may be asked to accept the Docker Subscription Service Agreement.
Docker Subscription Service Agreement
  • To start Docker Desktop, you can click the Docker Desktop on your computer desktop and you will see the Docker Desktop application like the one shown below.
Running Docker Desktop on Windows 11

Dockerizing a new ASP.NET Core Application

In this section, we will learn how to dockerize a new ASP.NET Core application in Visual Studio 2022 using a Dockerfile. We will also learn the syntax and the basic commands available in Dockerfile.

  • Open Visual Studio 2022 and go to File > New > Project.
  • Select the ASP.NET Core Web App template from the Create a new project dialog and click the Next button.
  • Profile project name as AspNetCoreDockerDemoApp and select the Location where you want to create an application and click the Next button.
  • In the Additional information dialog, you need to check the Enable Docker support checkbox. This will enable the Docker OS dropdown from where you can select Windows and then click on the Create button.
Enable Docker Support in New ASP.NET Web Application
  • If you see the following message, you need to switch to Windows containers. This is because you have probably kept the default container setting for Docker as Linux:
Switch Docker to Windows Containers
  • You can also use the Switch to Windows container… option to switch to Windows containers if you right click Docker icon in the taskbar.
Switch to Windows Containers using Docker icon in Taskbar
  • Once the application is created, you will see the following project setup in Solution Explorer. A Dockerfile is automatically added to your application along with a package Microsoft.VisualStudio.Azure.Containers.Tools.Targets that enable Visual Studio tooling for Docker files.
ASP.NET Core Application with Dockerfile in Solution Explorer
  • You will also notice that the Run button is now replaced with the Docker button and a menu with a lot of Docker related options.
Docker Menu in Visual Studio 2022
  • Click the Docker button to debug your ASP.NET Core application and you will notice some Docker commands in the Output window. After a few minutes, the browser will open and you will see the ASP.NET Core application running inside of a Windows Docker container.
ASP.NET Core Application Running inside Docker Container
  • You will also see the following Containers window at the bottom of Visual Studio 2022. On the left, you’ll see a list of containers on your local computer. The containers associated with the solution are displayed under Solution Containers. The right side shows an area with tabs for Environment, Label, Port, Volume, Log, and File. You can learn more about the usage of the containers window at Microsoft official docs here.
Containers Window in Visual Studio 2022
  • If you will open the Docker Desktop at this point, you will also see our containers in the list of containers. You can also start, stop and manage containers using Docker Desktop.
Docker Desktop Showing Available Containers

You can see how easy to start a new ASP.NET Core application with container support. Next, we will learn how to Dockerize an existing ASP.NET Core application. 

Adding Docker Support in existing ASP.NET Core Application

If you have an existing ASP.NET Core application and you want to add Docker support you can follow the steps below:

  • Right-click on your project in Solution Explorer
  • Click on the Add menu item
  • Click on Docker Support… menu option
Add Docker Support to Existing ASP.NET Core Application
  • Visual Studio will show you the Docker File Options dialog in which you need to select the target operation system. You can choose either Windows or Linux as per your application requirements.
Choose Target Operation System for Docker in Visual Studio
  • Click the OK button and Visual Studio will start adding Docker support to the application. The Docker file with default configurations will be added automatically along with the package Microsoft.VisualStudio.Azure.Containers.Tools.Targets.
ASP.NET Core Application with Dockerfile in Solution Explorer


The combination of Docker and ASP.NET Core empowers teams with greater flexibility and portability. Developers can seamlessly integrate their ASP.NET Core applications with the Docker ecosystem to package, deploy, and run applications in containers. I hope you have found this post useful. If you have any comments or suggestions, please leave your comments below. Don’t forget to share this tutorial with your friends or community.

This Post Has One Comment

  1. Yanga

    Very nice tutorial. Thank you so much.

Leave a Reply