Introduction to .NET and Docker

This article provides an introduction and conceptual background to working with .NET on Docker.

Docker: Packaging your apps to deploy and run anywhere

Docker is an open platform that enables developers and administrators to build images, ship, and run distributed applications in a loosely isolated environment called a container. This approach enables efficient application lifecycle management between development, QA, and production environments.

The Docker platform uses the Docker Engine to quickly build and package apps as Docker images created using files written in the Dockerfile format that then is deployed and run in a layered container.

You can either create your own layered images as dockerfiles or use existing ones from a registry, like Docker Hub.

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.

Further reading (and watching)

Getting .NET Docker images

The Official .NET Docker images are 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 on OS versions. Most image repos provide extensive tagging to help you select both a specific framework version and an OS (Linux distro or Windows version).

Scenario based guidance

Microsoft’s intent for .NET repositories is to have granular and focused repos, which represent a specific scenario or workload.

The microsoft/aspnetcore images are optimized for ASP.NET Core apps on Docker, so containers can start faster.

The .NET Core images (microsoft/dotnet) are intended for console apps based on .NET Core. For example, batch processes, Azure WebJobs, and other console scenarios should use optimized .NET Core images.

The most obvious horizontal scenario for using Docker and .NET applications is for production deployment and hosting. It turns out that production is just one scenario and the other ones are equally useful. These scenarios are not specific to .NET, but should apply to most developer platforms.

  • Low friction install — You can try out .NET without a local install. Just download a Docker image with .NET in it.

  • Develop in a container — You can develop in a consistent environment, making development and production environments similar (avoiding issues like global state on developer machines). Visual Studio Tools for Docker even enable you to start a container directly from Visual Studio.

  • Test in a container — You can test in a container, reducing failures due to incorrectly configured environments or other changes left behind from the last test.

  • Build in a container — You can build code in a container, avoiding the need to correctly configure shared build machines for multiple environments but instead move to a “BYOC” (bring your own container) approach.

  • Deployment in all environments — You can deploy an image through all of your environments. This approach reduces failures due to configuration differences, typically changing the image behavior via external configuration (for example, injected environment variables).

General guidance for deciding between .NET Core and .NET Framework for Docker container development.

Common Docker development scenarios

.NET Core

.NET Core resources

Pick the .NET Core samples that fit your scenarios of interest. All sample instructions describe how to target Windows or Linux Docker images from Windows, Linux, or macOS hosts.

The samples use .NET Core 2.0. They use Docker multi-stage build and multi-arch tags where appropriate.

ARM32 / Raspberry Pi

.NET Framework

This repo contain samples that demonstrate various .NET Framework Docker configurations. You can use these images as the basis of your own Docker images.

.NET Framework 4.7

The dotnet-framework:4.7 sample demonstrates basic "hello world" usage of the .NET Framework 4.7. It shows you how you can build and deploy the app relying on the .NET Framework 4.7 docker image.

.NET Framework 4.6.2

The dotnet-framework:4.6.2 sample demonstrates basic "hello world" usage of the .NET Framework 4.6.2. It shows you how you can build and deploy the app relying on the .NET Framework 4.6.2 docker image.

.NET Framework 3.5

The dotnet-framework:3.5 sample demonstrates basic "hello world" usage of .NET Framework 3.5. It shows you how you can build and deploy a project relying on .NET Framework 3.5 in Docker.


ASP.NET Framework

Windows Communication Framework (WCF)

Internet Information Server (IIS)

Interact with other Microsoft stack container images

Microsoft SQL Server

Azure DevOps Services agent

Operations Management Suite (OMS) Linux agent

Microsoft Azure Command Line Interface (CLI)


If you do not have an Azure subscription, sign up today for a free 30-day account and get $200 in Azure Credits to try out any combination of Azure services.

Microsoft Azure Cosmos DB Emulator (Windows Containers only)

Exploring the rich Docker development ecosystem

Now that you have learned about the Docker platform and different Docker images, the next step is to explore the rich Docker ecosystem. The following links show you how the Microsoft tools complement container development.

Next steps