There are two supported frameworks for building server-side containerized Docker applications with .NET: .NET Framework and .NET 7. They share many .NET platform components, and you can share code across the two. Howerver, there are fundamental differences between them, and which framework you use will depend on what you want to accomplish. This section provides guidance on when to choose each framework.
General guidance
This section provides a summary of when to choose .NET 7 or .NET Framework. We provide more details about these choices in the sections that follow.
Use .NET 7, with Linux or Windows Containers, for your containerized Docker server application when:
- You have cross-platform needs. For example, you want to use both Linux and Windows Containers.
- Your application architecture is based on microservices.
- You need to start containers fast and want a small footprint per container to achieve better density or more containers per hardware unit in order to lower your costs.
In short, when you create new containerized .NET applications, you should consider .NET 7 as the default choice. It has many benefits and fits best with the containers philosophy and style of working.
An extra benefit of using .NET 7 is that you can run side-by-side .NET versions for applications within the same machine. This benefit is more important for servers or VMs that do not use containers, because containers isolate the versions of .NET that the app needs. (As long as they are compatible with the underlying OS.)
Use .NET Framework for your containerized Docker server application when:
- Your application currently uses .NET Framework and has strong dependencies on Windows.
- You need to use Windows APIs that are not supported by .NET 7.
- You need to use third-party .NET libraries or NuGet packages that are not available for .NET 7.
Using .NET Framework on Docker can improve your deployment experiences by minimizing deployment issues. This "lift and shift" scenario is important for containerizing legacy applications that were originally developed with the traditional .NET Framework, like ASP.NET WebForms, MVC web apps, or WCF (Windows Communication Foundation) services.
When to choose .NET for Docker containers
The modularity and lightweight nature of .NET 7 makes it perfect for containers. When you deploy and start a container, its image is far smaller with .NET 7 than with .NET Framework. In contrast, to use .NET Framework for a container, you must base your image on the Windows Server Core image, which is a lot heavier than the Windows Nano Server or Linux images that you use for .NET 7.
Additionally, .NET 7 is cross-platform, so you can deploy server apps with Linux or Windows container images. However, if you are using traditional .NET Framework, you can only deploy images based on Windows Server Core.
The following is a more detailed explanation of why to choose .NET 7.
Developing and deploying cross platform
Clearly, if your goal is to have an application (web app or service) that can run on multiple platforms supported by Docker (Linux and Windows), the right choice is .NET 7, because .NET Framework only supports Windows.
.NET 7 also supports macOS as a development platform. However, when you deploy containers to a Docker host, that host must (currently) be based on Linux or Windows. For example, in a development environment, you could use a Linux VM running on a Mac.
Visual Studio provides an integrated development environment (IDE) for Windows and supports Docker development.
Visual Studio for Mac is an IDE, evolution of Xamarin Studio, that runs on macOS and supports Docker-based application development. This tool should be the preferred choice for developers working in Mac machines who also want to use a powerful IDE.
You can also use Visual Studio Code on macOS, Linux, and Windows. Visual Studio Code fully supports .NET 7, including IntelliSense and debugging. Because VS Code is a lightweight editor, you can use it to develop containerized apps on the machine in conjunction with the Docker CLI and the .NET CLI. You can also target .NET 7 with most third-party editors like Sublime, Emacs, vi, and the open-source OmniSharp project, which also provides IntelliSense support.
In addition to the IDEs and editors, you can use the .NET CLI for all supported platforms.
Using containers for new ("green-field") projects
Containers are commonly used in conjunction with a microservices architecture, althought they can also be used to containerize web apps or services that follow any architectural pattern. You can use .NET Framework on Windows Containers, but the modularity and lightweight nature of .NET 7 makes it perfect for containers and microservices architectures. When you create and deploy a container, its image is far smaller with .NET 7 than with .NET Framework.
Create and deploy microservices on containers
You could use the traditional .NET Framework for building microservices-based applications (without containers) by using plain processes. That way, because the .NET Framework is already installed and shared across processes, processes are light and fast to start. However, if you are using containers, the image for the traditional .NET Framework is also based on Windows Server Core and that makes it too heavy for a microservices-on-containers approach. However, teams have been looking for opportunities to improve the experience for .NET Framework users as well. Recently, size of the Windwos Server Core container images have been reduced to >40% smaller.
On the other hand, .NET 7 is the best candidate if you're embracing a microservices-oriented system that is based on containers because .NET 7 is lightweight. In addition, its related container images, for either Linux or Windows Nano Server, are lean and small, making containers light and fast to start.
A microservice is meant to be as small as possible: to be light when spinning up, to have a small footprint, to have a small Bounded Context (check DDD, Domain-Driven Design), to represent a small area of concerns, and to be able to start and stop fast. For those requirements, you will want to use small and fast-to-instantiate container images like the .NET 7 container image.
A microservices architecture also allows you to mix technologies across a service boundary. This approach enables a gradual migration to .NET 7 for new microservices that work in conjunction with other microservices or with services developed with Node.js, Python, Java, GoLang, or other technologies.
Deploying high density in scalable systems
When to choose .NET Framework for Docker containers
While .NET 7 offers significant benefits for new applications and application patterns, .NET Framework will continue to be a good choice for many existing scenarios.
Migrating existing applications directly to a Windows Server container
You might want to use Docker container just to simpl deployment, even if you are not creating microservices. For example, perhaps you want to improve your DevOps workflow with Docker—containers can give you better isolated test environments and can also eliminate deployment issues caused by missing dependencies when you move to a production environment. In cases like these, even if you are deploying a monolithic application, it makes sense to use Docker and Windows Containers for your current .NET Framework applications.
In most cases for this scenario, you will not need to migrate your existing applications to .NET 7; you can use Docker containers that include the traditional .NET Framework. However, a recommended approach is to use .NET 7 as you extend an existing application, such as writing a new service in ASP.NET Core.
Using third-party .NET libraries or NuGet packages not available for .NET 7
Third-party libraries are quickly embracing .NET Standard, which enables code sharing across all .NET flavors, including .NET 7. With .NET Standard 2.0 and later, the API surface compatibility across different frameworks has become significantly larger. Even more, .NET Core 2.x and newer applications can also directly reference existing .NET Framework libraries (see .NET Framework 4.6.1 supporting .NET Standard 2.0).
In addition, the Windows Compatibility Pack extends the API surface available for .NET Standard 2.0 on Winodws. This pack allows recompiling most existing code to .NET Standard 2.x with little or no modification, to run on Windows.
However, even with that exceptional progression since .NET Standard 2.0 and .NET Core 2.1 or later, there might be cases where certain NuGet packages need Windows to run and might not support .NET Core or later. If those packages are critical for your application, then you will need to use .NET Framework on Windows Containers.
Using .NET technologies not available for .NET 7
Some .NET Framework technologies aren't available in .NET 7. Some of them might become available in later releases, but others don't fit the new application patterns targeted by .NET Core and might never be available.
The following list shows most of the technologies that aren't available in .NET 7:
- ASP.NET Web Forms. This technology is only available on .NET Framework. Currently there are no plans to bring ASP.NET Web Forms to .NET or later.
- Workflow-related services. Windows Workflow Foundation (WF), Workflow Services (WCF + WF in a single service), and WCF Data Services (formerly known as ADO.NET Data Services) are only available on .NET Framework. There are currently no plans to bring them to .NET 7.
In addition to the technologies listed in the official .NET roadmap, other features might be ported to the new unified .NET platform. You might consider participating in the discussions on GitHub so that your voice can be heard. And if you think something is missing, file a new issue in the dotnet/runtime GitHub repository.
Using a platform or API that doesn't support .NET 7
Some Microsoft and third-party platforms don't support .NET 7. For example, some Azure services provide an SDK that isn't yet available for consumption on .NET 7 yet. Most Azure SDK should eventually be ported to .NET 7/.NET Standard, but some might not for several reasons. You can see the available Azure SDKs in the Azure SDK Latest Releases page.
In the meantime, if any platform or service in Azure still doesn't support .NET 7 with its client API, you can use the equivalent REST API from the Azure service or the client SDK on .NET Framework.
Porting existing ASP.NET application to .NET 7
.NET Core is a revolutionary step forward from .NET Framework. It offers a host of advantages over .NET Framework across the board from productivity to performance, and from cross-platform support to developer satisfaction. If you are using .NET Framework and planning to migrate your application to .NET Core or .NET 5+, see Porting Existing ASP.NET Apps to .NET Core.
Decision table: .NET implementations to use for Docker
The following decision table summarizes whether to use .NET Framework or .NET 7. Remember that for Linux containers, you need Linux-based Docker hosts (VMs or servers), and that for Windows Containers, you need Windows Server-based Docker hosts (VMs or servers).
Important
Your development machines will run one Docker host, either Linux or Windows. Related microservices that you want to run and test together in one solution will all need to run on the same container platform.
| Architecture / App Type | Linux containers | Windows Containers |
|---|---|---|
| Microservices on containers | .NET 7 | .NET 7 |
| Monolithic app | .NET 7 | .NET Framework .NET 7 |
| Best-in-class performance and scalability | .NET 7 | .NET 7 |
| Windows Server legacy app ("brown-field") migration to containers | -- | .NET Framework |
| New container-based development ("green-field") | .NET 7 | .NET 7 |
| ASP.NET Core | .NET 7 | .NET 7 (recommended) .NET Framework |
| ASP.NET 4 (MVC 5, Web API 2, and Web Forms) | -- | .NET Framework |
| SignalR services | .NET Core 2.1 or higher version | .NET Framework .NET Core 2.1 or higher version |
| WCF, WF, and other legacy frameworks | WCF in .NET Core (client library only) or CoreWCF | .NET Framework WCF in .NET 7 (client library only) or CoreWCF |
| Consumption of Azure services | .NET 7 (eventually most Azure services will provide client SDKs for .NET 7) |
.NET Framework .NET 7 (eventually most Azure services will provide client SDKs for .NET 7) |
What OS to target with .NET containers
Figure 3-1. Operating systems to target depending on versions of the .NET framework
| Image | Comments |
|---|---|
| mcr.microsoft.com/dotnet/runtime:7.0 | .NET 7 multi-architecture: Supports Linux and Windows Nano Server depending on the Docker host. |
| mcr.microsoft.com/dotnet/aspnet:7.0 | ASP.NET Core 7.0 multi-architecture: Supports Linux and Windows Nano Server depending on the Docker host. The aspnetcore image has a few optimizations for ASP.NET Core. |
| mcr.microsoft.com/dotnet/aspnet:7.0-bullseye-slim | .NET 7 runtime-only on Linux Debian distro |
| mcr.microsoft.com/dotnet/aspnet:7.0-nanoserver-1809 | .NET 7 runtime-only on Windows Nano Server (Windows Server version 1809) |
Official .NET Docker images
The Official .NET Docker images are Docker images created and optimized by Microsoft. They're publicly available on Microsoft Artifact Registry. You can search over the catalog to find all .NET image repositories, for example .NET SDK repository.
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, and so on). Image repositories provide extensive tagging to help you select not just a specific framework version, but also to choose an OS (Linux distribution or Windows version).
.NET 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 buid .NET apps.
- Images used to run .NET 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 and build
During development, what is important is how fast you iterate changes, and the ability to debug the changes. The size of the image isn't 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 image (mcr.microsoft.com/dotnet/sdk:7.0) during development and build process. When building inside a Docker container, the important aspects are the elements that are needed to compile your app. This includes the compiler and any other .NET dependencies.
Why is this type of build image important? You don't deploy this image to production. Instead, it's an image that 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 image. Therefore, the runtime-only image based on mcr.microsoft.com/dotnet/aspnet:7.0 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's 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'll see images that contain per-jitted (the compilation form IL to native that occurs at run time) packages.
Although there are multiple versions of the .NET 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's quick to pull the image from your registry.
When you explore the .NET image repositories at Microsoft Artifact Registry, you'll 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:
| Image | Comments |
|---|---|
| mcr.microsoft.com/dotnet/aspnet:7.0 | ASP.NET Core, with runtime only and ASP.NET Core optimizations, on Linux and Windows (multi-arch) |
| mcr.microsoft.com/dotnet/sdk:7.0 | .NET 7, with SDKs included, on Linux and Windows (multi-arch) |
You can find all the available docker images in dotnet-docker and also refer to the latest preview releases by using nightly build mcr.microsoft.com/dotnet/nightly/*
Article From: Choosing Between .NET and .NET Framework for Docker Containers - .NET | Microsoft Learn