Introduction to .NET and Docker

.NET can easily run in a Docker container. Containers provide a lightweight way to isolate your application from the rest of the host system, sharing just the kernel, and using resources given to your application. If you're unfamiliar with Docker, it's highly recommended that you read through Docker's overview documentation.

For more information about how to install Docker, see the download page for Docker Desktop: Community Edition.

Docker basics

There are a few concepts you should be familiar with. The Docker client has a CLI that you can use to manage images and containers. As previously stated, you should take the time to read through the Docker overview documentation.


An image is an ordered collection of filesystem changes that form the basis of a container. The image doesn't have a state and is read-only. An image is commonly based on another image, but with some customization. For example, when you create a new image for your application, you would base it on an existing image that already contains the .NET runtime.

Because containers are created from images, images have a set of run parameters (such as a starting executable) that run when the container starts.


A container is a runnable instance of an image. As you build your image, you deploy your application and dependencies. Then, multiple containers can be instantiated, each isolated from one another. Each container instance has its own filesystem, memory, and network interface.


Container registries are a collection of image repositories. You can base your images on a registry image. You can create containers directly from an image in a registry. The relationship between Docker containers, images, and registries is an important concept when architecting and building containerized applications or microservices. This approach greatly shortens the time between development and deployment.

Docker has a public registry hosted at the Docker Hub that you can use. .NET-related images are listed at the Docker Hub.

The Microsoft Container Registry (MCR) is the official source of Microsoft-provided container images. The MCR is built on Azure CDN to provide globally replicated images. However, the MCR doesn't have a public-facing website, and the primary way to learn about Microsoft-provided container images is through the Microsoft Docker Hub pages.


A Dockerfile is a file that defines a set of instructions that creates an image. Each instruction in the Dockerfile creates a layer in the image. Usually, when you rebuild the image, only the layers that have changed are rebuilt. The Dockerfile can be distributed to others and allows them to recreate a new image in the same manner you created it. While this allows you to distribute the instructions on how to create the image, the main way to distribute your image is to publish it to a registry.

.NET images

Official .NET Docker images are published to the Microsoft Container Registry (MCR) and are discoverable at the Microsoft .NET Docker Hub repository. Each repository contains images for different combinations of the .NET SDK or .NET runtime and operating system that you can use.

Microsoft provides images that are tailored for specific scenarios. For example, the ASP.NET Core repository provides images that are built for running ASP.NET Core apps in production. For more information, see .NET container images.

Azure services

Various Azure services support containers. You create a Docker image for your application and deploy it to one of the following services:

Next steps