Add support for containers

You can add support for Docker containers in supported Visual Studio project types, such as ASP.NET web projects and others. See the overview for information about supported project types in your version of Visual Studio.

You can add support for Docker or Podman containers in supported Visual Studio project types, such as ASP.NET web projects and others. See the overview for information about supported project types in your version of Visual Studio.

Prerequisites

• Docker Desktop
• Visual Studio 2019 or later with the ASP.NET and web development, Azure development workload, and/or .NET Core cross-platform development workload installed.
• .NET Core Development Tools for development with .NET Core.
• To publish to Azure Container Registry, an Azure subscription. Sign up for a free trial.

Prerequisites

• Docker Desktop
• Visual Studio with the ASP.NET and web development, Azure development workload, and/or .NET desktop development workload installed.
• To publish to Azure Container Registry, an Azure subscription. Sign up for a free trial.

Prerequisites

• Docker Desktop or Podman Desktop.
• Visual Studio, or for Podman support, Visual Studio (Insiders), with the ASP.NET and web development, Azure development workload, and/or .NET desktop development workload installed.
• To publish to Azure Container Registry, an Azure subscription. Sign up for a free trial.

You can enable support for containers during project creation by selecting Enable Docker support when you create a new project, as shown in the following screenshot:

You can enable support for containers during project creation by selecting Enable container support when you create a new project, as shown in the following screenshot:

You can add Docker support to an existing project by selecting Add > Docker Support in Solution Explorer. The Add > Docker Support and Add > Container Orchestrator Support commands are located on the right-click menu (or context menu) of the project node for an ASP.NET Core project in Solution Explorer, as shown in the following screenshot:

You can add Docker support to an existing project by selecting Add > Container Support in Solution Explorer. The Add > Container Support and Add > Container Orchestrator Support commands are located on the right-click menu (or context menu) of the project node for an ASP.NET Core project in Solution Explorer, as shown in the following screenshot:

Add Docker support

When you add or enable Docker support, Visual Studio adds the following to the project:

• a Dockerfile file
• a .dockerignore file
• a NuGet package reference to the Microsoft.VisualStudio.Azure.Containers.Tools.Targets

The Dockerfile you add resembles the following code. In this example, the project was named WebApplication-Docker, and you chose Linux containers:

#See https://aka.ms/containerfastmode to understand how Visual Studio uses this Dockerfile to build your images for faster debugging.

FROM mcr.microsoft.com/dotnet/aspnet:3.1 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:3.1 AS build
WORKDIR /src
COPY ["WebApplication-Docker/WebApplication-Docker.csproj", "WebApplication-Docker/"]
RUN dotnet restore "WebApplication-Docker/WebApplication-Docker.csproj"
COPY . .
WORKDIR "/src/WebApplication-Docker"
RUN dotnet build "WebApplication-Docker.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "WebApplication-Docker.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApplication-Docker.dll"]

Choose the container build type and other options

When you add or enable container support to a .NET 7 or later project, Visual Studio shows the Container Scaffolding Options dialog box, which gives you the choice of operating system (Linux or Windows), but also the ability to choose the container build type, either Dockerfile or .NET SDK.

You can also specify the Container Image Distro and the Container Build Context.

Container Image Distro specifies which OS image your containers use as the base image. This list changes if you switch between Linux and Windows as the container type.

The following images are available:

Windows:

• Windows Nano Server (recommended, only available 8.0 and later, not preset for Native Ahead-of-time (AOT) deployment projects)
• Windows Server Core (only available 8.0 and later)

Linux:

• Default (Debian, but the tag matches your target .NET version)
• Debian
• Ubuntu
• Chiseled Ubuntu
• Alpine

Container Build Context specifies the folder that is used for docker build (or podman build). See Docker build context or Podman build. The default is the solution folder, which is recommended. All the files needed for a build need to be under this folder, which is not the case if you choose the project folder or some other folder.

Dockerfile container build type

If you choose the Dockerfile container build type, Visual Studio adds the following to the project:

• a Dockerfile file
• a .dockerignore file
• a NuGet package reference to the Microsoft.VisualStudio.Azure.Containers.Tools.Targets

The Dockerfile you add will resemble the following code. In this example, the project was named WebApplication-Docker, and you chose Linux containers:

# See https://aka.ms/customizecontainer to learn how to customize your debug container and how Visual Studio uses this Dockerfile to build your images for faster debugging.

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081


# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["WebApplication15-AddContainerSupport/WebApplication15-AddContainerSupport.csproj", "WebApplication15-AddContainerSupport/"]
RUN dotnet restore "./WebApplication15-AddContainerSupport/WebApplication15-AddContainerSupport.csproj"
COPY . .
WORKDIR "/src/WebApplication15-AddContainerSupport"
RUN dotnet build "./WebApplication15-AddContainerSupport.csproj" -c $BUILD_CONFIGURATION -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "./WebApplication15-AddContainerSupport.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApplication15-AddContainerSupport.dll"]

.NET SDK container build type

You can use .NET SDK's built-in support for container builds, which means you don't need a Dockerfile; see Containerize a .NET app with dotnet publish. Instead, you configure your containers using MSBuild properties in the project file, and the settings for launching the containers with Visual Studio are encoded in a .json configuration file, launchSettings.json.

Here, choose .NET SDK as the container build type to use .NET SDK's container management instead of a Dockerfile.

Container Image Distro specifies which OS image your containers use as the base image. This list changes if you switch between Linux and Windows as the container. See the previous section for a list of available images.

The .NET SDK container build entry in launchSettings.json looks like the following code:

"Container (.NET SDK)": {
  "commandName": "SdkContainer",
  "launchBrowser": true,
  "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}",
  "environmentVariables": {
    "ASPNETCORE_HTTPS_PORTS": "8081",
    "ASPNETCORE_HTTP_PORTS": "8080"
  },
  "publishAllPorts": true,
  "useSSL": true
}

The .NET SDK manages some of the settings that would have been encoded in a Dockerfile, such as the container base image, and the environment variables to set. The settings available in the project file for container configuration are listed at Customizing your container. For example, the Container Image Distro is saved in the project file as the ContainerBaseImage property. You can change it later by editing the project file.

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0-alpine-amd64</ContainerBaseImage>
</PropertyGroup>

Choose the container build type and other options

When you add or enable Docker support to a .NET 7 or later project, Visual Studio shows the Container Scaffolding Options dialog box, which gives you the choice of operating system (Linux or Windows), but also the ability to choose the container build type, either Dockerfile or .NET SDK. This dialog box doesn't appear in .NET Framework projects.

In 17.11 and later, you can also specify the Container Image Distro and the Docker Build Context.

Container Image Distro specifies which OS image your containers use as the base image. This list changes if you switch between Linux and Windows as the container type.

The following images are available:

Windows:

• Windows Nano Server (recommended, only available 8.0 and later, not preset for Native Ahead-of-time (AOT) deployment projects)
• Windows Server Core (only available 8.0 and later)

Linux:

• Default (Debian, but the tag is "8.0")
• Debian
• Ubuntu
• Chiseled Ubuntu
• Alpine

Docker Build Context specifies the folder that is used for the Docker build. See Docker build context. The default is the solution folder, which is recommended. All the files needed for a build need to be under this folder, which is not the case if you choose the project folder or some other folder.

Dockerfile container build type

If you choose the Dockerfile container build type, Visual Studio adds the following to the project:

• a Dockerfile file
• a .dockerignore file
• a NuGet package reference to the Microsoft.VisualStudio.Azure.Containers.Tools.Targets

The Dockerfile you add will resemble the following code. In this example, the project was named WebApplication-Docker, and you chose Linux containers:

#See https://aka.ms/containerfastmode to understand how Visual Studio uses this Dockerfile to build your images for faster debugging.

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["WebApplication-Docker/WebApplication-Docker.csproj", "WebApplication-Docker/"]
RUN dotnet restore "WebApplication-Docker/WebApplication-Docker.csproj"
COPY . .
WORKDIR "/src/WebApplication-Docker"
RUN dotnet build "WebApplication-Docker.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "WebApplication-Docker.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WebApplication-Docker.dll"]

.NET SDK container build type

With Visual Studio 2022 17.9 and later with the .NET 7 SDK installed, in ASP.NET Core projects that target .NET 6 or later, you have the option of using .NET SDK's built-in support for container builds, which means you don't need a Dockerfile; see Containerize a .NET app with dotnet publish. Instead, you configure your containers using MSBuild properties in the project file, and the settings for launching the containers with Visual Studio are encoded in a .json configuration file, launchSettings.json.

Here, choose .NET SDK as the container build type to use .NET SDK's container management instead of a Dockerfile.

Container Image Distro specifies which OS image your containers use as the base image. This list changes if you switch between Linux and Windows as the container. See the previous section for a list of available images.

The .NET SDK container build entry in launchSettings.json looks like the following code:

"Container (.NET SDK)": {
  "commandName": "SdkContainer",
  "launchBrowser": true,
  "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}",
  "environmentVariables": {
    "ASPNETCORE_HTTPS_PORTS": "8081",
    "ASPNETCORE_HTTP_PORTS": "8080"
  },
  "publishAllPorts": true,
  "useSSL": true
}

The .NET SDK manages some of the settings that would have been encoded in a Dockerfile, such as the container base image, and the environment variables to set. The settings available in the project file for container configuration are listed at Customizing your container. For example, the Container Image Distro is saved in the project file as the ContainerBaseImage property. You can change it later by editing the project file.

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0-alpine-amd64</ContainerBaseImage>
</PropertyGroup>