Given the diversity of operating systems supported by Docker and the differences between .NET Framework and .NET Core, you should target a specific OS and specific versions depending on the framework you are using.
For Windows, you can use Windows Server Core or Windows Nano Server. These Windows versions provide different characteristics (IIS in Windows Server Core versus a self-hosted web server like Kestrel in Nano Server) that might be needed by .NET Framework or .NET Core, respectively.
For Linux, multiple distros are available and supported in official .NET Docker images (like Debian). In the image below you can see the possible OS version depending on the .NET framework used.
You can also create your own Docker image in cases where you want to use a different Linux distro or where you want an image with versions not provided by Microsoft. For example, you might create an image with ASP.NET Core running on the traditional .NET Framework and Windows Server Core, which is a not-so-common scenario for Docker.
When you add the image name to your Dockerfile file, you can select the operating system and version depending on the tag you use, as in the following examples:
| microsoft/dotnet:2.1-runtime | .NET Core 2.1 multi-architecture: Supports Linux and Windows Nano Server depending on the Docker host. |
| microsoft/dotnet:2.1-aspnetcoreruntime | ASP.NET Core 2.1 multi-architecture: Supports Linux and Windows Nano Server depending on the Docker host. The aspnetcore image has a few optimizations for ASP.NET Core. |
| microsoft/dotnet:2.1-aspnetcore runtime-alpine | .NET Core 2.1 runtime-only on Linux Alpine distro |
| microsoft/dotnet:2.1-aspnetcore runtime-nanoserver-1803 | .NET Core 2.1 runtime-only on Windows Nano Server (Windows Server version 1803) |
Official .Net Core Images
The Official .NET Docker images are Docker images created and optimized by Microsoft. They are publicly available in the Microsoft repositories on Docker Hub. Each repository can contain multiple images, depending on .NET versions, and depending on the OS and versions (Linux Debian, Linux Alpine, Windows Nano Server, Windows Server Core, etc.).
Since .NET Core 2.1, all the .NET Core images, including for ASP.NET Core are available at Docker Hub at the .NET Core image repo: https://hub.docker.com/r/microsoft/dotnet/
Most image repos provide extensive tagging to help you select not just a specific framework version, but also to choose an OS (Linux distro or Windows version).
NET Core and Docker image optimizations for development versus production
When building Docker images for developers, Microsoft focused on the following main scenarios:
- Images used to develop and build .NET Core apps.
- Images used to run .NET Core apps.
Why multiple images? When developing, building, and running containerized applications, you usually have different priorities. By providing different images for these separate tasks, Microsoft helps optimize the separate processes of developing, building, and deploying apps.
During Development Build
During development, what is important is how fast you can iterate changes, and the ability to debug the changes. The size of the image is not as important as the ability to make changes to your code and see the changes quickly. Some tools and “build-agent containers”, use the development .NET Core image (microsoft/dotnet:2.1-sdk) during development and build proces. When building inside a Docker container, the important aspects are the elements that are needed in order to compile your app. This includes the compiler and any other .NET dependencies.
Why is this type of build image important? You do not deploy this image to production. Instead, it is an image you use to build the content you place into a production image. This image would be used in your continuous integration (CI) environment or build environment when using Docker Multi-stage builds.
In Production
What is important in production is how fast you can deploy and start your containers based on a production .NET Core image. Therefore, the runtime-only image based on microsoft/dotnet:2.1-aspnetcore-runtime is small so that it can travel quickly across the network from your Docker registry to your Docker hosts. The contents are ready to run, enabling the fastest time from starting the container to processing results. In the Docker model, there is no need for compilation from C# code, as there is when you run dotnet build or dotnet publish when using the build container.
In this optimized image you put only the binaries and other content needed to run the application. For example, the content created by dotnet publish contains only the compiled .NET binaries, images, .js, and .css files. Over time, you will see images that contain pre-jitted (the compilation from IL to native that occurs at runtime) packages.
Although there are multiple versions of the .NET Core and ASP.NET Core images, they all share one or more layers, including the base layer. Therefore, the amount of disk space needed to store an image is small; it consists only of the delta between your custom image and its base image. The result is that it is quick to pull the image from your registry.
When you explore the .NET image repositories at Docker Hub, you will find multiple image versions classified or marked with tags. These tags help to decide which one to use, depending on the version you need, like those in the following table:
| microsoft/dotnet:2.1-aspnetcoreruntime | ASP.NET Core, with runtime only and ASP.NET Core optimizations, on Linux and Windows (multi-arch) |
| microsoft/dotnet:2.1-sdk | NET Core, with SDKs included, on Linux and Windows (multi-arch) |