Summary of Microsoft Docker Images for .NET Core and .NET Framework

Cesar De la Torre

Even when these official images are still evolving, I think that a summary about the multiple Microsoft Docker images for .NET available at Docker Hub would be a “nice to have” thing.

This blog post is related to my previous blog post on “Docker containers – Should I use .NET Core or .NET Framework?”, however I’m drilling down here into the specific images available today (November 18th 2016).

.NET Core images – microsoft/dotnet

(https://hub.docker.com/r/microsoft/dotnet/)

This repository is named as microsoft/dotnet and contains multiple images supporting several Operating Systems and versions (Linux and Windows) based on multiple available TAGs, like:

The whole repo name plus the selected tag is what you need to provide into your dockerfile file.

There are additional Images used to develop, build or run .NET Core apps with sub-variant tags like “:1.1.0-sdk-msbuild”, etc. These .NET Core SDK Docker images are useful images for iterative development and the easiest way to get started using .NET Core with Docker. However, It isn’t recommended for production since it’s a bigger image than necessary as they include SDKs.

When to use images from the .NET Core repository

• Light/simple processes and “console” apps based on .NET Core (Linux or Windows) for batch and Azure WebJobs and other application types based on the “console” program.
• (Temporally) For “ASP.NET Core on Windows Nano Server”, using microsoft/dotnet:1.1-runtime-nanoserver image until Windows Image on NanoServer is provided in the ASPNETCORE repo (Still not available in ASPNETCORE repo as of Feb. 2017).
• Using the .NET Core image instead of the ASPNETCore image is pretty similar. The ASPNET image (currently only available for Linux) provides additional optimizations like the automatic setting of aspnetcore_urls to port 80 and the pre-ngend cache of assemblies. The pre-ngend cache of assemblies is important for faster startup of containers, but in development mode, it is not needed. So for development targeting ASP.NET Core services and Windows Containers, you can use these Docker images.
• See this Scott’s post related to see how to run ASP.NET Core containers on Windows Nano Server.

ASP.NET Core images – microsoft/aspnetcore

(https://hub.docker.com/r/microsoft/aspnetcore/)

This repository is named as microsoft/aspnetcore and contains multiple images supporting several versions (currently several versions for Linux Debian, but Windows Nano Server will be added pretty soon) based on multiple available TAGs, like:

The whole repo name plus the selected tag is what you need to provide into your dockerfile file.

When to use images from the ASP.NET Core repository

When using ASP.NET Core as the selected framework for your application/service, like when building a Web API service, Microsoft encourages you to use the ASP.NET Core Docker image instead of the regular .NET Core image, as the ASP.NET Core image is optimized for ASP.NET Core tasks. In addition to .NET Core this image contains a set of native images for all of the ASP.NET Core libraries. These images will be used at runtime to increase the cold-start performance of your application. A significant amount of the time taken to JIT compile on startup of your application is typically spent compiling ASP.NET Core libraries rather than your application code. Given that these libraries are not going to change for a given version we include native images so that the runtime can load them instead of running the JIT.

ASP.NET Core on Windows Nano Server will be added to this repo pretty soon (You also have it in the .NET Core image, in the meantime).

ASP.NET Core on traditional NET Framework and Windows Server Core is not an environment we actually encourage for Docker. With .NET Standard 2.0 we are bringing back the majority of APIs that force people to use ASP.NET Core on full .NET today. Therefore we are not creating an image for this, not encouraging you to use ASP.NET Core running on full .NET Framework and Windows Server Core because it gives you a worse experience in Docker with a much larger surface area, much bigger images, etc. If using ASP.NET Core, we recommend to run it on top of the CoreCLR and Windows Nano Server.

Having said that, you could always build your custom image from scratch (based on the Windows Server Core image) for ASP.NET Core running on traditional .NET Framework and Windows Server Core if that is an scenario you really need.

.NET Framework images – microsoft/dotnet-framework

(https://hub.docker.com/r/microsoft/dotnet-framework/)

This is the repo for the official Docker images for .NET Framework on Windows Server 2016 Server Core”

The supported tags are currently the following:

The whole repo name plus the selected tag is what you need to provide into your dockerfile file.

When to use images from the .NET Framework repository

When using any traditional .NET Framework technology, like plain console apps, WCF, WF, etc.

ASP.NET images – microsoft/aspnet

https://hub.docker.com/r/microsoft/aspnet/

This is the repo for ASP.NET images (Based on the traditional .NET Framework). The main difference between this image and the .NET Framework image is that this image also has IIS installed, which is a pre-requisite and dependency for the traditional ASP.NET applications.

The supported tags are currently the following.

The whole repo name plus the selected tag is what you need to provide into your dockerfile file.

When to use images from the ASP.NET repository

When using ASP.NET like MVC 5 apps, Web API 2 services or older versions, as these images have IIS installed already.

SUMMARY

Here’s a summary table:

In addition to the mentioned repos which are the main ones for .NET-Docker development, there are other base images (like the IIS image, Windows images, etc.) and additional complementary repos for sample apps that I’m not covering here. These are those:

microsoft/dotnet-nightly

microsoft/dotnet35

microsoft/aspnetcore-build-nightly

microsoft/aspnetcore-build

microsoft/dotnet-samples

microsoft/sample-dotnet

microsoft/dotnet-framework-samples

microsoft/iis

microsoft/nanoserver

microsoft/servercore

Cesar De la Torre Principal Program Manager, Azure

Follow