How to customize Docker containers in Visual Studio

Applies to: yesVisual Studio noVisual Studio for Mac noVisual Studio Code

You can customize your container images by editing the Dockerfile that Visual Studio generates when you add Docker support to your project. Whether you're building a customized container from the Visual Studio IDE, or setting up a command-line build, you need to know how Visual Studio uses the Dockerfile to build your projects. You need to know such details because, for performance reasons, Visual Studio follows a special process for building and running containerized apps that isn't obvious from the Dockerfile.

Suppose you want to make a change in the Dockerfile and see the results in both debugging and in production containers. In that case, you can add commands in the Dockerfile to modify the first stage (usually base). See Modify the container image for debugging and production. But, if you want to make a change only when debugging, but not production, then you should create another stage, and use the DockerfileFastModeStage build setting to tell Visual Studio to use that stage for debug builds. See Modify the container image only for debugging.

This article explains the Visual Studio build process for containerized apps in some detail, then it contains information on how to modify the Dockerfile to affect both debugging and production builds, or just for debugging.

Multistage build

When Visual Studio builds a project that doesn't use Docker containers, it invokes MSBuild on the local machine and generates the output files in a folder (typically bin) under your local solution folder. For a containerized project, however, the build process takes account of the Dockerfile's instructions for building the containerized app. The Dockerfile that Visual Studio uses is divided into multiple stages. This process relies on Docker's multistage build feature.

The multistage build feature helps make the process of building containers more efficient, and makes containers smaller by allowing them to contain only the bits that your app needs at run time. Multistage build is used for .NET Core projects, not .NET Framework projects.

The multistage build allows container images to be created in stages that produce intermediate images. As an example, consider a typical Dockerfile. The first stage is called base in the Dockerfile that Visual Studio generates, although the tools don't require that name.

FROM AS base

The lines in the Dockerfile begin with the ASP.NET image from Microsoft Container Registry ( and create an intermediate image base that exposes ports 80 and 443, and sets the working directory to /app.

The next stage is build, which appears as follows:

FROM AS build
COPY ["WebApplication43/WebApplication43.csproj", "WebApplication43/"]
RUN dotnet restore "WebApplication43/WebApplication43.csproj"
COPY . .
WORKDIR "/src/WebApplication43"
RUN dotnet build "WebApplication43.csproj" -c Release -o /app/build

You can see that the build stage starts from a different original image from the registry (sdk rather than aspnet), rather than continuing from base. The sdk image has all the build tools, and for that reason it's a lot bigger than the aspnet image, which only contains runtime components. The reason for using a separate image becomes clear when you look at the rest of the Dockerfile:

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

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

The final stage starts again from base, and includes the COPY --from=publish to copy the published output to the final image. This process makes it possible for the final image to be a lot smaller, since it doesn't need to include all of the build tools that were in the sdk image.

Building from the command line

If you want to build outside of Visual Studio, you can use docker build or MSBuild to build from the command line.

docker build

To build a containerized solution from the command line, you can usually use the command docker build <context> for each project in the solution. You provide the build context argument. The build context for a Dockerfile is the folder on the local machine that's used as the working folder to generate the image. For example, it's the folder that you copy files from when you copy to the container. In .NET Core projects, use the folder that contains the solution file (.sln). Expressed as a relative path, this argument is typically ".." for a Dockerfile in a project folder, and the solution file in its parent folder. For .NET Framework projects, the build context is the project folder, not the solution folder.

docker build -f Dockerfile ..


Dockerfiles created by Visual Studio for .NET Framework projects (and for .NET Core projects created with versions of Visual Studio prior to Visual Studio 2017 Update 4) are not multistage Dockerfiles. The steps in these Dockerfiles do not compile your code. Instead, when Visual Studio builds a .NET Framework Dockerfile, it first compiles your project using MSBuild. When that succeeds, Visual Studio then builds the Dockerfile, which simply copies the build output from MSBuild into the resulting Docker image. Because the steps to compile your code aren't included in the Dockerfile, you can't build .NET Framework Dockerfiles using docker build from the command line. You should use MSBuild to build these projects.

To build an image for single docker container project you can use MSBuild with the /t:ContainerBuild command option. This tells MSBuild to build the target ContainerBuild rather than the default target Build. For example:

MSBuild MyProject.csproj /t:ContainerBuild /p:Configuration=Release

You'll see output similar to what you see in the Output window when you build your solution from the Visual Studio IDE. Always use /p:Configuration=Release, since in cases where Visual Studio uses the multistage build optimization, results when building the Debug configuration might not be as expected. See Debugging.

If you are using a Docker Compose project, use this command to build images:

msbuild /p:SolutionPath=<solution-name>.sln /p:Configuration=Release docker-compose.dcproj

Project warmup

Project warmup refers to a series of steps that happen when the Docker profile is selected for a project (that is, when a project is loaded or Docker support is added) in order to improve the performance of subsequent runs (F5 or Ctrl+F5). This is configurable under Tools > Options > Container Tools. Here are the tasks that run in the background:

  • Check that Docker Desktop is installed and running.
  • Ensure that Docker Desktop is set to the same operating system as the project.
  • Pull the images in the first stage of the Dockerfile (the base stage in most Dockerfiles).
  • Build the Dockerfile and start the container.

Warmup will only happen in Fast mode, so the running container will have the app folder volume-mounted. That means that any changes to the app won't invalidate the container. This therefore improves the debugging performance significantly and decreases the wait time for long running tasks such as pulling large images.

Volume mapping

For debugging to work in containers, Visual Studio uses volume mapping to map the debugger and NuGet folders from the host machine. Volume mapping is described in the Docker documentation here. You can view the volume mappings for a container by using the Containers window in Visual Studio.

Here are the volumes that are mounted in your container:

Volume Description
Remote debugger Contains the bits required to run the debugger in the container depending on the project type. This is explained in more detail in the Debugging section.
App folder Contains the project folder where the Dockerfile is located.
Source folder Contains the build context that is passed to Docker commands.
NuGet packages folders Contains the NuGet packages and fallback folders that is read from the obj{project}.csproj.nuget.g.props file in the project.

For ASP.NET core web apps, there might be two additional folders for the SSL certificate and the user secrets, which is explained in more detail in the next section.


When building in Debug configuration, there are several optimizations that Visual Studio does that help with the performance of the build process for containerized projects. The build process for containerized apps is not as straightforward as simply following the steps outlined in the Dockerfile. Building in a container is much slower than building on the local machine. So, when you build in the Debug configuration, Visual Studio actually builds your projects on the local machine, and then shares the output folder to the container using volume mounting. A build with this optimization enabled is called a Fast mode build.

In Fast mode, Visual Studio calls docker build with an argument that tells Docker to build only the base stage (you can change that by setting the MSBuild property, DockerfileFastModeStage, described later). Visual Studio handles the rest of the process without regard to the contents of the Dockerfile. So, when you modify your Dockerfile, such as to customize the container environment or install additional dependencies, you should put your modifications in the first stage. Any custom steps placed in the Dockerfile's build, publish, or final stages will not be executed.

This performance optimization only occurs when you build in the Debug configuration. In the Release configuration, the build occurs in the container as specified in the Dockerfile.

If you want to disable the performance optimization and build as the Dockerfile specifies, then set the ContainerDevelopmentMode property to Regular in the project file as follows:


To restore the performance optimization, remove the property from the project file.

When you start debugging (F5), a previously started container is reused, if possible. If you don't want to reuse the previous container, you can use Rebuild or Clean commands in Visual Studio to force Visual Studio to use a fresh container.

The process of running the debugger depends on the type of project and container operating system:

Scenario Debugger process
.NET Core apps (Linux containers) Visual Studio downloads vsdbg and maps it to the container, then it gets called with your program and arguments (that is, dotnet webapp.dll), and then debugger attaches to the process.
.NET Core apps (Windows containers) Visual Studio uses onecoremsvsmon and maps it to the container, runs it as the entry point and then Visual Studio connects to it and attaches to the program. This is similar to how you would normally set up remote debugging on another computer or virtual machine.
.NET Framework apps Visual Studio uses msvsmon and maps it to the container, runs it as part of the entry point where Visual Studio can connect to it, and attaches to the program.

For information on vsdbg.exe, see Offroad debugging of .NET Core on Linux and OSX from Visual Studio.

Modify container image for debugging and production

To modify the container image for both debugging and production, modify the base stage. Add your customizations to the Dockerfile in the base stage section, usually the first section in the Dockerfile. Refer to the Dockerfile reference in the Docker documentation for information about Dockerfile commands.

FROM AS base
# <add your commands here>

FROM AS build
COPY ["WebApplication3/WebApplication3.csproj", "WebApplication3/"]
RUN dotnet restore "WebApplication3/WebApplication3.csproj"
COPY . .
WORKDIR "/src/WebApplication3"
RUN dotnet build "WebApplication3.csproj" -c Release -o /app/build

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

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

Modify container image only for debugging

This scenario applies when you want to do something with your containers to help you in the debugging process, such as installing something for diagnostic purposes, but you don't want that installed in production builds.

To modify the container only for debugging, create a stage and then use the MSBuild property DockerfileFastModeStage to tell Visual Studio to use your customized stage when debugging. Refer to the Dockerfile reference in the Docker documentation for information about Dockerfile commands.

In the following example, we install the package procps-ng, but only in debug mode. This supplies the command pidof, which Visual Studio requires but isn't in the Mariner image used here. The stage we use for fast mode debugging is debug, a custom stage defined here. The fast mode stage does not need to inherit from the build or publish stage, it can inherit directly from the base stage, because Visual Studio will mount a volume that contains everything needed to run the app, as described earlier in this article.

#See to understand how Visual Studio uses this Dockerfile to build your images for faster debugging.

FROM AS base

FROM base as debug
RUN tdnf install procps-ng -y

FROM AS build
COPY ["WebApplication1/WebApplication1.csproj", "WebApplication1/"]
RUN dotnet restore "WebApplication1/WebApplication1.csproj"
COPY . .
WORKDIR "/src/WebApplication1"
RUN dotnet build "WebApplication1.csproj" -c Release -o /app/build

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

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

In the project file, add this setting to tell Visual Studio to use your custom stage debug when debugging.

     <!-- other property settings -->

The next sections contain information that may be useful in certain cases, such as when you want to specify a different entry point, or if your app is SSL-enabled and you're changing something that might affect how the SSL certificates are handled.

Container entry point

Visual Studio uses a custom container entry point depending on the project type and the container operating system, here are the different combinations:

Container type Entry point
Linux containers The entry point is tail -f /dev/null, which is an infinite wait to keep the container running. When the app is launched through the debugger, it is the debugger that is responsible to run the app (that is, dotnet webapp.dll). If launched without debugging, the tooling runs a docker exec -i {containerId} dotnet webapp.dll to run the app.
Windows containers The entry point is something like C:\remote_debugger\x64\msvsmon.exe /noauth /anyuser /silent /nostatus which runs the debugger, so it is listening for connections. This method applies when the debugger runs the app. When launched without debugging, a docker exec command is used. For .NET Framework web apps, the entry point is slightly different where ServiceMonitor is added to the command.

The container entry point can only be modified in docker-compose projects, not in single-container projects.

SSL-enabled ASP.NET Core apps

Container tools in Visual Studio support debugging an SSL-enabled ASP.NET core app with a dev certificate, the same way you'd expect it to work without containers. To make that happen, Visual Studio adds a couple of more steps to export the certificate and make it available to the container. Here is the flow that Visual Studio handles for you when debugging in the container:

  1. Ensures the local development certificate is present and trusted on the host machine through the dev-certs tool.

  2. Exports the certificate to %APPDATA%\ASP.NET\Https with a secure password that is stored in the user secrets store for this particular app.

  3. Volume-mounts the following directories:

    • %APPDATA%\Microsoft\UserSecrets
    • %APPDATA%\ASP.NET\Https

ASP.NET Core looks for a certificate that matches the assembly name under the Https folder, which is why it is mapped to the container in that path. The certificate path and password can alternatively be defined using environment variables (that is, ASPNETCORE_Kestrel__Certificates__Default__Path and ASPNETCORE_Kestrel__Certificates__Default__Password) or in the user secrets json file, for example:

  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "c:\\app\\mycert.pfx",
        "Password": "strongpassword"

If your configuration supports both containerized and non-containerized builds, you should use the environment variables, because the paths are specific to the container environment.

For more information about using SSL with ASP.NET Core apps in containers, see Hosting ASP.NET Core images with Docker over HTTPS).

Next steps

Learn how to further customize your builds by setting additional MSBuild properties in your project files. See MSBuild properties for container projects.

See also

MSBuild Dockerfile on Windows Linux containers on Windows