Tell us about your PDF experience.

Container Tools in Visual Studio

Container Tools

ｅ OVERVIEW

Container tools in Visual Studio

Get started

ｆ QUICKSTART

Docker in Visual Studio

Running build tools in a container

Develop containerized apps

ｇ TUTORIAL

Multicontainer app with Docker Compose

Debugging Docker apps

Deploy Docker containers

ｃ HOW-TO GUIDE

Deploy to Azure Container Registry

Deploy to Azure App Service

Deploy to Azure Container apps

Deploy multicontainer app to Azure

Deploy to Docker Hub

Deploy without a Dockerfile

Container development tasks

ｃ HOW-TO GUIDE

Use the Containers window

Launch a subset of your Compose services

Configure the build and debug environment

Customize containers

Troubleshoot container development tools

Container tools settings

ｉ REFERENCE

Container launch settings

Container MSBuild properties

Docker Compose MSBuild properties

Configure container tools

Visual Studio Container Tools
The tools included in Visual Studio for developing with Docker or Podman containers
greatly simplify building, debugging, and deployment for containerized applications. You can
work with a container for a single project, or use container orchestration with Docker
Compose .

Prerequisites
Docker Desktop or Podman Desktop
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] 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 .

Container support in Visual Studio

Container support is available for [Link] Core projects, and .NET Core (and .NET 5 and later)
console projects. .NET Framework projects are not supported in the current version of Visual
Studio.

If you just want a container for a single project, without using orchestration, you can do that by
adding container support. You can choose Docker or Podman as a container platform, and
easily switch between them without changing the project. The next level is Container Compose
support, which adds appropriate support files for Docker Compose. (Podman Compose is not
supported.)

When you add container support to a .NET 7 or later project, you have two container build
types to choose from for adding container support. You can choose to add a Dockerfile to
specify how to build the container images, or you can choose to use the built-in container
support provided by the .NET SDK.

The Containers window lets you view running containers, browse available images, view
environment variables, logs, and port mappings, inspect the filesystem, attach a debugger, or
open a terminal window inside the container environment. See Use the Containers window.

To create a project with container support, or add container support to an existing project, see
Add support for containers.

７ Note
 Docker's licensing requirements might be different for different versions of Docker
Desktop. Refer to the Docker documentation to understand the current licensing
requirements for using your version of Docker Desktop for development in your situation.

Podman support in Visual Studio

Visual Studio supports Podman containers, a popular container management tool that provides
a daemonless container engine. You can run and manage containers using the Podman CLI
directly from Visual Studio. You can use Podman to run your single-container apps in the same
way as Docker.

To use Podman containers, start podman from the CLI, and open your solution in Visual Studio.
By default, Container Tools automatically detects whether Podman or Docker is running, and
use the currently active container runtime when you start the app. To configure the container
runtime manually, go to Tools > Options > Container Tools > Container Runtime and select
Podman or Docker. The default setting is Auto, which means Visual Studio tries to detect the
currently active container runtime. Close the Tools > Options window to commit the setting
change.

Containers window
The Containers window lets you view containers and images on your machine and see what's
going on with them. You can view the filesystem, volumes mounted, environment variables,
ports used, and examine log files.

Open the Containers window by using the quick launch (Ctrl+Q) and typing containers . You
can use the docking controls to put the window somewhere. Because of the width of the
window, it works best when docked at the bottom of the screen.

Select a container, and use the tabs to view the information that's available. To check it out, run
your Docker-enabled app, open the Files tab, and expand the app folder to see your deployed
app on the container.
For more information, see Use the Containers window.

Docker Compose support

When you want to compose a multi-container solution using Docker Compose, add container
orchestrator support to your projects. This lets you run and debug a group of containers (a
whole solution or group of projects) at the same time if they're defined in the same docker-
[Link] file.

To add container orchestrator support using Docker Compose, right-click the application in
Solution Explorer, and then select Add > Container Compose Support.

After you add container orchestrator support to your project, you see a Dockerfile added to the
project (if there wasn't one there already) and a docker-compose folder added to the solution
in Solution Explorer, as shown here:
If [Link] already exists, Visual Studio just adds the required lines of configuration
code to it.

Repeat the process with the other projects that you want to control using Docker Compose.

If you work with a large number of services, you can save time and computing resources by
selecting which subset of services you want to start in your debugging session. See Start a
subset of Compose services.

７ Note

Remote Docker hosts are not supported in Visual Studio tooling.

Service Fabric support

The Service Fabric Application Projects have been removed in Visual Studio 2026, and will
become a Visual Studio Extension. For status on availability, see this GitHub issue .

Continuous delivery and continuous integration

(CI/CD)
Visual Studio integrates readily with Azure Pipelines for automated and continuous integration
and delivery of changes to your service code and configuration. To get started, see Create your
first pipeline.

For Service Fabric, see Tutorial: Deploy your [Link] Core app to Azure Service Fabric by using
Azure DevOps Projects.

Next steps
For further details on the services implementation and use of Visual Studio tools for working
with containers, read the following articles:

Add support for containers

Container Tools in Visual Studio

Debugging apps in a local container

Deploy an [Link] container to a container registry using Visual Studio

Deploy to Azure App Service

Deploy to Azure Container Apps using Visual Studio

Last updated on 11/14/2025

Quickstart: Container Tools in Visual Studio
With Visual Studio, you can easily build, debug, and run containerized .NET, [Link], and
[Link] Core apps and publish them to Azure Container Registry, Docker Hub, Azure App
Service, or your own Container Registry. In this article, you publish an [Link] Core app to
Azure Container Registry.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] 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 .

Installation and setup

For Docker installation, first review the information at Docker Desktop for Windows: What to
know before you install . Next, install Docker Desktop .

To use Podman as the container platform, download Podman Desktop for Windows, and
then follow the tutorial at Podman for windows to initialize and start a Podman machine.

Add a project to a container

1. Before you create the Visual Studio project, make sure Docker Desktop is running the
type of containers (Windows or Linux) that you intend to use in your Visual Studio project.

To change the container type used by Docker Desktop, right-click the Docker icon (whale)
in the Taskbar and choose either Switch to Linux containers or Switch to Windows
containers.

２ Warning

If you switch the container type after you create the Visual Studio project, the Docker
image files might fail to load.

2. Create a new project using the [Link] Core Web App template.
 3. On the Create new web application screen, make sure the Enable container Support
checkbox is selected.

The screenshot shows the latest release with .NET 8.0.

4. Select the type of container you want (Windows or Linux) and select Create.

Dockerfile overview
Visual Studio creates a Dockerfile in your project, which provides the recipe for how to create a
final Docker image. For more information, see the Dockerfile reference for details about the
commands used in the Dockerfile.

Dockerfile
#See [Link] 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 [Link]/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 [Link]/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["MyWepApp/[Link]", "MyWebApp/"]
RUN dotnet restore "./MyWebApp/./[Link]"
COPY . .
WORKDIR "/src/MyWebApp"
RUN dotnet build "./[Link]" -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 "./[Link]" -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", "[Link]"]

The preceding Dockerfile is based on the Microsoft syndicates container catalog .NET 8
image and includes instructions for modifying the base image by building the project named
MyWebApp and adding it to the container.

When the new project dialog's Configure for HTTPS checkbox is checked, the Dockerfile
exposes two ports. One port is used for HTTP traffic; the other port is used for HTTPS. If the
checkbox isn't checked, a single port (80 or 8080) is exposed for HTTP traffic.

When targeting .NET 8 and later, you have the benefit of being able to run your app more
securely, as a normal user, rather than with elevated permissions. The default Dockerfile
generated by Visual Studio for .NET 8 projects is configured to run as a normal user. To enable
this behavior on an existing project, add the line USER app to the Dockerfile in the base image.
Also, because port 80 is restricted for normal users, expose ports 8080 and 8081 instead of 80
and 443. Port 8080 is used for HTTP traffic, and port 8081 is used for HTTPS. To run as a normal
user, the container must use a .NET 8 base image, and the app must run as a .NET 8 app. When
configured correctly, your Dockerfile should contain code as in the following example:

Dockerfile
FROM [Link]/dotnet/aspnet:8.0 AS base
USER app
WORKDIR /app
EXPOSE 8080
EXPOSE 8081
The default templates use the environment variable APP_UID for the identity of the normal user.

Debug
Select Docker from the debug dropdown list in the toolbar, and start debugging the app. You
might see a message with a prompt about trusting a certificate; choose to trust the certificate
to continue.

The Container Tools option in the Output window shows what actions are taking place. The
first time, it might take a while to download the base image, but it's faster on subsequent runs.

After the build completes, the browser opens and displays your app's home page. In the
browser address bar, you can see the localhost URL and port number for debugging.

７ Note

If you need to change ports for debugging, you can do that in the [Link]
file. See Container Launch Settings.

Containers window
You can use the Containers window to view running containers on your machine and other
images you have available.

Open the Containers window by using the search box in the IDE (press Ctrl+Q to use it), type
in container , and choose the Containers window from the list.

You can mount the Containers window in a convenient place, such as below the editor, by
moving it around and following the window placement guides.

In the window, find your container and step through each tab to view the environment
variables, port mappings, logs, and the filesystem.
For more information, see Use the Containers window.

Publish Docker images

Once the develop and debug cycle of the app is completed, you can create a production image
of the app.

1. Change the configuration dropdown list to Release and build the app.

2. Right-click your project in Solution Explorer and choose Publish.

3. On the Publish dialog, select the Docker Container Registry tab.

4. Choose Create New Azure Container Registry.

5. Fill in your desired values in the Create a new Azure Container Registry.
 ﾉ Expand table

Setting Suggested value Description

DNS Prefix Globally unique Name that uniquely identifies your container registry.
name

Subscription Choose your The Azure subscription to use.

subscription

Resource myResourceGroup Name of the resource group in which to create your

Group container registry. Choose New to create a new resource
group.

SKU Standard Service tier of the container registry

Registry A location close to Choose a Location in a region near you or near other
Location you services that can use your container registry.
 6. Select Create. The Publish dialog now shows the created registry.

7. Choose Finish to complete the process of publishing your container image to the newly
created registry in Azure.

Next steps
You can now pull the container from the registry to any host capable of running Docker
images, for example Azure Container Instances.
Additional resources
Container development with Visual Studio
Create a multi-container app with Docker Compose
Troubleshoot Visual Studio development with Docker
Visual Studio Container Tools GitHub repository

Last updated on 09/18/2025

Tutorial: Create a multi-container app with
Docker Compose
In this tutorial, you learn how to manage more than one container and communicate between
them when using Container Tools in Visual Studio. Managing multiple containers requires
container orchestration and requires an orchestrator such as Docker Compose. For these
procedures, you use Docker Compose. Docker Compose is great for local debugging and
testing in the course of the development cycle.

The completed sample that you create in this tutorial can be found on GitHub at
[Link] in the folder docker/ComposeSample.

Prerequisites
Docker Desktop
Visual Studio with the [Link] and web development, Azure development workload,
and/or .NET cross-platform development workload installed. This installation includes
the .NET SDK.

Create a Web Application project

In Visual Studio, create an [Link] Core Web App project, named WebFrontEnd , to create a
web application with Razor pages.

Don't select Enable container support. You add container support later in the process.
Create a Web API project
1. Add a project to the same solution and call it MyWebAPI. Select API as the project type,
and clear the checkbox for Configure for HTTPS.

７ Note

In this design, we're only using HTTPS for communication with the client, not for
communication from between containers in the same web application. Only
WebFrontEnd needs HTTPS and the code in the examples assumes that you have

cleared that checkbox. In general, the .NET developer certificates used by Visual
Studio are only supported for external-to-container requests, not for container-to-
container requests.
2. Add support for Azure Cache for Redis. Add the NuGet package
[Link] (not [Link] ). In

[Link], add the following lines, just before var app = [Link]() :

C#
[Link](options =>
{
[Link] = "redis:6379"; // redis is the container name of
the redis service. 6379 is the default port
[Link] = "SampleInstance";
});

3. Add using directives in [Link] for [Link] and

[Link] .

C#
using [Link];
using [Link];

4. In the Web API project, delete the existing [Link] and

Controllers/[Link], and add a file under Controllers,
[Link], with the following contents:

C#
 using [Link];
using [Link];
using [Link];

namespace [Link]
{
[ApiController]
[Route("[controller]")]
public class CounterController : ControllerBase
{
private readonly ILogger<CounterController> _logger;
private readonly IDistributedCache _cache;

public CounterController(ILogger<CounterController> logger,

IDistributedCache cache)
{
_logger = logger;
_cache = cache;
}

[HttpGet(Name = "GetCounter")]
public string Get()
{
string key = "Counter";
string? result = null;
try
{
var counterStr = _cache.GetString(key);
if ([Link](counterStr, out int counter))
{
counter++;
}
else
{
counter = 0;
}
result = [Link]();
_cache.SetString(key, result);
}
catch(RedisConnectionException)
{
result = "Redis cache is not found.";
}
return result;
}
}
}

The service increments a counter every time the page is accessed and stores the counter
in the cache.
Add code to call the Web API
1. In the WebFrontEnd project, open the [Link] file, and replace the OnGet method
with the following code.

C#
public async Task OnGet()
{
// Call *mywebapi*, and display its response in the page
using (var client = new [Link]())
{
var request = new [Link]();

// A delay is a quick and dirty way to work around the fact that
// the mywebapi service might not be immediately ready on startup.
// See the text for some ideas on how you can improve this.
// Uncomment if not using healthcheck (Visual Studio 17.13 or later)
// await [Link](10000);

// mywebapi is the service name, as listed in [Link].

// Docker Compose creates a default network with the services
// listed in [Link] exposed as host names.
// The port 8080 is exposed in the WebAPI Dockerfile.
// If your WebAPI is exposed on port 80 (the default for HTTP, used
// with earlier versions of the generated Dockerfile), change
// or delete the port number here.
[Link] = new Uri("[Link]
var response = await [Link](request);
string counter = await [Link]();
ViewData["Message"] = $"Counter value from cache :{counter}";
}
}

７ Note

In real-world code, you shouldn't dispose HttpClient after every request. For best
practices, see Use HttpClientFactory to implement resilient HTTP requests.

The URI given references a service name defined in the [Link] file. Docker
Compose sets up a default network for communication between containers using the
listed service names as hosts.

The code shown here works with .NET 8 and later, which sets up a user account in the
Dockerfile without administrator privileges, and exposes port 8080 because the HTTP
default port 80 is not accessible without elevated privilege.
 2. In the [Link] file, add a line to display ViewData["Message"] so that the file looks
like the following code:

CSHTML
@page
@model IndexModel
@{
ViewData["Title"] = "Home page";
}

<div class="text-center">
<h1 class="display-4">Welcome</h1>
<p>Learn about <a href="/aspnet/core">building Web apps with [Link]
Core</a>.</p>
<p>@ViewData["Message"]</p>
</div>

This code displays the value of the counter returned from the Web API project. It
increments every time the user accesses or refreshes the page.

Add Docker Compose support

1. In the WebFrontEnd project, choose Add > Container Orchestrator Support. The Docker
Support Options dialog appears.

2. Choose Docker Compose.

3. Visual Studio 17.12 and later Choose the scaffolding options for the WebFrontEnd
project.
Visual Studio 17.11 and earlier Choose your Target OS, for example, Linux.

Visual Studio creates a [Link] file and a .dockerignore file in the docker-
compose node in the solution, and that project shows in boldface font, which shows that
it's the startup project.
The [Link] appears as follows:
 YAML
services:
webfrontend:
image: ${DOCKER_REGISTRY-}webfrontend
build:
context: .
dockerfile: WebFrontEnd/Dockerfile

The .dockerignore file contains file types and extensions that you don't want Docker to
include in the container. These files are generally associated with the development
environment and source control, not part of the app or service you're developing.

Look at the Container Tools section of the output pane for details of the commands
being run. You can see the command-line tool docker-compose is used to configure and
create the runtime containers.

4. In the Web API project, again right-click on the project node, and choose Add >
Container Orchestrator Support. Choose Docker Compose, and then select the same
target OS.

７ Note

In this step, Visual Studio will offer to create a Dockerfile. If you do this on a project
that already has Docker support, you are prompted whether you want to overwrite
the existing Dockerfile. If you've made changes in your Dockerfile that you want to
keep, choose no.

Visual Studio makes some changes to your docker-compose YML file. Now both services
are included.

YAML
services:
webfrontend:
image: ${DOCKER_REGISTRY-}webfrontend
build:
context: .
dockerfile: WebFrontEnd/Dockerfile

mywebapi:
image: ${DOCKER_REGISTRY-}mywebapi
build:
context: .
dockerfile: MyWebAPI/Dockerfile
5. Add the cache to the [Link] file:

yml
redis:
image: redis

Make sure the indentation is at the same level as the other two services.

6. (Visual Studio 17.13 or later) The dependent services demonstrate a common problem.
The HTTP request in the front end's main page could run immediately on application
launch, before the mywebapi service is ready to receive web requests. If you're using Visual
Studio 17.13 or later, you can use the Docker Compose features depends_on and
healthcheck in [Link] to make the projects start in the right sequence, and

have them be ready to serve requests when required. See Docker Compose - Startup
order .

yml
services:
webfrontend:
image: ${DOCKER_REGISTRY-}webfrontend
depends_on:
mywebapi:
condition: service_healthy
build:
context: .
dockerfile: WebFrontEnd/Dockerfile

mywebapi:
image: ${DOCKER_REGISTRY-}mywebapi
depends_on:
redis:
condition: service_started
healthcheck:
test: curl --fail [Link] || exit 1
interval: 20s
timeout: 20s
retries: 5
build:
context: .
dockerfile: MyWebAPI/Dockerfile

redis:
image: redis

In this example, the health check uses curl to verify that the service is ready to process
requests. If the image you're using doesn't have curl installed, add lines to the base
 stage of the MyWebAPI Dockerfile to install it. This step requires elevated privileges, but
you can restore the normal user privileges after installing it as shown here (for the Debian
images used in this example):

Dockerfile
USER root
RUN apt-get update && apt-get install -y curl
USER $APP_UID

７ Note

If you're using a Linux distro, like Alpine, that doesn't support apt-get , try RUN apk -
-no-cache add curl instead.

These Docker Compose features require a property setting in the Docker Compose
project file ( .dcproj ). Set the property DependencyAwareStart to true:

XML
<PropertyGroup>
<!-- existing properties -->
<DependencyAwareStart>true</DependencyAwareStart>
</PropertyGroup>

This property activates a different way of starting the containers for debugging that
supports the service dependency features.

With these changes, the webfrontend service will not start until mywebapi starts and
successfully handles a web request.

7. The first project that you add container orchestration to is set up to be launched when
you run or debug. You can configure the launch action in the Project Properties for the
Docker Compose project. On the Docker Compose project node, right-click to open the
context menu, and then choose Properties, or use Alt+Enter. For example, you can
change the page that is loaded by customizing the Service URL property.
 8. Press F5. Here's what you see when launched:

9. You can monitor the containers using the Containers window. If you don't see the
window, use the search box, press Ctrl+K, Ctrl+O, or press Ctrl+Q. Under Feature search,
search for containers , and choose View > Other Windows > Containers from the list.

10. Expand the Solution Containers node, and choose the node for your Docker Compose
project to view combined logs in the Logs tab of this window.
 

You can also select the node for an individual container to view logs, environment
variables, the filesystem, and other details.

Set up launch profiles

1. This solution has an Azure Cache for Redis, but it's not efficient to rebuild the cache
container every time you start a debugging session. To avoid that situation, you can set
up a couple of launch profiles. Create one profile to start the Azure Cache for Redis.
Create a second profile to start the other services. The second profile can use the cache
container that's already running. From the menu bar, you can use the dropdown list next
to the start button to open a menu with debugging options. Select Manage Docker
Compose Launch Settings.

The Manage Docker Compose Launch Settings dialog comes up. With this dialog, you
can control which subset of services is launched during a debugging session, which are
launched with or without the debugger attached, and the launch service and URL. See
Start a subset of Compose services.
Choose New to create a new profile, and name it Start Redis . Then, set the Redis
container to Start without debugging, leave the other set to Do not start, and choose
Save.
Then create another profile Start My Services that doesn't start Redis, but starts the
other two services.
 (Optional) Create a third profile Start All to start everything. You can choose Start
without debugging for Redis.

2. Choose Start Redis from the dropdown list on the main Visual Studio toolbar. The Redis
container builds and starts without debugging. You can use the Containers window to see
that it's running. Next, choose Start My Services from the dropdown list and press F5 to
launch them. Now you can keep the cache container running throughout many
subsequent debug sessions. Every time you use Start My Services, those services use the
same cache container.

Congratulations, you're running a Docker Compose application with a custom Docker

Compose profile.

Next steps
Look at the options for deploying your containers to Azure. If you're ready to deploy to Azure
Container Apps, see Deploy a multicontainer app to Azure Container Apps.
See also
Docker Compose

Container Tools

Last updated on 11/18/2025

Tutorial: Deploy a multi-container app to
Azure Container Apps
You can deploy a multi-container app to Azure Container Apps by using Visual Studio.
Typically, you deploy each container to a separate container app instance, but you include all
your app's containers in the same container app environment to allow them to easily and
securely communicate with each other. You can configure each container app to either accept
requests from within the container environment, or to allow outside traffic. Azure Container
Apps is highly flexible and configurable, allowing for many possible microservices scenarios,
and a full set of advanced monitoring tools. If you're using Docker Compose to manage on-
premises container apps, you might consider trying to port it to a container app environment
in Azure.

The process involves a few steps using Visual Studio and the Azure portal. You can also use the
Azure CLI to perform these actions, but that's beyond the scope of this tutorial. First, we use
the app you built using the Create a multi-container app, and deploy it using the Publish
process. Visual Studio walks you through the steps to create the first container app, a container
app environment, as well as create a container registry to store the container images. You then
run through the Publish process again with the other container app. You specifically must
choose the same container app environment in the Publish process. Finally, you need to
configure the Redis cache to work with the Azure Redis Cache service. You modify the cache
configuration code and republish the Web API. Then, you configure the permissions to grant
the app's system-assigned managed identity access to the cache.

Prerequisites
An Azure subscription. Sign up for a free trial .
Visual Studio with the Azure development and [Link] and web development
workloads installed.
The MulticontainerSample project at [Link]
samples in the docker folder. The sample solution contains two projects, the Web API
backend and the [Link] Razor front end, as you created in another tutorial. You can also
create the two projects from scratch, since they are very simple modifications of the
default templates, by following that tutorial. You can skip the Docker Compose steps.

Deploy the Web API backend

1. In Solution Explorer, right-click on the Web API project node, and select Publish.

2. Choose the target Azure, and then select Azure Container Apps.
3. If you're not already signed in with an account that is associated with an Azure
subscription, you can sign in now, or change the tenant if you need to.

4. On the screen where you specify a container app, select Create new to create a new
container app.

5. On the Create Azure Container app page, enter details such as the resource group. For
this step, you create a new resource group, a new container environment, and a new
container registry.
 

It might take a little while to create the resources. When it completes, click Next to move
to the next step.

6. In the next step, you create a container registry. If you create a new container registry,
you're asked for a few details. You can choose the same region and resource group as the
container app.

7. The next step asks you to choose the container build type. Choose .NET SDK if you don't
have a Dockerfile, or Docker Desktop if you do.
 

8. For the deployment type, choose Publish (generate pubxml file) to create a publish
profile.


9. Select Finish to complete the Publish process, and create a Publish profile. If you see a
prompt about extra configuration to access the published container, choose Yes.

You see a page that shows the activity in Azure, and when you close it, the Publish screen
now has your container app's information, such as the URL for ingress to the web API.

Click the Publish button to publish to the Azure container app. Visual Studio requests that
the Azure resources be created, and starts the publish process for the WebAPI container
app.

Visual Studio might try to load the page for the new container app, but this wouldn't be
expected to work at this stage.
Now that you've published once, you've created a Publish profile ( .pubxml file), so you don't
have to repeat these steps the next time you publish. Just click the Publish button on this
screen, unless you want to start over, or change any of the Azure resources you specified.

Later, you'll use the Azure portal to make some further configuration changes for the Ingress
and to support the Azure Redis Cache, but first, in the next section, you publish the web front
end.

Deploy the front end

1. Modify the front-end code file in [Link] to reference the new URL for the Web
API container app. This is the name shown under Resource name in the Web API Publish
screen. For container-to-container communication, you can directly use HTTP with the
name of the container app, without specifying a fully qualified domain name (FQDN) and
port number. In the OnGet method, replace the existing line that sets the RequestUri to
reference the Web API container app name, as in the following code.

C#

[Link] = new Uri("[Link]

2. In Solution Explorer, right-click on the project node for the Webfrontend project, and
select Publish. On the next screen, select Create new to create a new container app.

3. On the Create new Azure container app screen, choose the same resource group and the
same container environment that you created when you published the Web API project.
 

4. Important! Select the same container registry that you created previously.
 

5. Choose the same options as you did for the Web API for the other steps. The container
build type is Docker Desktop, and the deployment type is Publish (generates pubxml
file).

6. Select Finish to complete the Publish process, and create a Publish profile. You see a page
that shows the activity in Azure, and when you close it, the Publish screen now has your
container app's information, such as the URL for ingress to the Webfrontend app.

View and configure the container apps in the Azure

portal
1. Sign in to the Azure portal.
2. Search for container apps and locate the ones you just created.
3. Choose Ingress and configure the following options:

a. On the Ingress screen, set Ingress traffic to Limited to Container Apps Environment.
This means that only the Webfrontend can send requests. Even Visual Studio won't be
able to access this service, for example, when you complete the publish process, and
Visual Studio tries to load the page, you get an error in the browser instead of
accessing the service. This is expected.

b. Check the Ingress port (it should be 8080). You're using HTTP for the web API call and
you can directly reference the container app by name in the request URI. The fully
 qualified domain name (FQDN) generated by Azure Container apps uses an HTTPS URL
(as displayed in Visual Studio on the Publish screen), but internal traffic can bypass
that.

c. For the Webfrontend Ingress, you can accept the defaults. The Target port is 8080,
because the Ingress handles all requests securely using the FQDN and HTTPS (or HTTP
to HTTPS redirection), and forwards them to the Webfrontend using HTTP on container
port 8080.

Create the Azure Redis Cache

Follow these steps to create an Azure Redis Cache in the same resource group as the container
apps.

1. In the Azure portal, open the Web API container app you created previously. Open the
Service Connector screen, and select Create. The Create connection section appears.

2. On the Create connection screen, enter the Service type as Cache for Redis, and choose
Create new to create a new Redis cache.
 

3. Choose a cache, or follow the Create new link to create a cache. If you create a new
cache, you might have to return to the container app and Service Connector and repeat
the previous steps to create the connection.

4. For the database, choose "0" to create the first numbered database for this cache.

5. Move to the Authentication tab. Choose System-assigned managed identity. Accept all
other defaults, and select Create. This creates the connection to the cache.
 6. Back in the Service Connector section of the Web API container app, refresh to see the
newly connected cache (if you don't see it already), and select the checkbox next to the
cache. Select Validate to check the status of the connection. You can expand the cache
node to see the values for the environment variables for that Azure cache. For the
purposes of this tutorial, you only need AZURE_REDIS_HOST, but you can use the others
in real-world code or for a more complete configuration. Use the values here to set the
environment variables in the Dockerfile, as described in the next section, so that Web API
can connect to the cache.

For more information, see Quickstart: Create a Service Connection for Azure Container Apps
from the Azure portal.

Configure roles for managed identity

In the Azure portal, you use Access Control (IAM) on the Azure Redis Cache to grant
Contributor access to the container app's system-assigned managed identity.

1. In the Azure portal, open the page for the Azure Redis Cache, and select Access Control
(IAM).
2. Select Add > Add Role Assignment. The Add role assignment page opens.
3. Select the Members tab, and choose managed identity.
4. Select Select members. The Select members page opens, and select System-assigned
managed identity.
5. Select Container App, and choose the Web API container app.
6. In the Role tab, choose Redis Cache Contributor.
7. Select Review and assign. The system processes the request.
8. Open Role assignments to see the system-assigned managed identity under the Redis
Cache Contributor role.

The next step is to modify the cache configuration in the Web API client to use the
DefaultAzureCredential , which is the recommended way to authenticate when you use the

system-assigned managed identity. Anyone accessing the application externally isn't required
to have specific user-level role assignments to access the resources via this form of identity
management. For more information, see Integrate Azure Redis Cache - System-assigned
managed identity.

Modify the Web API project to reference the Azure

Redis Cache service
Before you publish the Web API project to run in Azure, update it to reference Azure Redis
Cache and use a managed identity to access it securely. To accommodate this, you can modify
the cache configuration code in [Link].

For Azure Redis Cache, you set an environment variable AZURE_REDIS_HOST with the connection
information, and then read it in the startup code to connect to Azure Redis Cache, and
configure the cache.

You use [Link] to get the DefaultAzureCredential which handles secure

authentication with your managed identity.

1. In Visual Studio, in the Web API project, add a reference to the NuGet packages Azure
Identity and [Link] .

2. Add using directives for the packages you just added.

C#
using [Link];
using [Link];

3. Update the configuration code for the Redis Cache. Delete the old code and replace it
with the following code. You can review the comments later and uncomment any optional
code to suit your own more advanced scenarios.

C#
// Check the environment variable for the Redis cache host name
var cacheHostName = [Link]("AZURE_REDIS_HOST");
if ([Link](cacheHostName))
{
throw new InvalidOperationException("The environment variable
'AZURE_REDIS_HOST' is not set.");
}

var configurationOptions = [Link]($"

{cacheHostName}:6380");

// For system-assigned identity.

// In the Azure portal, we need to set up Redis service to grant Contributor
access to the system-assigned identity
// for the container app that hosts this Web API service.
await [Link](new
DefaultAzureCredential());

var connectionMultiplexer = await

[Link](configurationOptions);

[Link](options =>
{
[Link] = configurationOptions;
[Link] = "SampleInstance";
 });

// Uncomment the following line if you need to use the ConnectionMultiplexer

directly
// (for example, for advanced Redis operations like Pub/Sub or working with
Redis data structures).
// [Link]<IConnectionMultiplexer>(sp =>
// [Link](configurationOptions));

The authentication method you set earlier when you created the cache connection is
system-assigned managed identity, so the code here is consistent with that choice. If you
want to use another authentication methods as well, you need to make changes to the
code here. See Integrate Azure Redis Cache - System-assigned managed identity.

Build the Web API project to verify there are no errors.

4. If you have a Dockerfile, update the base stage of the Dockerfile to define the
environment variable AZURE_REDIS_HOST . You get the host from the Azure portal, when
you create the Azure Redis Cache, or from the Service Connector section of the Web API
container app page in the portal (see previous section).

Dockerfile
ENV AZURE_REDIS_HOST [Link]

(Optional) You can define other configuration options in environment variables, for
example, AZURE_REDIS_PORT which is usually 6380. For simplicity, this value is hardcoded
instead of using an environment variable. You might also wish to set
ASPNETCORE_ENVIRONMENT to Development.

If you're using the .NET SDK container build type (without a Dockerfile), you can set the
environment variable in [Link] under profiles > http .

JSON
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"launchUrl": "swagger",
"applicationUrl": "[Link]
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"AZURE_REDIS_HOST": "[Link]"
}
}
 5. You're ready to publish and verify these changes. Select the Publish button on the
Publish screen. Visual Studio will attempt to load the page, but this fails because the Web
API container app is not accessible to requests outside of the container app environment.

Before you can run the application with the Azure Redis Cache, you need to set up the
managed identity with the right permissions to access the cache.

Test the application

Go back to the Publish screen in the Webfrontend project, and click the link on the
Webfrontend URL. You should see the Webfrontend app appear with the counter that updates
when you refresh the page.

 Tip

Azure Container Apps seeks to maximize uptime of your services. If anything goes wrong
with one of the services, such that it fails a health probe, Azure Container Apps won't set it
as the active revision and use it serve requests. As a consequence, during the
development and testing process, you might occasionally find that the latest changes
you've made aren't reflected in the live site. In the Azure portal, select Revisions and
replicas to view the status of your latest published revision. From there, you can open logs
to help troubleshoot the issue.

Congratulations! You successfully published a multicontainer app to Azure Container Apps and
verified communication between containers and the use of the Azure Redis Cache within the
app.

Clean up resources
To clean up the resources you created during this tutorial, go the Azure portal and delete the
resource group that contains the container apps, cache, and container registry.

Next steps
Learn more about Azure Container Apps.
Learn about .NET Aspire, a technology that helps you more easily develop complex
containerized apps and services that integrate with diverse resources in Azure. .NET
Aspire supports development time orchestration, standardized integration with an array
of services, as well as tooling support with Visual Studio project templates.
 You can also the Azure command-line interface (CLI) to work with your container apps.
Install Azure CLI and get started working with Azure Container Apps by using the Azure
CLI commands by following Deploy Azure Container Apps with the az containerapp up
command.

Last updated on 09/18/2025

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

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] 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 .

Add container support when you create a project

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:

７ Note
 Support for .NET Framework containers is discontinued in the current version of Visual
Studio. .NET Framework containers were supported up to Visual Studio 2022 17.14.

Add container support to an existing project

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
[Link] Core project in Solution Explorer, as shown in the following screenshot:

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
 ７ Note

Containers based on the Chiseled Ubuntu image and that use Native Ahead-of-time
(AOT) deployment can only be debugged in Fast Mode. See Customize Docker
containers in Visual Studio.

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 [Link]

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

Dockerfile
# See [Link] 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 [Link]/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 [Link]/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["WebApplication15-AddContainerSupport/WebApplication15-
[Link]", "WebApplication15-AddContainerSupport/"]
RUN dotnet restore "./WebApplication15-AddContainerSupport/WebApplication15-
[Link]"
 COPY . .
WORKDIR "/src/WebApplication15-AddContainerSupport"
RUN dotnet build "./[Link]" -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 "./[Link]" -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", "[Link]"]

.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, [Link].
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 [Link] looks like the following code:

JSON
"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.

XML
<PropertyGroup>
<ContainerBaseImage>[Link]/dotnet/runtime:8.0-alpine-
amd64</ContainerBaseImage>
</PropertyGroup>

Next steps
For further details on the services implementation and use of Visual Studio tools for working
with containers, read the following articles:

Docker in Visual Studio

Debugging apps in a local container

Deploy an [Link] container to a container registry using Visual Studio

Deploy to Azure App Service

Deploy to Azure Container Apps using Visual Studio

Related content
Visual Studio Container Tools

Last updated on 09/18/2025

Debug apps in a local container
Visual Studio provides a consistent way to develop containers and validate your application
locally. You can run and debug your apps in Linux or Windows containers running on your local
Windows desktop with Docker installed, and you don't have to restart the container each time
you make a code change.

This article illustrates how to use Visual Studio to start an app in a local container, make
changes, and then refresh the browser to see the changes. This article also shows you how to
set breakpoints for debugging for containerized apps. Supported project types include web
app, console app, and Azure function targeting .NET Core or .NET 5 and higher. The example
presented in this article are a project of type [Link] Core Web App.

If you already have a project of a supported type, Visual Studio can create a Dockerfile and
configure your project to run in a container. See Container Tools in Visual Studio.

Prerequisites
To debug apps in a local container, the following tools must be installed:

Visual Studio , or for Podman support, Visual Studio 2026 with the [Link] and web
development workload installed.

To run Docker containers locally, you must have a local Docker client. You can use Docker
Desktop , which requires Windows 10 or later.

To run containers with Podman, install Podman Desktop .

Create a web app

If you have a project and you've added Docker support as described in the overview, skip this
section.

1. In the Visual Studio start window, select Create a new project.

2. Select [Link] Core Web App, and then select Next.

3. Enter a name for your new application (or use the default name), specify the location on
disk, and then select Next.

4. Select the .NET version you want to target. If you're not sure, choose the LTS (long-term
support) release .
 5. Choose whether you want SSL support by selecting or clearing the Configure for HTTPS
checkbox.

6. Select the Enable Docker checkbox.

7. Use the Docker OS dropdown list to select the type of container you want: Windows or
Linux.

8. Select Create to complete the process.

Edit your Razor pages and refresh

To quickly iterate changes in your Razor pages, you can start your application in a container.
Then, continue to make changes, viewing them as you would with Internet Information Services
(IIS) Express.

1. Make sure that Docker is set up to use the container type (Linux or Windows) that you are
using. Right-click on the Docker icon on the Taskbar, and choose Switch to Linux
containers or Switch to Windows containers as appropriate.

2. Editing your code and refreshing the running site as described in this section is not
enabled in the default templates in .NET Core and .NET 5 and later. To enable it, add the
NuGet package [Link] . Add a call to
the extension method AddRazorRuntimeCompilation to the code in the
 [Link] method. You only need this enabled in DEBUG mode, so code

it as follows in the Main method:

C#
// Add services to the container.
var mvcBuilder = [Link]();
#if DEBUG
if ([Link]())
{
[Link]();
}
#endif

For more information, see Razor file compilation in [Link] Core. The exact code might
vary, depending on the target framework and the project template you used.

3. Set Solution Configuration to Debug. Then, press Ctrl+F5 to build your Docker image
and run it locally.

When the container image is built and running in a Docker container, Visual Studio
launches the web app in your default browser.

4. Go to the Index page. We'll make changes on this page.

5. Return to Visual Studio and open [Link].

6. Add the following HTML content to the end of the file, and then save the changes.

HTML
<h1>Hello from a Docker container!</h1>

7. In the output window, when the .NET build is finished and you see the following lines,
switch back to your browser and refresh the page:

Output
Now listening on: [Link]
Application started. Press Ctrl+C to shut down.

Your changes have been applied!

Debug with breakpoints

Often, changes require further inspection. You can use the debugging features of Visual Studio
for this task.

1. In Visual Studio, open [Link].

2. Replace the contents of the OnGet method with the following code:

C#
ViewData["Message"] = "Your application description page from within a
container";

3. To the left of the code line, set a breakpoint.

4. To start debugging and hit the breakpoint, press F5.

5. Switch to Visual Studio to view the breakpoint. Inspect values.

Hot reload
Also, in Visual Studio 17.10 and later, Hot Reload is supported in containers, although be aware
that in a container, you have to refresh the page to see changes. If the change is to a CSS file,
you again have to refresh the page to see those changes. Note also that updates to scoped
CSS files ( .[Link] files, see [Link] Core Blazor CSS isolation) are not supported as part of
hot reload.

Authenticating to Azure services using the token

proxy
When you're using Azure services from a container, you can use DefaultAzureCredential (with
the VisualStudioCredential enabled) to authenticate with Azure services with your Microsoft
Entra account without any additional configuration in the container. To enable this, see How to
configure Visual Studio Container Tools. Also, you need to set up Azure authentication in Visual
Studio by following the instructions at Authenticate Visual Studio with Azure. The support for
VisualStudioCredential in a container is available in Visual Studio version 17.6 and later.

Azure Functions
If you're debugging an integrated Azure Functions project and using the token proxy in the
container to handle authentication to Azure services, you need to copy the .NET runtime onto
the container for the token proxy to run. If you're debugging an isolated Azure Functions
project, it already has the .NET runtime, so there's no need for this extra step.

To ensure the .NET runtime is available to the token proxy, add, or modify the debug layer in
the Dockerfile that copies the .NET runtime into the container image. For Linux containers, you
can add the following code to the Dockerfile:

Dockerfile
# This layer is to support debugging, VS's Token Proxy requires the runtime to be
installed in the container
FROM [Link]/dotnet/runtime:8.0 AS runtime
FROM base as debug
COPY --from=runtime /usr/share/dotnet /usr/share/dotnet
RUN ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet

Also, in the Visual Studio project, you need to make some changes to specify this as the layer
to use when debugging in Fast Mode. For an explanation of Fast Mode, see Customize Docker
containers in Visual Studio. For single container scenarios (not Docker Compose), set the
MSBuild property ContainerFastModeStage (or DockerfileFastModeStage ) to debug in order to
use that layer for debugging. For Docker Compose, modify the [Link]
as follows:

yml

# Set the stage to debug to use an image with the .NET runtime in it
services:
functionappintegrated:
build:
target: debug

For a code sample of authentication with Azure Functions, including both integrated and
isolated scenarios, see VisualStudioCredentialExample .

Container reuse
When you use Fast Mode, which Visual Studio normally uses for the Debug configuration,
Visual Studio rebuilds only your container images and the container itself when you change the
Dockerfile. If you don't change the Dockerfile, Visual Studio reuses the container from an
earlier run.
If you manually modified your container and want to restart with a clean container image, use
the Build > Clean command in Visual Studio, and then build as normal.

When you're not using Fast Mode, which is typical for the Release configuration, Visual Studio
rebuilds the container each time the project is built.

You can configure when Fast Mode is used; see How to configure Visual Studio Container Tools.

Troubleshoot
Learn how to troubleshoot Visual Studio Docker development.

Related content
Get more details by reading How Visual Studio builds containerized apps.

More about Docker with Visual Studio, Windows,

and Azure
Learn more about container development with Visual Studio.
To build and deploy a Docker container, see Docker integration for Azure Pipelines .
For an index of Windows Server and Nano Server articles, see Windows container
information.
Learn about Azure Kubernetes Service and review the Azure Kubernetes Service
documentation.

Last updated on 11/11/2025

Use the Containers window
You can use the Visual Studio Containers window to see what's going on inside the containers
that host your apps and to view your container images. If you're used to running Docker
commands to view and analyze your containers, this window provides a convenient way to
monitor and interact with containers without leaving the Visual Studio IDE.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio . For Podman support, Visual Studio 2026 .
For the Docker Compose node:
Docker v2, which installs with Docker Desktop and is on by default.

View information about your containers

The Containers window opens automatically when you start a containerized .NET project. To
open the Containers window any time, select View > Other Windows > Containers from the
Visual Studio menu, or press Ctrl+K, Ctrl+O. You can also use Ctrl+Q to open the Visual Studio
Search box, type Containers, and select the Containers item.

The left side of the window shows the list of containers on your local machine. The containers
associated with your current solution are under Solution Containers. On the right is a pane
with tabs for Environment, Labels, Ports, Volumes, Files, Logs, and Details.

If you're using Docker Compose, you see a tree of nodes, with a parent node for your solution
and child nodes for each project enrolled in Docker Compose.
  Tip

By default, the Containers window is docked with the Watch window when the debugger
is running. You can easily customize where the Containers tool window is docked. See
Customizing window layouts in Visual Studio.

View environment variables

The Environment tab shows the environment variables in the container. You can set these
variables in the Dockerfile, in an .env file, or by using the -e option when you start a container
using a Docker command.

７ Note

Changes to the environment variables aren't reflected in real time. Also, the environment
variables in this tab are the system environment variables on the container, not the user
environment variables local to the app.

View labels
The Labels tab shows the labels for the container. Labels are a way of setting custom metadata
on Docker objects. Visual Studio sets some labels automatically.

View port mappings

On the Ports tab, you can check the port mappings for your container. Well-known ports are
linked, so you can select the link to open a browser to the host port address.

View volumes
The Volumes tab shows the mounted filesystem nodes, or volumes, on the container.

View the filesystem

On the Files tab, you can view the container's filesystem, including the app folder that contains
your project. By using the Files tab, you can view application logs such as Internet Information
Services (IIS) logs, configuration files, and other content files in your container's filesystem.
 ７ Note

In Visual Studio 2022 version 17.7 or later, when targeting .NET 8 or later, the Dockerfile
might contain the USER app command, which specifies to run the app with regular user
permissions. The Files tab uses the same permissions, so you might not be able to view
folders that require elevated permissions to view.

To open a file in Visual Studio, double-click the file or right-click it and choose Open. Visual
Studio opens the file in read-only mode.
View logs
The Logs tab shows the results of the docker logs command. By default, the tab shows stdout
and stderr streams on a container, but you can configure the output. For details, see Docker
logging .

By default, the Logs tab streams the logs. You can pause the stream by selecting the Stream
button on the tab. Select Stream again to resume the streaming from where it left off.
To clear the logs, use the Clear button on the Logs tab. To get all the logs, use the Refresh
button.

７ Note

Visual Studio automatically redirects stdout and stderr to the Output window when you
run Windows containers without debugging. These logs then don't display in the Logs
tab.

If you're using Docker Compose with Visual Studio 2022 version 17.7 or later, you can view logs
of each container separately or interleaved into a single output stream. If you select the parent
node for the solution, you see interleaved logs from all the Compose projects. The first column
on each line shows the container that produced that line of output. If you only want to see the
logs for one container, select that project's node.

View details
The Details tab displays metadata and runtime information about the container's configuration
in JSON format. This information includes environment variables, ports, volumes, and other
runtime settings.
Interact with containers
The confirmation dialogs for various tasks, such as removing containers and images or
launching more than 10 containers at a time, might display prompts. You can disable each
prompt by using the checkbox on the dialog window.

You can also enable or disable these options by using the settings in the Tools > Options pane
under All Settings > Container Tools > Containers Window. For more information, see
Configure Container Tools.

Start, stop, and remove containers

By default, the Containers window shows all containers on the machine that Docker manages.
You can use the toolbar buttons in the Containers window to start, stop, or delete a container.
The containers list dynamically updates as containers are created or removed.

To select multiple containers, for example to remove more than one container at a time, use
Ctrl+Select. You're prompted to confirm if you try to start or remove more than 10 containers
at a time. You can disable the confirmation prompts if desired.

Open a terminal window in a running container

You can open a terminal window (command prompt or interactive shell) in the container by
using the Open Terminal Window button in the Containers window.

For Windows containers, the Windows command prompt opens. For Linux containers, a
window opens using the Bash shell.
If you're targeting .NET 8 in Visual Studio 2022 version 17.7 and later, your Dockerfile can
specify the USER app command, which means your app runs with regular user permissions
rather than elevated permissions. The terminal opens as the user specified in the Dockerfile,
which is app by default for .NET 8 projects. If no user is specified, the terminal runs as the root
user.

Attach the debugger to a container process

You can attach the debugger to a process running in the container by using the Attach to
Process button on the Containers window toolbar. When you use this button, the Attach to
Process dialog box appears and shows the processes that are running in the container.
You can attach to managed processes in the container. To look for a process in another
container, select the Find button in the Attach to Process dialog box, and select another
container in the Select Docker Container dialog box.

View images
You can view images on the local machine by using the Images tab on the left side of the
Containers window. Images pulled from external repositories are grouped together in a
treeview.
The right pane has the tabs applicable to images: Labels, Details, and Layers. The Details tab
shows the configuration details for the image in JSON format.

To remove an image, right-click the image in the treeview and choose Remove, or select the
image and then select the Remove button on the toolbar.

Prune containers and images

You can easily remove containers and images you're not using by selecting the Prune button
on the Containers window toolbar.

If you have the Containers tab selected, you're asked to confirm that you want to remove
all stopped containers.

If you have the Images tab selected, the prompt asks if you want to remove all dangling
images. Dangling images are images of layers that are no longer associated with a tagged
image. Prune dangling images occasionally to help conserve disk space.

Related content
 Container Tools overview
Container development in Visual Studio

Last updated on 12/12/2025

Launch a subset of Compose services
If you have an application that consists of multiple services and uses Docker Compose, you can
configure which services run and debug by creating or editing an existing launch profile in
Docker Compose launch settings. Launch profiles allow you to dynamically run only the
services that matter to your current scenario. You can create and select from launch profiles in
order to customize your debugging experience and set specific launch actions such as Browser
Launch URL . You also have the option of either choosing each service individually or by

choosing a Docker Compose profile, which also looks at your Compose file to determine the
group of services to run.

For information about Docker Compose profiles, see Using profiles with Compose .

Prerequisites
Visual Studio
A .NET solution with Container Orchestration with Docker Compose

Manage launch settings

Consider the following Docker Compose project in which the [Link] has five
services and three Compose profiles (web, web1 and web2).

yml

version: '3.9'

services:
webapplication1:
image: ${DOCKER_REGISTRY-}webapplication1
profiles: [web, web1]
build:
context: .
dockerfile: WebApplication1/Dockerfile

webapplication2:
image: ${DOCKER_REGISTRY-}webapplication2
profiles: [web, web2]
build:
context: .
dockerfile: WebApplication2/Dockerfile

webapplication3:
image: ${DOCKER_REGISTRY-}webapplication3
profiles: [web]
build:
 context: .
dockerfile: WebApplication3/Dockerfile

external1:
image: redis

external2:
image: redis

There are a few options to open the Docker Compose launch settings dialog:

In Visual Studio, choose Debug > Manage Docker Compose Launch Settings:

Right-click on the Visual Studio docker-compose project and select Manage Docker
Compose Launch Settings
 Use the Quick Launch (Ctrl+Q) and search for Docker Compose to find the same
command.

In the example below, the web1 Compose profile is selected, which filters the Services list to
only the three out of five included in that profile:
 ７ Note

The Docker Compose profiles section only appears if there are profiles defined in your
[Link] files.

The next example demonstrates selecting between individual services instead of filtering to the
services in a Compose profile. Here, we show how the dialog would look if you created a new
launch profile named test2 that only starts two out of the five services, webapplication1 with
debugging and webapplication2 without debugging. This launch profile also launches a
browser when the application starts and opens it to the home page of webapplication1 .
And this information is saved in [Link] as shown below

JSON

{
"profiles": {
"test2": {
"commandName": "DockerCompose",
"composeLaunchServiceName": "webapplication1",
"serviceActions": {
"external1": "DoNotStart",
"external2": "DoNotStart",
"webapplication1": "StartDebugging",
"webapplication2": "StartWithoutDebugging",
"webapplication3": "DoNotStart"
},
"composeLaunchAction": "LaunchBrowser",
 "commandVersion": "1.0",
"composeLaunchUrl": "{Scheme}://localhost:{ServicePort}"
}
}
}

Create a launch profile that uses a Docker

Compose profile
You can also further customize launch behaviors by creating Visual Studio launch profiles that
make use of the Compose profiles.

To create another profile that makes use of the Compose profile, select Use Docker Compose
profiles and choose web1 . Now the launch profile includes three services: webapplication1
(which belongs to both web and web1 Compose profiles), external1 , and external2 . By
default, the services without source code such as external1 and external2 have the default
action of Start without debugging. .NET applications with source code defaults to Start
debugging.

） Important

If a service doesn't specify a Compose profile, it's included in all Compose profiles
implicitly.
This information is saved as shown in the following code. The configuration for the service and
its default action are not saved unless you change the default action.

JSON
{
"profiles": {
"test1": {
"commandName": "DockerCompose",
"composeProfile": {
"includes": [
"web1"
]
},
"commandVersion": "1.0"
}
 }
}

You can also change the action of webapplication1 to Start without debugging. The settings in
[Link] then look like the following code:

JSON
{
"profiles": {
"test1": {
"commandName": "DockerCompose",
"composeProfile": {
"includes": [
"web1"
],
"serviceActions": {
"webapplication1": "StartWithoutDebugging"
}
},
"commandVersion": "1.0"
}
}
}

Properties
Here's a description of each property in the [Link]:

ﾉ Expand table

Property Description

commandName Name of the command. Defaults to "DockerCompose"

commandVersion Version number used to manage the schema of the DockerCompose

launch profile.

composeProfile Parent property that defines the launch profile definition. Its child
properties are includes and serviceActions

composeProfile - includes List of the Compose profile names that make up a launch profile.

composeProfile - Lists the selected Compose profiles, services, and the launch action of
serviceActions each service

serviceActions Lists the selected services and the launch action.

Property Description

composeLaunchAction Specifies the launch action to perform on F5 or Ctrl+F5. Allowed values

are None, LaunchBrowser, and LaunchWCFTestClient.

composeLaunchUrl The URL to use when launching the browser. Valid replacement tokens
are "{ServiceIPAddress}", "{ServicePort}", and "{Scheme}". For example:
{Scheme}://{ServiceIPAddress}:{ServicePort}

composeLaunchServiceName Specifies the service used for replacing the tokens in composeLaunchUrl.

Related content
Visual Studio Container Tools build and debug overview
Visual Studio Container Tools launch settings
Docker Compose build settings

Last updated on 12/12/2025

Configure Visual Studio Container Tools
You can control some aspects of how Visual Studio works with Docker containers by using
Container Tools settings. This article describes how to configure Container Tools settings that
can affect Visual Studio performance and resource usage when you work with Docker
containers.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Container Tools settings

To access the settings, select Tools > Options from the main Visual Studio menu. In the left
pane, scroll down and expand Container Tools.

General settings

The following table describes the General settings:

ﾉ Expand table
 Setting Default value Description

Prompt to install Enabled Choose whether you want to be prompted if

container runtime Docker Desktop or Podman isn't installed.
when one is not
installed

Prompt to trust Choose whether to prompt if

[Link] Core SSL the localhost SSL certificate
certificate isn't trusted in an [Link] Core
project.

Start the container Prompt me If Docker Desktop or Podman isn't started,

runtime if needed choose whether to start it automatically or
whether to prompt you.

Container runtime Auto Choose the container runtime; Docker and

Podman are supported. Choose Auto if you
want Visual Studio to detect which runtime
you're using.

） Important

If you set Trust [Link] Core SSL certificate to Never and the localhost SSL certificate
isn't trusted, HTTPS web requests might fail at run time. In that case, set Trust [Link]
Core SSL certificate to Prompt me, run your project, and indicate trust at the prompt.

Single Project or Docker Compose settings

The Container Tools Single Project and Docker Compose settings are identical.

The following table describes Single Project and Docker Compose settings:

The following settings in the Container Warmup section control how Visual Studio optimizes
performance by starting services and preparing images ahead of anticipated use.

ﾉ Expand table

Setting Default Description

value

Pull required Enabled Whether to start a background Docker pull operation when loading a
images on container project. Required images are downloaded or downloading when
project open you're ready to run your code. If you just want to browse the code, you
can set to False to avoid downloading container images you don't need.
 Setting Default Description
value

Run containers True Whether to create a container when loading a container project, so it's
on project open ready when you build and run. If you prefer to control when your container
is created, set to False.

Remove True Whether to remove containers for your solution after closing the solution
containers on or closing Visual Studio.
project close

The following settings appear in the Debugging section:

ﾉ Expand table

Setting Default Description

value

Run a service in Enabled Whether to install and run a token proxy service in the container
containers to enable to enable Azure Authentication. This service lets your apps use
Azure Authentication Azure services during development. For more information, see the
Configure Azure authentication section.

Run a service in Enabled Whether to install and run the Hot Reload service. This service
containers to enable Hot only supports running without debugging, Ctrl+F5.
Reload

Containers Window settings

The Containers Window settings apply to the Containers window in the Visual Studio IDE,
which shows information about Docker containers and images. For more information, see Use
the Containers window.

The following table describes the Containers Window settings:

ﾉ Expand table

Setting Default Description

value

Confirm before pruning Enabled Whether to prompt you when pruning unused containers.
containers

Confirm before pruning Enabled Whether to prompt you when pruning unused images.
images
 Setting Default Description
value

Confirm before removing Enabled Whether to prompt you when removing a container.
a container

Confirm before removing Enabled Whether to prompt you when removing an image.
an image

Confirm before running Enabled Whether to prompt you before starting containers from more
large number of images than 10 images at a time.

Display string format to Blank A display string format to use in the Containers window, with
use in the Containers support for {ContainerName}, {ImageName}, {ProjectName}, and
window {ContainerID} tokens.

Group containers by the Enabled Whether to group containers by the Docker Compose project
Docker Compose project they're part of.

Configure Azure authentication

If your app uses Azure services, it needs appropriate credentials to authenticate with Azure
services when it runs in a container. You can usually use your own Azure credentials during
development, but to run in the container environment, the containerized app requires the
credentials it uses in production.

Visual Studio deploys and runs a token proxy service in your single-container and Docker
Compose projects to help your apps and services authenticate in Azure. The feature requires
Azure Identity 1.9.0 or later.

With this service enabled, you can automatically use most Azure services within the container
without any added configuration or setup. Your code can use DefaultAzureCredential and
VisualStudioCredential to authenticate with Azure services the same way as outside of a
container. For more information, see the Azure Identity 1.9.0 README .

To disable this feature, set Run a service in containers to enable Azure Authentication to False
in the Container Tools Single Project or Docker Compose settings.

Ｕ Caution

Using the token proxy and enabling certain diagnostic logs presents a potential security
concern. These logs could expose authentication credentials as plain text. The following
environment variables enable these logs:
 For single container projects, MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED , which logs in
%tmp%\[Link] .

For Docker Compose projects, MS_VS_DOCKER_TOOLS_LOGGING_ENABLED , which logs in

%tmp%\[Link] .

Related content
Visual Studio Container Tools for Docker
Use the Containers window

Last updated on 10/24/2025

Deploy an [Link] container to a container
registry using Visual Studio
This tutorial walks you through using Visual Studio to publish your containerized application to
an Azure Container Registry .

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites
Install Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link]
and web development workload.

Install Docker Desktop for Windows or Podman Desktop .

Create an [Link] Core web app

The following steps guide you through creating a basic [Link] Core app that you use in this
tutorial. If you already have a project, you can skip this section.

1. In the Visual Studio start window, select Create a new project.

2. Select [Link] Core Web App, and then select Next.

3. Enter a name for your new application (or use the default name), specify the location on
disk, and then select Next.

4. Select the .NET version you want to target. If you're not sure, choose the LTS (long-term
support) release .
 5. Choose whether you want SSL support by selecting or clearing the Configure for HTTPS
checkbox.

6. Select the Enable Docker checkbox.

7. Use the Docker OS dropdown list to select the type of container you want: Windows or
Linux.

8. Select Create to complete the process.

Publish your container to Azure Container Registry

1. Right-click your project in Solution Explorer and choose Publish. The Publish dialog
opens.

2. On the Target tab, select Docker Container Registry, and then select Next.
3. On the Specific target tab, select Azure Container Registry, and then select Next.

4. On the Registry tab, select the Create new (+) option at the right:

5. Fill in your desired values in the Azure Container Registry screen.

 ﾉ Expand table

Setting Suggested Description

value

DNS Prefix Globally unique Name that uniquely identifies your container registry.
name

Subscription Your The Azure subscription to use.

subscription

Resource Your resource Name of the resource group in which to create your container
Group group registry. Select New to create a new resource group.

SKU "Standard" Select the service tier of the container registry.

Registry A nearby Choose a location in a region close to you or close to other

Location location services that you expect to use the container registry.
 6. After you enter the resource values, select Create.

Visual Studio validates the property values and creates the new container resource. When
the process completes, Visual Studio returns to the Publish dialog and selects the new
container in the list.

7. Select Finish to publish the new container.

You can now pull the container from the registry to any host capable of running Docker
images, such as Azure Container Instances.

Related content
Quickstart: Deploy a container instance in Azure using the Azure CLI

Last updated on 11/11/2025

Deploy an [Link] Core container to Azure
App Service using Visual Studio
This tutorial walks you through using Visual Studio to publish your containerized [Link] Core
web application to an Azure App Service. Azure App Service is an appropriate service for a
single-container web app hosted in Azure.

You can also deploy to Azure Container Apps. For a tutorial, see Deploy to Azure Container
Apps using Visual Studio.

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites
To complete this tutorial:

Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development workload.
Install Docker Desktop or Podman Desktop .

Create an [Link] Core web app

The following steps guide you through creating a basic [Link] Core app that will be used in
this tutorial.

1. From the Visual Studio start window, choose Create a new project.
2. Choose [Link] Core Web App (Razor pages), and choose Next.
3. Give your new application a name (or take the default) and choose Next.
4. Choose the .NET version you want to target.
5. Choose whether or not you want SSL support by using the Configure for HTTPS
checkbox.
6. Select the Enable container support checkbox.
7. Select the container type, and click Create.

Deploy the container to Azure

1. Right-click your project in Solution Explorer and choose Publish.

2. On the Publish dialog, choose the Azure target.

3. On the Specific target tab, choose the appropriate deployment target, such as Azure App
Service Container. App Service (Linux), or App Service (Windows), depending on your
container type. Choose Azure App Service Container if you want to deploy your image to
Azure Container Registry.
4. If you are not signed in to the right Azure account with the subscription you want to use,
sign in by using the button at the top left of the Publish window.

5. You can use an existing app service or create a new one by clicking on the Create new
Azure App Service link. Find your existing app service in the treeview by expanding its
resource group, or change the View setting to Resource type to sort by type.

７ Note

In Visual Studio 2022 version 17.11 and later, the default authentication method
used for publishing to Azure changed from basic authentication to using an access
token for authentication. To use basic authentication with Visual Studio 17.11 or later,
clear the checkbox Enable secure publishing (not recommended).

6. If you create a new one, a resource group and app service will be generated in Azure. You
can change the names if desired, as long as they are unique.
7. You can accept the default hosting plan or change the hosting plan now, or later in the
Azure portal. The default is S1 (small) in one of the supported regions. To create a
hosting plan, choose New next to the Hosting Plan dropdown list. The Hosting Plan
window appears.
 You can view the details about these options at Azure App Service plan overview.

8. If you chose the Azure App Service Container option, specify whether to use an existing
registry or create a new one. If you create a new one, a screen appears with settings for
the new registry. For the description of the options for SKU, see Azure Container Registry
service tiers.
9. Once you're done selecting or creating these resources, choose Finish. Your container is
deployed to Azure in the resource group and app service you selected. This process takes
a bit of time. When it's completed, the Publish tab shows information about what was
published, including the site URL.
 

10. The publishing profile is saved with all the details you selected, such as the resource
group and app service. If you chose Azure App Service Container, you might be asked to
enable the Admin user on the Container Registry instance.

11. Click on the site link to verify your app works as expected in Azure.
 12. To deploy again with the same publishing profile, use the Publish button, the Publish
button on the Web Publish Activity window, or right-click on the project in Solution
Explorer and choose the Publish item on the context-menu.

View container settings

In the Azure portal , you can open your deployed App Service.

You can view settings for your deployed App Service by opening the Container settings menu
(when you are using Visual Studio 2019 version 16.4 or later).
From there, you can view the container information, view or download logs, or set up
continuous deployment. See Azure App Service Continuous Deployment CI/CD.

Clean up resources
To remove all Azure resources associated with this tutorial, delete the resource group using the
Azure portal . To find the resource group associated with a published web application, choose
View > Other Windows > Web Publish Activity, and then choose the gear icon. The Publish
tab opens, which contains the resource group.

In the Azure portal, choose Resource groups, select the resource group to open its details
page. Verify that this is the correct resource group, then choose Remove resource group, type
the name, and choose Delete.

Related content
Azure App Service
Deploy to Azure Container Registry

Last updated on 09/10/2025

Deploy to Docker Hub
Docker Hub provides a convenient hosting service for your image repositories. You can easily
deploy to Docker Hub manually from Visual Studio.

Prerequisites
Docker Desktop .
Visual Studio with the [Link] and web development, Azure development workload,
and/or .NET desktop development workload installed.

Create a Docker account and Docker Hub

repository
Sign up for a Docker account, if you don't already have one.

If you don't have a Docker Hub repository, create one at Docker Hub .

Publish the image for a single project to Docker

Hub
1. Right-click on the project node and choose Publish.... A screen showing deployment
options appears.
2. Choose Docker Container Registry, and then choose Docker Hub.

3. Enter your Docker credentials.

4. If you are connecting to your own repository (not part of an organization), leave the
checkbox for Publish to a personal repository checked. If the repository is owned by an
organization, clear the checkbox, and enter the organization name. Enter your Docker
username and password for your Docker account that has permissions to access the
repository that you are connecting to, and then select Save.

Visual Studio attempts to deploy your image to the Docker Hub. If successful, the Publish
screen appears with the URL for the repository image, the image tag, repository, and the
build configuration (for example, Release).


 5. You can update the image at any time by clicking on the Publish button on this page. Or,
you can modify or remove the profile, by using the links underneath the URL.

Next steps
Publish to Azure Container Registry by following the steps at Deploy to Azure Container
Registry.

Set up continuous integration and delivery (CI/CD) with Azure Pipelines.

Related content
Deploy to Azure App Service
Visual Studio Container Tools.

Last updated on 12/12/2025

Deploy an app into a container in Azure or
Docker Hub
You can deploy a .NET 7 or later app without Docker Desktop or a Dockerfile. Visual Studio
provides a deployment option that handles this conveniently for you.

Prerequisites
Install Visual Studio .
A .NET 7 or later project
For Azure targets, an Azure subscription. Sign up for a free trial .
For Docker Hub, a Docker account. If you don't have one, you can sign up .

You don't need Docker Desktop or Podman Desktop.

Deploy to Docker Hub

1. Right-click on the project node and choose Publish.

2. Choose Docker Container Registry, and then Docker Hub.

3. Provide your Docker username and password. You can skip the password, if it's in the
[Link] file.
Deploy to Azure Container Registry
1. Right-click on the project node and choose Publish.

2. Choose Docker Container Registry, and then Azure Container Registry.

The app is deployed to Azure Container Registry, and Visual Studio creates a publish profile for
the selected deployment target.

Deploy to Azure Container Apps

If you have an [Link] Core 7 or later project, you can deploy it to Azure Container Apps.

1. Right-click on the project node and choose Publish, then Azure.

2. Choose Azure Container Apps (Linux).

3. Choose an existing container app or create a new one.

If you create a new one, review and modify the default app name, resource group,
location, environment, and container name, and choose Create. It might take some time
 to create the resources in Azure.

4. Choose Finish and wait for the container app to be created. If you see a message box
about enabling the Admin user on the container instance, you'll need to accept this to
continue.
When the container app has been created, Visual Studio creates a publish profile ( .pubxml file)
and displays the settings on the Publish tab.

You can access the containerized web site online using the Site link.

Next time you want to publish using the same target and settings, you can use the Publish
button on this screen. If you want to publish using different settings, use the New button. You
can repeat the entire process and save the target and other settings in a separate .pubxml file.

Clean up resources
To clean up resources, use the Azure portal or use the Azure CLI or Azure PowerShell to delete
the resource group, if you created one, or delete the resources individually.

Related content
Learn more about:

Azure Container Apps

Azure Container Registry
Docker Hub
Last updated on 09/18/2025
Customize containers in Visual Studio
You can customize your container images by editing the Dockerfile that Visual Studio generates
when you add container 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 ContainerFastModeStage 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.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Dockerfile builds in Visual Studio

７ Note

This section describes the container build process that Visual Studio uses when you
choose the Dockerfile container build type. If you're using the .NET SDK build type, the
customization options are different, and the information in this section isn't applicable.
Instead, see Containerize a .NET app with dotnet publish and use the properties
described at Customize your container to configure the container build process.

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.

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.

Dockerfile

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

The lines in the Dockerfile begin with the [Link] image from Microsoft Container Registry
([Link]) and create an intermediate image base that exposes ports 8080 and 8081,
and sets the working directory to /app .

When you're targeting .NET 7 and later, the USER $APP_UID line appears, which sets the
container to run without elevated privileges with a username obtained from the environment
variable APP_UID . The ports are 8080 and 8081, rather than 80 and 443, which require elevated
privileges.

The next stage is build , which appears as follows:

Dockerfile

# This stage is used to build the service project

FROM [Link]/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["WebApplication43/[Link]", "WebApplication43/"]
RUN dotnet restore "WebApplication43/[Link]"
COPY . .
WORKDIR "/src/WebApplication43"
RUN dotnet build "[Link]" -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:

Dockerfile
# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
RUN dotnet publish "[Link]" -c Release -o /app/publish

# 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", "[Link]"]

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.

The following table summarizes the stages used in the typical Dockerfile created by Visual
Studio:

ﾉ Expand table

Stage Description

base Creates the base runtime image where the built app is published. Settings that need to be
available at runtime go here, such as ports and environment variables. This stage is used
when running from VS in fast mode (Default for Debug configuration).

build The project is built in this stage. The .NET SDK base image is used, which has the components
required to build your project.

publish This stage derives from the build stage and publishes your project, which will be copied to
the final stage.

final This stage configures how to start the app and is used in production or when running from
VS in regular mode (Default when not using the Debug configuration).

aotdebug This stage is used as the base for the final stage when launching from VS to support
debugging in regular mode (Default when not using the Debug configuration).

７ Note
 The aotdebug stage is only supported for Linux containers. It's used in Visual Studio 2022
17.11 and later if native Ahead Of Time (AOT) deployment is enabled on the project.

Project warmup
Project warmup refers to a series of steps that happen when the Container profile is selected
for a project (that is, when a project is loaded or container support is added) in order to
improve the performance of subsequent runs (F5 or Ctrl+F5).

This behavior is configurable in the Tools > Options pane under All Settings > Container
Tools. Here are the tasks that run in the background:

Check that the container runtime (Docker Desktop or Podman) is installed and running.
Ensure that Docker Desktop is set to the same operating system as the project. (This
check isn't applicable to Podman, which only supports Linux containers.)
Pull the images in the first stage of the Dockerfile (the base stage in most Dockerfiles).
Build the Dockerfile and start the container.

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

Enable detailed container tools logs

For diagnostic purposes, you can enable certain Container Tools logs. You can enable these
logs by setting certain environment variables. For single container projects, the environment
variable is MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED , which then logs in
%tmp%\[Link] . For Docker Compose projects, the variable is

MS_VS_DOCKER_TOOLS_LOGGING_ENABLED , which then logs in

%tmp%\[Link] .

２ Warning

When logging is enabled and you're using a token proxy for Azure authentication,
authentication credentials could be logged as plain text. See Configure Azure
authentication.

Next steps
Learn about how to use the Dockerfile stages to customize the images used for debugging and
production, for example, how to install a tool on the image only when debugging. See
Configure container images for debugging.

Related content
MSBuild properties for container projects.
Dockerfile on Windows
Linux containers on Windows

Last updated on 10/24/2025

Customize container images for debugging
This article describes how you can customize your containers when you choose the Dockerfile
container build type. If you are using the .NET SDK build type, the customization options are
different, and most of the information in this section isn't applicable. Instead, see Containerize
a .NET app with dotnet publish.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Fast Mode optimizations

When you build in the 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 isn't as straightforward as simply following the steps outlined in
the Dockerfile. Building in a container is 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 or podman build with an argument that tells the
container runtime to build only the first stage in the Dockerfile (normally the base stage). You
can change that by setting the MSBuild property, ContainerFastModeStage , which replaces the
obsolete DockerfileFastModeStage . See Container Tools MSBuild properties. 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 aren't executed.

This performance optimization normally only occurs when you build in the Debug
configuration. In the Release configuration, the build occurs in the container as specified in the
Dockerfile. You can enable this behavior for the Release configuration by setting
ContainerDevelopmentMode to Fast in the project file:

XML
 <PropertyGroup Condition="'$(Configuration)' == 'Release'">
<ContainerDevelopmentMode>Fast</ContainerDevelopmentMode>
</PropertyGroup>

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

XML
<PropertyGroup>
<ContainerDevelopmentMode>Regular</ContainerDevelopmentMode>
</PropertyGroup>

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:

ﾉ Expand table

Scenario Debugger process

.NET Core apps (Linux Visual Studio downloads vsdbg and maps it to the container, then it gets
containers) called with your program and arguments (that is, dotnet [Link] ).

.NET Core apps Visual Studio uses onecoremsvsmon and maps it to the container, runs it as the
(Windows containers) entry point.

For information on [Link] , see Offroad debugging of .NET Core on Linux and OS X from
Visual Studio .

Modify container image for debugging and

production
To modify the container image for both debugging and production, modify the first stage in
the Dockerfile, usually called the base stage. Refer to the Dockerfile reference in the Docker
documentation for information about Dockerfile commands.
  Tip

If your project uses the ContainerFastModeStage (or the obsolete equivalent

DockerfileFastModeStage ) MSBuild property, you should select an appropriate stage for

customization that flows to the final stage and the ContainerFastModeStage , if possible.
See Container Tools build properties.

Dockerfile
# This stage is used when running from VS in fast mode (Default for Debug
configuration)
FROM [Link]/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081
# <add your commands here>

# This stage is used to build the service project

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

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
RUN dotnet publish "[Link]" -c Release -o /app/publish

# 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", "[Link]"]

Modify container image only for debugging

You can customize your containers in certain ways to help in debugging, such as installing
something for diagnostic purposes, without affecting production builds.

To modify the container only for debugging, create a stage and then use the MSBuild property
ContainerFastModeStage 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.
 ７ Note

The instructions here apply to the single-container case. You can also do the same thing
for multiple containers with Docker Compose, but the techniques required for Docker
Compose are slightly different. For example, the stage is controlled by a setting in the
[Link] file.

In the following example, we install the package procps-ng , but only in debug mode. This
package supplies the command pidof , which Visual Studio requires (when targeting .NET 5
and earlier) 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 doesn't need to inherit
from the build or publish stage, it can inherit directly from the base stage, because Visual
Studio mounts a volume that contains everything needed to run the app, as described earlier in
this article.

Dockerfile
#See [Link] to understand 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 [Link]/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

FROM base AS debug

RUN tdnf install procps-ng -y

# This stage is used to build the service project

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

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
RUN dotnet publish "[Link]" -c Release -o /app/publish

# 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", "[Link]"]

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

XML

<PropertyGroup>
<!-- other property settings -->
<ContainerFastModeStage>debug</ContainerFastModeStage>
</PropertyGroup>

Customize debugging images with AOT deployment

To support native AOT deployment, the GNU debugger (GDB) is installed, but only on the
image used when debugging, not the final runtime image. The Dockerfile includes a build
argument LAUNCHING_FROM_VS which can be true or false . If true , the aotdebug stage is used,
which is where GDB is installed. Note that Visual Studio only supports native AOT and GDB for
Linux containers.

Dockerfile
# These ARGs allow for swapping out the base used to make the final image when
debugging from VS
ARG LAUNCHING_FROM_VS
# This sets the base image for final, but only if LAUNCHING_FROM_VS has been defined
ARG FINAL_BASE_IMAGE=${LAUNCHING_FROM_VS:+aotdebug}

# ... (other stages omitted)

# This stage is used as the base for the final stage when launching from VS to
support debugging in regular mode (Default when not using the Debug configuration)
FROM base as aotdebug
USER root
# Install GDB to support native debugging
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
gdb
USER app

# This stage is used in production or when running from VS in regular mode (Default
when not using the Debug configuration)
FROM ${FINAL_BASE_IMAGE:-[Link]/dotnet/runtime-deps:8.0} AS final
WORKDIR /app
EXPOSE 8080
COPY --from=publish /app/publish .
ENTRYPOINT ["./WebApplication1"]
You can use aotstage in the Dockerfile to customize the image used at debug time, without
affecting the final image used when not launching from Visual Studio, or in production. For
example, you could install a tool for use only during debugging.

Related content
Customize Docker containers in Visual Studio
Build a container project from the command line

Last updated on 09/18/2025

Customize container 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.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Volume mounts in Visual Studio container images

Here are the volumes that are mounted in your container. What you see in your containers
might differ depending on the minor version of Visual Studio you're using.

ﾉ Expand table

Volume Description

App folder Contains the project folder where the Dockerfile is located.

NuGet Contains the NuGet packages and fallback folders that are read from the
packages obj{project}.[Link] file in the project.
folders

Remote Contains the bits required to run the debugger in the container depending on the
debugger project type. For more information, see Customize container images for debugging.

Source folder Contains the build context that is passed to Docker commands.

VSTools Contains Visual Studio tools that support working with the container, including support
for the debugger, the Containers window, handling Azure tokens, the Hot Reload agent,
and the Distroless Helper.

For .NET 8 and later, additional mount points at root and for the app user that contain user
secrets and the HTTPS certificate might also be present.

７ Note
 If you're using Docker Engine in Windows Subsystem for Linux (WSL) without Docker
Desktop, set the environment variable VSCT_WslDaemon=1 to have Visual Studio use WSL
paths when creating volume mounts. The NuGet package
[Link] 1.20.0-Preview 1 is also
required.

For [Link] core web apps, there might be two additional folders for the SSL certificate and
the user secrets, which is explained in more detail at Use SSL for containerized [Link] Core
apps

Mount a container volume

You can mount another volume by specifying command-line arguments for the container
runtime, [Link] or [Link].

1. Open [Link] for the containerized project.

2. To specify a new command-line argument, add the JSON containerRunArguments , and

provide the -v or --mount syntax. For example, the following syntax creates a volume
myvolume and mounts it in the container in the folder /scratch .

JSON

"containerRunArguments": "-v myvolume:/scratch"

Refer to the container runtime provider's documentation for the command-line syntax for
the Docker -v or --mount options, or the Podman -v option and the Podman --
mount option .

Related content
Customize containers in Visual Studio
Dockerfile on Windows
Linux containers on Windows

Last updated on 01/07/2026

Build a container project from the
command line
If you want to build a container project with a Dockerfile outside of Visual Studio, you can use
docker build (or podman build ), or dotnet publish /t:PublishContainer to build from the

command line.

If you're using the .NET SDK build type, you don't have a Dockerfile, so you can't use docker
build or podman build ; instead, use dotnet publish /t:PublishContainer to build on the

command line.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Use Docker build or Podman build

To build a containerized solution from the command line, you can usually use the command
docker build <context> (or podman 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, the default is to
use the folder that contains the solution file (.sln or .slnx). Expressed as a relative path, this
argument is typically ".." for a Dockerfile in a project folder, and the solution file in its parent
folder.

Windows Command Prompt

docker build -f Dockerfile ..

Windows Command Prompt

podman build -f Dockerfile ..

You can set the build context in the project file by setting the ContainerBuildContext property.
For example,
 XML

<PropertyGroup>
<ContainerBuildContext>contextfolder</ContainerBuildContext>
</PropertyGroup>

Relative paths in the Dockerfile are relative to the build context, so if you change the context,
be sure to update the relative paths accordingly.

When you add container support to a project, you can specify a folder for the build context. If
you want to change the build context, you could delete the Dockerfile (if it doesn't have other
changes you want to keep), and rerun Add Container Support, this time specifying the new
build context. The new Dockerfile will have relative paths updated to correspond to the new
build context.

Use MSBuild

７ Note

This section describes how you can customize your containers when you choose the
Dockerfile container build type. If you are using the .NET SDK build type, the
customization options are different, and the information in this article isn't applicable.
Instead, see Containerize a .NET app with dotnet publish.

To build an image for single Docker container project, you can use MSBuild with the
/t:ContainerBuild command option. This command tells MSBuild to build the target

ContainerBuild rather than the default target Build . For example:

Windows Command Prompt

MSBuild [Link] /t:ContainerBuild /p:Configuration=Release

You 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 Customize container images for debugging.

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

Windows Command Prompt

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

[Link]
To view the MSBuild logs, see Obtaining build logs with MSBuild.

Build from the command line

Visual Studio uses Fast Mode (if enabled) to produce a container image configured to work
best for development and debugging, so we don't recommend copying the docker build or
podman build commands from the Output window after a Fast Mode build. To build a standard

image without nonstandard optimizations, you can right-click on the Dockerfile and choose the
Build Image option.

Visual Studio uses the dev tag to designate images that it has specially prepared to optimize
the startup time during debugging. However, these images shouldn't be used outside of the
context of Visual Studio. This tag is an indication the images have nonstandard modifications
and customizations, for example, to support Fast Mode debugging. See Customize Docker
containers in Visual Studio.

Related content
MSBuild properties for container projects.
MSBuild

Last updated on 09/18/2025

Set the container entry point
A container entry point is a process that is configured to run when a container is started.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Entry point by project type

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

ﾉ Expand table

Container Entry point

type

Linux For .NET 6 and later, the entry point is dotnet --roll-forward Major
containers /VSTools/DistrolessHelper/[Link] --wait . For .NET 5 and earlier, the entry
point is tail -f /dev/null . These processes use an infinite wait to keep the container
running when the app is not running. When the app is launched, with or without
debugging, it's the debugger that is responsible to run the app (that is, dotnet [Link] ).
DistrolessHelper monitors the app process, and exits with the app's exit code when the
app process ends.

Windows The entry point is something like C:\remote_debugger\x64\[Link] /noauth /anyuser

containers /silent /nostatus which runs the debugger, so it's listening for connections.

The container entry point can only be modified in Docker Compose projects, not in single-
container projects. See Docker Compose properties - Customize the app startup process.

Related content
MSBuild properties for container projects.
MSBuild
Dockerfile on Windows
Linux containers on Windows
Last updated on 09/18/2025
Use SSL for containerized [Link] Core
apps
SSL (Secure Sockets Layer) provides secure connections over HTTP (HTTPS). This method of
securing connections uses a certificate, and in a containerized app, the port mappings are
different for secured and unsecured entry points.

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Security for multicontainer apps

Multicontainer app architectures vary depending on security requirements. Some app designs
use HTTPS for external endpoints, but HTTP for internal communication from one container to
another. High-security environments might use HTTPS for all communications, even between
containers that are only accessible within a secure outer perimeter.

Ports and port mappings

The Dockerfile contains directives for exposing ports to external traffic over unsecured HTTP or
secure HTTPS. Also, .NET 8 and later run the containerized app as a typical user, but in earlier
.NET versions, containerized apps run as administrator. When running as administrator, apps
have access to the privileged ports 80 for HTTP traffic and 443 HTTPS traffic. When apps run as
users without elevated privileges, they use ports 8080 for HTTP and 8081 for HTTPS. The ports
appear in the EXPOSE commands in the Dockerfile that Visual Studio generates. The ports in
the container specified in the Dockerfile are mapped to host ports using the mappings
specified in the launch settings file. See Container tools launch settings. When the container is
running, you can view the port mappings in the Containers window. See View and diagnose
containers.

Certificates
Container tools in Visual Studio support debugging an SSL-enabled [Link] 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%\[Link]\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%\[Link]\Https

[Link] Core looks for a certificate that matches the assembly name under the Https folder,
which is why it's 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:

JSON

{
"Kestrel": {
"Certificates": {
"Default": {
"Path": "c:\\app\\[Link]",
"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 [Link] Core apps in containers, see Hosting
[Link] Core images with Docker over HTTPS.

For a code sample that demonstrates creating custom certificates for a multi-service app that
are trusted on the host and in the containers for HTTPS service-to-service communication, see
CertExample .

If you plan to deploy your containerized app to Azure, see Configure HTTPS when deploying
containerized applications to Azure.
Last updated on 09/18/2025
Configure HTTPS when deploying
containerized applications to Azure
When you deploy a containerized application, you typically use the HTTPS protocol for
encrypted, secure communication. The secure communication is implemented by Transport
Layer Security (TLS), which replaces the earlier method using Secure Sockets Layer (SSL).

Prerequisites
Docker Desktop or Podman Desktop .
Visual Studio , or for Podman support, Visual Studio 2026 , with the [Link] and web
development, Azure development workload, and/or .NET desktop development
workload installed.

Devtest certificates
During development, Visual Studio uses a self-signed certificate, sometimes called a devtest
certificate. You get a prompt asking you to trust the certificate when you launch the application
on your local machine for the first time. This is acceptable for development and testing, but
when you deploy to Azure and expose your application on a custom domain, you need to
switch to a certificate issued by a Certificate Authority (CA), either Azure or a third-party CA.

Security for deployment options in Azure

Many Azure services simplify the configuration and management burden by handling
certificate management automatically. The configuration and procedure for setting up TLS for
containers in Azure depends on the service you deploy to.

In general, Azure services can support multiple ways of obtaining and storing certificates. You
may obtain trusted certificates from Azure's own certificate authority (CA), or you may upload
private trusted certificates issued by a third-party CA. You may make use of the service's own
certificate store, or you may use Azure Key Vault to store the certificate, along with other
secrets.

The following table shows the services and includes links that explain how HTTPS security
works when you deploy to these services and how-to guides for managing the certificates.

ﾉ Expand table
 Azure Notes
Service

Azure App Azure App Service is a suitable deployment service for a single container that provides a
Service default experience that means you get a secure endpoint with a trusted certificate
provided by Azure without any additional overhead. For greater control, you can choose
from multiple options for obtaining and storing the certificate. You may use your own
trusted certificate obtained from a third-party CA instead of the default trusted certificate
provided by Azure. Optionally, you can store certificates in Azure Key Vault. See App
Service TLS overview.

Azure Azure Container Apps is a suitable hosting service for containerized apps using one or
Container more containers. Like Azure App Service, it provides a default experience that uses
Apps trusted Azure-provided certificates automatically, but also provides a range of
networking architecture options to support different scenarios. See Networking in Azure
Container Apps.

Azure To configure HTTPS public endpoint for a container hosted in Azure Container Instances,
Container see Enable a TLS endpoint in a sidecar container. This option minimizes the impact to the
Instances container itself.

Azure See the guidance in the AKS documentation for setting up TLS for an ingress to your
Kubernetes cluster. AKS provides the most advanced management capabilities, handling rotation and
Service (AKS) renewal of certificates with maximum flexibility.

Network security options for multiple containers

If your scenario involves multiple containers, you have the option of securing the ingress traffic
only (that is, at the externally facing load balancer or reverse proxy), or you can apply secure
communications between every container in the application. The latter option provides security
for deeper layers of the system, even if there's a breach in the outer layer. Using HTTPS for all
container-to-container communication is outside the scope of this article.

For Azure Container Apps, you can configure ingress which uses HTTPS for external callers, and
within the network of multiple containers, use HTTP or TCP. For secure communication
between containers, you can use mTLS (mutual TLS), which requires certificates on both sides
of a request, client and server, or between microservices. See Ingress in Azure Container Apps
and Configure client certificate authentication in Azure Container Apps.

Related content
Deploy an [Link] Core container to Azure App Service using Visual Studio
Use SSL for containerized [Link] Core apps
Last updated on 11/18/2025
Troubleshoot Visual Studio
development with Docker
Article • 02/20/2025

Applies to: Visual Studio

When you're working with Visual Studio Container Tools, you may encounter issues
while building or debugging your application. This article introduces some common
troubleshooting steps for the issues.

Volume sharing is not enabled. Enable volume

sharing in the Docker CE for Windows settings
(Linux containers only)
File sharing only needs to be managed if you're using Hyper-V with Docker. If you're
using WSL 2, the following steps aren't necessary, and the file sharing option won't be
visible. To resolve this issue:

1. Right-click Docker for Windows in the notification area, and then select Settings.

2. Select Resources > File Sharing and share the folder that needs to be accessed.
Sharing your entire system drive is possible but not recommended.

 Tip
 Visual Studio prompts you when Shared Drives aren't configured.

Problems with paths on Windows containers

When you use file paths that are specific to Linux on a Windows container, you might
encounter various file input or output (I/O) errors. If so, check the value of the
environment variable VSCT_WslDaemon . If the variable is set, Visual Studio attempts to use
Windows Subsystem for Linux (WSL) paths to refer to the Windows files for creating
volumes. This is necessary for Docker in WSL, but doesn't work with Docker Desktop on
Windows. This environment variable should always be unset if you use Windows
containers.

Unable to start debugging

One reason for this issue could be related to having stale debugging components in
your user profile folder. Execute the following commands to remove these folders so
that the latest debugging components are downloaded on the next debug session.

del %userprofile%\vsdbg

del %userprofile%\onecoremsvsmon

Errors specific to networking when debugging

your application
Try executing the script downloadable from Cleanup Container Host Networking ,
which will refresh the network-related components on your host machine.

Mounts denied
When using Docker for macOS, you might encounter an error referencing the folder
/usr/local/share/dotnet/sdk/NuGetFallbackFolder. Add the folder to the File Sharing tab
in Docker.

Docker users group

You might encounter the following error in Visual Studio when working with containers:
 The current user must be in the 'docker-users' group to use Docker Desktop. Add
yourself to the 'docker-users' group and then log out of Windows.

You must be a member of the 'docker-users' group in order to have permissions to work
with Docker containers. To add yourself to the group in Windows 10 or later, follow
these steps:

1. From the Start menu, open Computer Management.

2. Expand Local Users and Groups, and select Groups.
3. Find the docker-users group, right-click and select Add to group.
4. Add your user account or accounts.
5. Sign out and sign back in again for these changes to take effect.

You can also use the net localgroup command at the Administrator command prompt
to add users to specific groups.

Windows Command Prompt

net localgroup docker-users DOMAIN\username /add

In PowerShell, use the Add-LocalGroupMember function.

Low disk space

By default, Docker stores images in the %ProgramData%/Docker/ folder, which is
typically on the system drive, C:\ProgramData\Docker\. To prevent images from taking
up valuable space on the system drive, you can change the image folder location. To do
so:

1. Right-click on the Docker icon on the task bar and select Settings.

2. Select Docker Engine.

3. In the editing pane, add the graph property setting with the value of your desired
location for Docker images:

JSON

"graph": "D:\\mypath\\images"
 

4. Select Apply & Restart. These steps modify the configuration file at
%ProgramData%\docker\config\[Link]. Previously built images aren't moved.

Container type mismatch

When adding Docker support to a project, you choose either a Windows or a Linux
container. If the Docker Server host isn't configured to run the same container type as
the project target, you see an error similar to:

To resolve this issue, right-click the Docker for Windows icon in the System Tray and
select Switch to Windows containers... or Switch to Linux containers....

Other issues
For any other issues you encounter, see Microsoft/DockerTools issues.

References
 Container Tools error messages

Feedback
Was this page helpful?  Yes  No

Provide product feedback

Container Tools build properties
You can customize how Visual Studio builds your container projects by setting the properties that MSBuild uses to build your
project. For example, you can change the name of the Dockerfile, specify tags and labels for your images, provide additional
arguments passed to Docker commands, and control whether Visual Studio does certain performance optimizations such as
building outside of the container environment. You can also set debugging properties such as the name of the executable to
launch, and the command line arguments to provide.

To set the value of a property, edit the project file. For example, suppose your Dockerfile is named MyDockerfile. You can set the
DockerfilePath property in the project file as follows.

XML
<PropertyGroup>
<DockerfilePath>MyDockerfile</DockerfilePath>
</PropertyGroup>

７ Note

The property DockerfilePath replaces the deprecated property DockerfileFile , which is still supported in the current
version of Visual Studio.

You can add the property setting to an existing PropertyGroup element, or if there isn't one, create a new PropertyGroup element.

Properties for .NET SDK projects

This section describes the MSBuild properties that apply when you choose the .NET SDK container build type.

There is just one property, EnableSdkContainerDebugging , in the project file that is needed for .NET SDK containerized projects. It
must be set to True for .NET SDK projects to enable debugging.

XML
<PropertyGroup>
<EnableSdkContainerDebugging>True</EnableSdkContainerDebugging>
</PropertyGroup>

Properties for Dockerfile projects

This section describes the MSBuild properties that apply when you choose the Dockerfile container build type.

The following table shows the MSBuild properties available for Dockerfile projects. The NuGet package version applies to
[Link] .

Some of the properties and item lists in the following table are equivalent replacements for obsolete properties. In that case, the
obsolete property that it replaces is also named. We recommend updating projects to use the currently supported properties.
Support for obsolete properties might be removed in a future update of Visual Studio.

Some properties listed as obsolete are replaced by equivalent values in [Link], and one is replaced by MSBuild item
list.

ﾉ Expand table

Property name Description Default value Minimum NuGet package version

ContainerDevelopmentMode Controls whether "build-on- Fast 1.0.1872750

host" optimization ("Fast
Property name Description Default value Minimum NuGet package version

Mode" debugging) is
enabled. Allowed values are
Fast and Regular.

ContainerVsDbgPath The path for VSDBG %USERPROFILE%\vsdbg\vs2017u5 1.0.1985401

debugger.

ContainerLabel The default set of labels [Link]- 1.23.0 for ContainerLabel

applied to the Docker by=visual-
(replaces DockerImageLabels ) image. studio;[Link]- 1.5.4 for DockerImageLabels
[Link]-
ContainerLabel is an name=$(MSBuildProjectName)
MSBuild item list, not a
property.

ContainerFastModeProjectMountDirectory In Fast Mode, this property C:\app (Windows) or /app 1.23.0 for
controls where the project (Linux) ContainerFastModeProjectMountDirectory
(replaces output directory is volume-
DockerFastModeProjectMountDirectory ) mounted into the running 1.9.2 for
container. DockerFastModeProjectMountDirectory

ContainerBuildArguments Additional arguments Not applicable. 1.23.0 for ContainerBuildArguements

passed to the container
(replaces DockerfileBuildArguments ) build command. See Docker 1.0.1872750 for
build or podman build . DockerfileBuildArguments

ContainerBuildContext The default context used Set by Visual Studio when 1.23.0 for ContainerBuildContext
when building the Docker Docker support is added to a
(replaces DockerfileContext ) image, as a path relative to project. It's set to the relative 1.0.1872750 for DockerfileContext
the Dockerfile. path to the solution folder
(usually "..").

ContainerFastModeStage The Dockerfile stage (that is, First stage found in the -
target) to be used when Dockerfile (usually base)
(replaces DockerfileFastModeStage ) building the image in debug
mode.

ContainerIncludeDefaultImageLabels If set to false , doesn't True 1.23.0 for

(replaces: include default image tags ContainerIncludeDefaultImageLabels
DockerIncludeDefaultImageLabels ) [Link]-
by=visual-studio and
[Link]-
[Link]-
name=$(MSBuildProjectName) .

ContainerLabelBuiltImages (replaces Include labels on built True 1.23.0 for ContainerLabelBuiltImages

DockerLabelBuiltImages ) images. If false, no labels
are added, including user-
defined labels.

DockerfilePath Describes the default Dockerfile 1.23.0 for DockerfilePath

Dockerfile to use to
(replaces DockerfileFile ) build/run the container for 1.0.1872750 for DockerfileFile
the project.

ContainerRepository The repository to use in the The assembly name. 1.23.0 for ContainerRepository
label, for example
(replaces DockerRepository ) webapplication1 in the label
webapplication1:dev .

ContainerImageTag or The tag to use when Assembly name after 1.23.0 for ContainerImageTag ,
ContainerImageTags building the image. In stripping nonalphanumeric ContainerImageTags
debugging, a ":dev" is characters with the following
(replaces DockerfileTag ) appended to the tag. rules: 1.0.1872750 for DockerfileTag .
If the resultant tag is all
numeric, then "image" is
 Property name Description Default value Minimum NuGet package version

inserted as a prefix (for

example, image2314)
If the resultant tag is an
empty string, then "image" is
used as the tag.

DockerDebuggeeArguments When debugging, the - 1.7.8

debugger is instructed to
(obsolete, use commandLineArgs in pass these arguments to the
[Link]) launched executable.

DockerDebuggeeProgram When debugging, the - 1.7.8

debugger is instructed to
(obsolete, use executablePath in launch this executable.
[Link])

DockerDebuggeeKillProgram This command is used to kill - 1.7.8

the running process in a
container.

DockerDebuggeeWorkingDirectory When debugging, the C:\app (Windows) or /app 1.7.8

debugger is instructed to (Linux)
(obsolete; use workingDirectory in use this path as the working
[Link]) directory.

DockerDefaultTargetOS The default target operating Set by Visual Studio. 1.0.1985401

system used when building
the Docker image.

DockerfileRunArguments Additional arguments Not applicable. 1.0.1872750

passed to the Docker run
(obsolete, use containerRunArguments in command.
[Link])

DockerfileRunEnvironmentFiles Semicolon-delimited list of Not applicable. 1.0.1872750

environment files applied
(obsolete, use during Docker run.
containerRunEnvironmentFiles in
[Link])

ContainerRepository and ContainerImageTag (or ContainerImageTags ) provide the ability to specify the two parts of an image

label, the repository and one or more tags (for example, webapp1:alpha ). In previous versions of Visual Studio, you could use the
DockerfileTag property to specify the repository and a single tag, but this had limitations, for example, there was no ability to

specify multiple tags. The property DockerfileTag is obsolete; projects should now use ContainerRepository and
ContainerImageTag , and the current version also supports ContainerImageTags for multiple tags.

In previous Visual Studio versions, the syntax was <DockerfileTag>webapp1:alpha</DockerfileTag> . The current equivalent is
<ContainerRepository>webapp1</ContainerRespository> and <ContainerImageTag>alpha</ContainerImageTag> , or

<ContainerImageTags>alpha;latest</ContainerImageTags> if you want multiple tags.

Example
The following project file shows examples of some of these settings.

XML
<Project Sdk="[Link]">

<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
 <UserSecretsId>8c7ab9a5-d578-4c40-8b6d-54d174002229</UserSecretsId>
<DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
<!-- By default, Visual Studio uses the folder above the Dockerfile.
The path is relative to the Dockerfile, so here the context is
set to the same folder as the Dockerfile. -->
<ContainerBuildContext>.</ContainerBuildContext>
<!-- Set `docker run` arguments to mount a volume -->
<DockerfileRunArguments>-v $(MSBuildProjectDirectory)/host-folder:/container-folder:ro</DockerfileRunArguments>
<!-- Set `docker build` arguments to add a custom tag -->
<ContainerBuildArguments>-t contoso/front-end:v2.0</ContainerBuildArguments>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="[Link]" Version="1.20.1" />
</ItemGroup>

</Project>

７ Note

The build context, which you can set by providing a value for ContainerBuildContext (or DockerfileContext ), is usually
different in Visual Studio for projects from what docker build (or podman build ) uses when you run it from the command
line. The departure from the behavior of the build command line is necessary to ensure that build artifacts at the solution
level can be included.

When you call docker build (or podman build ), you always specify a build context, and you can optionally specify a path to
the Dockerfile. The default is that the Dockerfile is in the root of the context, but you can use the -f flag to specify an
alternate location. For example, you can build with docker build -f Dockerfile .. from the project directory, or docker
build -f ProjectName/Dockerfile . from the solution directory.

Next steps
For information on MSBuild properties generally, see MSBuild Properties.

See also
Docker Compose build properties

Container Tools launch settings

MSBuild reserved and well-known properties

Last updated on 09/18/2025

Docker Compose build properties
In addition to the properties that control individual Docker projects, described in Container
Tools build properties, you can also customize how Visual Studio builds your Docker Compose
projects by setting the Docker Compose properties that MSBuild uses to build your solution.
You can also control how the Visual Studio debugger runs your Docker Compose apps by
setting file labels in Docker Compose configuration files.

How to set the MSBuild properties

To set the value of a property, edit the project file. For Docker Compose properties, this project
file is the one with a .dcproj extension, unless otherwise indicated in the table in the next
section. For example, suppose you want to specify to launch the browser when you start
debugging. You can set the DockerLaunchAction property in the .dcproj project file as follows.

XML

<PropertyGroup>
<DockerLaunchAction>LaunchBrowser</DockerLaunchAction>
</PropertyGroup>

You can add the property setting to an existing PropertyGroup element, or if there isn't one,
create a new PropertyGroup element.

Docker Compose MSBuild properties

The following table shows the MSBuild properties available for Docker Compose projects
( .dcproj files).

ﾉ Expand table

Property name Description

AdditionalComposeFilePaths Specifies additional compose files in a semicolon-delimited list to be

sent out to [Link] for all commands. Relative paths
from the Docker Compose project file (dcproj) are allowed.

DependencyAwareStart Enables a different way of launching the app that supports the Docker
Compose properties depends_on and healthcheck , which control
service startup order and health checks.

Requires Visual Studio 17.13 or later.

Property name Description

Default value: False

DockerComposeBaseFilePath Specifies the first part of the filenames of the Docker Compose files,
without the .yml extension. For example:
1. DockerComposeBaseFilePath = null/undefined: use the base file
path docker-compose , and files will be named [Link] and
[Link].
2. DockerComposeBaseFilePath = mydockercompose: files will be
named [Link] and [Link].
3. DockerComposeBaseFilePath = ..\mydockercompose: files will be up
one level.

Default value: docker-compose

DockerComposeBuildArguments Specifies the extra parameters to pass to the docker-compose build

command. For example, --parallel --pull .

DockerComposeDownArguments Specifies the extra parameters to pass to the docker-compose down

command. For example, --timeout 500 .

DockerComposeEnvFilePath The relative path to an .env file that's passed to docker compose
commands via --env-file . See Use the env_file attribute .

Default value: Empty

DockerComposeProjectName If specified, overrides the project name for a Docker Compose

project.

Default value: "dockercompose" + auto-generated hash

DockerComposeProjectsToIgnore Specifies projects to be ignored by Docker Compose tools during

debug. This property can be used for any project. File paths can be
specified one of two ways:
1. Relative to dcproj. For example, <DockerComposeProjectsToIgnore>
path\to\[Link] </DockerComposeProjectsToIgnore> .
2. Absolute paths.
Note: The paths should be separated by the delimiter character ; .

DockerComposeUpArguments Specifies the extra parameters to pass to the docker-compose up

command. For example, --timeout 500 .

DockerDevelopmentMode Controls whether the user project is built in the container. The
allowed values of Fast or Regular control which stages are built in a
Dockerfile. The Debug configuration is Fast mode by default and
Regular mode otherwise.

Default value: Fast

 Property name Description

DockerLaunchAction Specifies the launch action to perform on F5 or Ctrl+F5. Allowed

values are None, LaunchBrowser, and LaunchWCFTestClient.

Default value: None

DockerLaunchBrowser Indicates whether to launch the browser. Ignored if

DockerLaunchAction is specified.

Default value: False

DockerServiceName If DockerLaunchAction or DockerLaunchBrowser are specified, then

DockerServiceName specifies which service referenced in the docker-
compose file gets launched.

DockerServiceUrl The URL to use when launching the browser. Valid replacement
tokens are "{ServiceIPAddress}", "{ServicePort}", and "{Scheme}". For
example: {Scheme}://{ServiceIPAddress}:{ServicePort}

DockerTargetOS The target OS used when building the Docker image.

In addition, the property DockerComposeProjectPath in a .csproj or .vbproj project file

specifies the relative path to the Docker Compose project ( .dcproj ) file. Set this property when
publishing the service project to find the associated image build settings stored in the docker-
[Link] file.

Example
If you change the location of the docker-compose files, by setting DockerComposeBaseFilePath to
a relative path, then you also need to make sure that the build context is changed so that it
references the solution folder. For example, if your docker-compose file is a folder called
DockerComposeFiles, then Docker Compose file should set the build context to ".." or "../..",
depending on where it is relative to the solution folder.

XML
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" Sdk="[Link]">
<PropertyGroup Label="Globals">
<ProjectVersion>2.1</ProjectVersion>
<DockerTargetOS>Windows</DockerTargetOS>
<ProjectGuid>154022c1-8014-4e9d-bd78-6ff46670ffa4</ProjectGuid>
<DockerLaunchAction>LaunchBrowser</DockerLaunchAction>
<DockerServiceUrl>{Scheme}://{ServiceIPAddress}{ServicePort}</DockerServiceUrl>
<DockerServiceName>webapplication1</DockerServiceName>
 <DockerComposeBaseFilePath>DockerComposeFiles\mydockercompose</DockerComposeBaseFile
Path>

<AdditionalComposeFilePaths>AdditionalComposeFiles\[Link]</Addition
alComposeFilePaths>
</PropertyGroup>
<ItemGroup>
<None Include="DockerComposeFiles\[Link]">
<DependentUpon>DockerComposeFiles\[Link]</DependentUpon>
</None>
<None Include="DockerComposeFiles\[Link]" />
<None Include=".dockerignore" />
</ItemGroup>
</Project>

The [Link] file should look like this, with the build context set to the relative
path of the solution folder (in this case, .. ).

yml
version: '3.4'

services:
webapplication1:
image: ${DOCKER_REGISTRY-}webapplication1
build:
context: ..
dockerfile: WebApplication1\Dockerfile

７ Note

DockerComposeBuildArguments, DockerComposeDownArguments, and

DockerComposeUpArguments are new in Visual Studio 2019 version 16.3.

Overriding Visual Studio's Docker Compose

configuration
Typically [Link] is used to override certain settings in docker-
[Link]. Additionally, Visual Studio generates override files [Link]
(for Fast mode) and [Link] (for Regular mode) files with settings that
are specific to running the application inside Visual Studio. You can override these Visual Studio
settings by placing a file named [Link] (for Fast mode) or docker-
[Link] (for Regular mode) in the same directory as your [Link]
file. Right click the Docker Compose project and select Open Folder in File Explorer , then use
Add > Existing Item to add the file to your Docker Compose project.
  Tip

To find out the default values for any of the Visual Studio settings, look in the intermediate
output directory (for example, obj/Docker) for [Link] or docker-
[Link]. These files are generated by Visual Studio and should not be
modified.

Docker Compose file labels

In [Link] or [Link], you can define override-
specific labels as follows:

yml
services:
webapplication1:
labels:
[Link]: "C:\\my_app_folder"

Use double quotes around the values, as in the preceding example, and use the backslash as
an escape character for backslashes in paths.

ﾉ Expand table

Label name Description

[Link] The program launched when starting

debugging. For .NET Core apps, this setting is
typically dotnet.

[Link] The arguments passed to the program when

starting debugging. For .NET Core apps,
these arguments are typically additional
search paths for NuGet packages followed by
the path to the project's output assembly.

[Link] The directory used as the starting directory

when starting debugging. This setting is
typically /app for Linux containers, or C:\app
for Windows containers.

[Link] This command is used to stop the debuggee

program that's running inside of the
container (when necessary).
 Label name Description

[Link] The program launched when you use Start

without debugging (Ctrl+F5) in an Azure
functions project that runs in an isolated
process. Typically both F5 and Ctrl+F5 uses
the same program, but if any project type like
Azure Functions in an isolated process
requires a different program than F5, then
this will be used.

[Link] The arguments passed to the program when

you use Start without debugging (Ctrl+F5)
in an Azure functions project that runs in an
isolated process.

[Link]-name The name of the project, which helps Visual

Studio find the project if the project is not in
the same folder as the Dockerfile.

[Link]-query The path and query used by the containers

window when opening links in the ports tab.

Requires Visual Studio 17.13 or later.

Customize the Docker build process

You can declare which stage to build in your Dockerfile by using the target setting in the
build property. This override can be used in only the [Link] or docker-

[Link]

yml
services:
webapplication1:
build:
target: customStage
labels:
...

Customize the app startup process

You can run a command or custom script before launching your app by using the entrypoint
setting, and making it dependent on the DockerDevelopmentMode . For example, if you need to
set up a certificate only in Fast mode by running update-ca-certificates , but not in Regular
mode, you could add the following code in only [Link]:
 yml
services:
webapplication1:
entrypoint: "sh -c 'update-ca-certificates && tail -f /dev/null'"
labels:
...

For more information, see Container entry point

Next steps
For information on MSBuild properties generally, see MSBuild Properties.

See also
Container Tools build properties

Container Tools launch settings

Manage launch profiles for Docker Compose in Visual Studio

MSBuild reserved and well-known properties

Last updated on 03/31/2025

Container Tools launch settings
In the Properties folder in an [Link] Core project, you can find the [Link] file,
which contains settings that control how your web app is started on your development
machine. For detailed information on how this file is used in [Link] development, see Use
multiple environments in [Link] Core.

You can edit this file directly, but in Visual Studio IDE, you can also edit the properties in this
file through the UI. Choose the dropdown list next to the launch option (for example, Docker
or .NET SDK ), and then choose Debug Properties for a single-container project.

For Docker Compose, choose Manage Docker Compose Launch Settings, and see Launch a
subset of compose services.

In [Link], the settings in the Docker section are related to how Visual Studio
handles containerized apps.

JSON
"Docker (Dockerfile)": {
"commandName": "Docker",
"launchBrowser": true,
"launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}",
"environmentVariables": {
"ASPNETCORE_HTTPS_PORTS": "8081",
"ASPNETCORE_HTTP_PORTS": "8080"
 },
"publishAllPorts": true,
"useSSL": true
}

You can also use "Container (Dockerfile)" , which is more accurate if you want to use Podman,
although "Docker (Dockerfile)" works for both Docker and Podman container runtimes.

The commandName setting identifies that this section applies to Container Tools.

Most of the settings in [Link] are available and applicable whether you're using
a Dockerfile, or using the .NET SDK's built-in container build support (available for .NET 7 and
later).

The following table shows the properties that can be set in this section:

ﾉ Expand table

Property in Setting name in Example Description

Debug [Link]
Profile UI

Command commandLineArgs "commandLineArgs": "--mysetting These command-line

line myvalue" arguments for starting
arguments your app are used
when launching your
project in the
container.

Container containerRunArguments "containerRunArguments": "-l Additional arguments

run ContainerRunArguments mylabel=value" to pass to the docker
arguments run or podman run
command.

(Use the lowercase

version in Visual Studio
17.12 and later. The
uppercase version was
introduced in Visual
Studio 17.9 and is
provided for backward
compatibility.)

You can use the

following replacement
tokens:

- {ProjectDir} - Full
Property in Setting name in Example Description
Debug [Link]
Profile UI

path to the project

directory.

- {OutDir} - The value

of the MSBuild
property OutDir.

N/A DockerfileRunArguments "dockerfileRunArguments": "-l Like

mylabel=value" containerRunArguments ,
but only for projects
that use the Dockerfile
build type. It's
recommended to use
containerRunArguments
instead.

Environment environmentVariables "environmentVariables": { These environment

Variables "ASPNETCORE_URLS": variable values are
"[Link] , passed to the process
"ASPNETCORE_HTTPS_PORT": when it's launched in
"44381" the container.
}

Executable executablePath "executablePath": When debugging, the

Path "[Link]" debugger is instructed
to launch this
executable.

Container containerName mycontainer (17.12 and later) A

Name name for the container
matching the regular
expression [a-zA-Z0-9]
[a-zA-Z0-9_.-] .

Container containerRunEnvironmentFiles "containerRunEnvironmentFiles": (17.12 and later) A list

environment "[Link];[Link]" of environment
files variable files ( .env
files) separated by
semicolons. See .env
file syntax .

HTTP Port httpPort "httpPort": 24051 This port on the host is

mapped to the
container's HTTP port
when launching the
container. Container
Property in Setting name in Example Description
Debug [Link]
Profile UI

port 80 is used, unless

you specify ports by
using the environment
variables
ASPNETCORE_URLS and
ASPNETCORE_HTTP_PORTS .

Launch launchBrowser "launchBrowser": true Indicates whether to

Browser launch the browser
after successfully
launching the project.

N/A launchBrowserTimeout "launchBrowserTimeout": 1 The maximum amount

of time (in seconds) to
wait for the app to be
ready before launching
the browser (Docker
Compose only).

URL launchUrl "launchUrl": " This URL is used when

{Scheme}://{ServiceHost}: launching the browser.
{ServicePort}" Supported
replacement tokens for
this string are:

- {Scheme} - Replaced
with either http or
https , depending on
whether SSL is used.

- {ServiceHost} -
Usually replaced with
localhost .
When you're targeting
Windows containers on
Windows 10 RS3 or
older, though, it's
replaced with the
container's IP.

- {ServicePort} -
Usually replaced with
either sslPort or
httpPort, depending on
whether SSL is used.
When you're targeting
Property in Setting name in Example Description
Debug [Link]
Profile UI

Windows containers on
Windows 10 RS3 or
older, though, it's
replaced with the HTTP
or HTTPS port
specified by the
environment variables
ASPNETCORE_URLS and
ASPNETCORE_HTTP_PORTS ,
or 80 for HTTP and 443
for HTTPS if not set.

Publish all publishAllPorts "publishAllPorts": true If true, pass -P to

ports docker run , which
publishes all exposed
ports to a random port.
See Docker
documentation .
However, when you
specify sslPort , Visual
Studio still passes -p
5002:443 , so your
service should still be
listening on port 5002.

SSL Port sslPort "sslPort": 44381 This port on the host is

mapped to the
container's HTTPS port
when launching the
container. Container
port 443 is used, unless
you specify ports by
using the environment
variables
ASPNETCORE_URLS and
ASPNETCORE_HTTP_PORTS .

N/A useSSL "useSSL": true Indicates whether to

use SSL when
launching the project.
If useSSL isn't
specified, then SSL is
used when sslPort >
0.
 Property in Setting name in Example Description
Debug [Link]
Profile UI

Working workingDirectory "workingDirectory": When debugging, the

directory "c:\path\to\folder" debugger is instructed
to use this path as the
working directory.

Not all settings are available in the UI, for example, useSSL . To change those settings, edit
[Link] directly.

The containerRunArguments can be set in the Launch Profiles UI as Container run arguments . It
is equivalent to the obsolete MSBuild property DockerfileRunArguments .

７ Note

If the same setting is found in both the project file and in the launch settings file, the value
in the launch settings file takes precedence.

Next steps
Configure your project by setting the Container Tools build properties.

See also
Docker Compose build properties
Manage launch profiles for Docker Compose

Last updated on 09/18/2025

Container Tools error messages
This article lists the error codes used by Visual Studio Container Tools and, where possible,
provides suggestions on how to resolve the issues.

Container Tools error codes

ﾉ Expand table

Code Description Notes Fix

CTC1001 Docker volume sharing is not This error happens when Enable Docker file sharing.
enabled file sharing is not
enabled. File sharing
allows local directories on
Windows to be shared
with Linux containers.
This is applicable only in
Linux containers that are
using Hyper-V mode. See
Docker Desktop for
Windows user manual or
Docker Documentation
for more details.

CTC1002 Docker Desktop is not installed Install Docker Desktop.

CTC1003 Docker Desktop is not running Start Docker Desktop.

CTC1004 Unable to get Docker server OS Specify the default targetOS in

the project file; for example,
<DockerDefaultTargetOS> Linux
</DockerDefaultTargetOS> ).

CTC1005 Docker Desktop's operating Switch the Docker Desktop

system mode does not match operating system mode to
the project's target operating match the project's target
system operating system.

CTC1006 Docker Desktop is running but Restart Docker Desktop and

is in an error state and should make sure Docker Desktop is
be restarted. functioning properly.

CTC1007 Downloading vsdbg failed but This is just a warning and No action needed from user.
an existing copy was found on the debugging will not
disk fail. This warning happens
when the latest version of
vsdbg fails to download
Code Description Notes Fix

but an existing copy was

found and being used.

CTC1008 Downloading vsdbg failed and F5 failed to download Check your Internet
no existing copy was found on [Link] . connection.
disk

CTC1009 Drive-sharing credentials are This might be caused by the

possibly invalid Shared Drives credentials used
by Docker Desktop being out
of date. Try resetting the
credentials in the Shared
Drives page of the Docker
Desktop settings, and then
restarting Docker.

CTC1010 The current user is not in the The current user is not in the
docker-users group docker-users group. Add
yourself to the docker-users
group and then log out and
back in to Windows.

CTC1011 Ports are in use A container is trying to Stop the previous container or
use a specific host port other application that uses this
that is already in use. port or update the application
to use different port.

CTC1012 Not used

CTC1013 This current type is not

supported or the dotnet core
version is not supported

CTC1014 Error building dockerFile Unable to build the Dockerfile.

Correct the error in the
Dockerfile and try again.

CTC1019 Unused

CTC1020 UnauthorizedAccessException
thrown while trying to start the
container

CTC1021 SecurityException thrown while

trying to start the container

CTC1022 Unused
Code Description Notes Fix

CTC1023 Either file or directory not This could be either

found. dockerfile, Docker
context or project file not
found.

CTC1024 IOException thrown while

trying to start the container

CTC1025 An error occurred while trying See the Output window for a
to pull a Docker image. more detailed error on why the
docker pull command failed.

CTC1026 Launch setting parsing error. Unable to find the Make sure the IISExpress
IISExpress settings or settings in [Link] is
parsing failure while valid.
parsing the IISExpress
setting in the
[Link] file.

CTC1027 Error running the dev-certs An error occurred while See the Output window for
tool. running the dev-certs more detailed error.
tool to trust the [Link]
Core development
certificate.

CTC1028 Invalid Launch URL The application URL that Ensure the launchUrl specified
will be launched when in the Docker launch settings in
the debugging starts is [Link]
invalid

CTC1029 Docker execution failed An error occurred while See the Output window for
trying to run a command more detailed error.
to start the application
process inside the
container.

CTC1030 Internal error An unknown internal Please open a bug in Visual

error occurred. Studio Feedback.

CTC1031 Unsupported OS Likely using .NET Framework

project in a Linux container.
Switch to a Windows container
and try again.

CTC1032 Unused

CTC1033 Unused

CTC1034 Unused
Code Description Notes Fix

CTC1035 Docker Desktop download Unable to download Check your Internet

failed Docker Desktop installer connection, and that no firewall
( .msi ) while trying to is blocking the file download.
install Docker Desktop.

CTC1036 Docker Desktop installation Correct the error in the installer

failed and manually install Docker
Desktop. Or, reopen the
solution and Visual Studio will
try to install Docker Desktop
again.

CTC1037 Blazor Manifest file access error Rewriting Blazor static See the Output window for
web assets file failed more detailed error.
when debugging the
Blazor application.

CTC1038 The container is absent or not See the Output window for
running at the time of more detail on why the
debugging container failed to start.

CTC1039 The binaries of the program to

debug are not found at
expected location in the
container.

CTC1040 The debugged program exited Unable to start the application

with an unexpected exit code process. See the Output
window for more details.

CTC1041 Incomplete Docker Desktop Docker Desktop does not

installation. appear to have finished
installing. Please try rebooting,
and if the issue persists, try
repairing your Docker Desktop
installation.

Docker-compose-specific error codes

ﾉ Expand table

Code Description Notes Fix

DTP1001 Host port not found In the Docker Compose project, the Ensure the container is started
Service URL specifies the token with a host port for the right
{ServicePort} , but the container URL scheme ( http or https ).
Code Description Notes Fix

doesn't have any corresponding

host port.

DTP1002 Container not When debugging the Docker See the Output window for
found Compose project, the container was more detail on why the
not started or container exited. container is failed to start.

DTP1003 No service found Ensure that the Docker

while debugging Compose document has one or
the Docker more dotnet service defined.
Compose project.

DTP1004 Docker Compose Try adding Docker Compose

scaffolding error support again.

DT1001 Debugging failed See the Output window for more

due to an error detail on this error.
running Docker
Compose
command.

DT1002 Invalid target OS Unknown Dockerfile target OS Supported values are 'Windows'
specified in DockerDefaultTargetOS and 'Linux'.
property.

DT1003 An unexpected See the Output window for

error while trying to more detail on this error.
execute a
command.

DT1004 Error in Docker Check all Docker Compose

Compose file documents and make sure they
are valid.

DT1005 Docker Compose See the Output window for

command more detail on this error.
execution failure

DT1006 The compose For example, if the active launch Update the launch profile to use
profile name used profile is using compose profile the right compose profile or use
in the active launch called p2 as shown here: the Manage Docker Compose
profile is not found Launch Settings dialog to
in the Docker "Docker Compose": { update the launch settings.
Compose "commandName": "DockerCompose",
document. "commandVersion": "1.0",
"composeProfile": {
"includes": [
"p2"
]
Code Description Notes Fix

}
}

but [Link] didn't

define the profile p2 , then you will
see this error.

DT1007 Invalid service name For example, if the active launch Update the launch profile to use
in the active launch profile is using compose profile p1 the right service name or use
profile that uses and defines the service list for the the Manage Docker Compose
compose profile. compose profile p1 as shown here: Launch Settings dialog to
update the launch settings.
"Docker Compose": {
"commandName": "DockerCompose",
"commandVersion": "1.0",
"composeProfile": {
"includes": [
"p1"
],
"serviceActions": {
"webapp2":
"StartWithoutDebugging"
}
}
}
but [Link] doesn't
define the service webapp2 , then you
see this error.

DT1008 Invalid service For example, if the active launch Correct the service action to
action in the active profile is using compose profile p1 StartWithoutDebugging , which is
launch profile that and defines the wrong action the only valid action for service
uses compose ( wrongActionname ) for a service that uses a compose profile.
profile. ( webapplication ).
"Docker Compose":
{ "commandName": "DockerCompose",
"commandVersion": "1.0",
"composeProfile": {
"includes": [
"p1"
],
"serviceActions": {
"webapp": "wrongActionname"
}
}
}
Code Description Notes Fix

DT1009 Active launch A Visual Studio launch profile can Use either composeProfile or
profile is using both be defined either using compose serviceActions or use the
composeProfile and profiles or picking and choosing a Manage Docker Compose
serviceActions . service list without using a compose Launch Settings dialog to
profile; it can't be created using update the launch settings.
both. So if an active launch profile
uses both as shown below, then you
see this error.
"Docker Compose": {
"commandName": "DockerCompose",
"commandVersion": "1.0",
"composeProfile": {
"includes": [
"p1"
]
},
"serviceActions": {
"webapp":
"StartWithoutDebugging"
}
}

DT1010 Invalid service name For example, if the active launch Update the launch profile to use
in the active launch profile defines the serviceActions the right service name or use
profile as shown here: the Manage Docker Compose
"Docker Compose": { Launch Settings dialog to
"commandName": "DockerCompose", update the launch settings.
"commandVersion": "1.0",
"serviceActions": {
"redis1":
"StartWithoutDebugging",
"webapp8":
"StartWithoutDebugging"
}
}
But the [Link] didn't
define the service redis1 , then you
will see this error.

DT1011 Invalid service For example, if the active launch Correct the service action to one
action in the active profile uses the wrong service of DoNotStart , StartDebugging ,
launch profile. action ( wrongAction ) as shown or StartWithoutDebugging . Or
below, then you will see this error. use Manage Docker Compose
"Docker Compose": { Launch Settings dialog to
"commandName": "DockerCompose", update the launch settings.
"commandVersion": "1.0",
Code Description Notes Fix

"serviceActions": {
"webapplication8":
"wrongAction"
}
}

DT1012 Invalid launch A Visual Studio launch profile can Use the Manage Docker
profile. Both be defined either using compose Compose Launch Settings
composeProfile and profiles or by picking and choosing dialog to update the launch
serviceActions are a service list without using a settings.
missing. compose profile. But the active
launch profile is defined with none
of them.

DT1013 The active launch Ensure the active launch profile

profile is not found is defined in [Link].

DT1014 Invalid profile For example, if the active launch Please see the error message for
version. profile defines an unknown the supported commandVersion ,
command version (10.0): or use the Manage Docker
"Docker Compose": Compose Launch Settings
"commandName": "DockerCompose", dialog to update the launch
"commandVersion": "10.0", settings.
"serviceActions": {
"webapp8": "StartDebugging",
"redis":
"StartWithoutDebugging"
}
}

DT1015 Unsupported old The profile version is no longer

profile version. supported by the current Visual
Studio. Please upgrade the
profile to the latest supported
version using the Manage
Docker Compose Launch
Settings dialog to update the
launch settings.

DT1016 Using profile from The profile version is higher

newer version of than the current supported
Visual Studio version. Please upgrade the
Visual Studio to the latest
version.

DT1017 Using profile from This is a warning message The profile version is higher
newer version of than the current supported
Visual Studio, but version, but still compatible with
Code Description Notes Fix

will continue to the current version of Visual

work Studio, but might be missing
some features.

DT1018 Using old profile This is a warning message The profile version is lower than
version, but the latest version, but still
compatible. compatible. Some of the newer
features might not work.
Consider upgrading to the latest
version of Visual Studio.

DT1019 Unsupported You are using older version of Upgrade Docker Compose to
compose v2 Docker Compose v2 that doesn't the latest version.
support the compose profile.

Single-project-specific error codes

ﾉ Expand table

Code Description Notes Fix

CTP1001 Unused

CTP1002 Unused

CTP1003 The container is absent or See the Output window for more detail on why
not running at the time of the container is failed to start.
debugging

CTP1004 Docker scaffolding error Try adding Docker support again.

CTP1005 Invalid target OS Unknown Dockerfile target OS specified in

DockerDefaultTargetOS property. Supported
values are 'Windows' and 'Linux'.

CTP1006 Failed to stop the This is just a Make sure the application is not in use.
application within the warning.
container.

CTP1007 Unused

CTP1008 Unused

CTP1009 Failed to download Azure See the Output window for more detail.
Functions CLI
Last updated on 03/29/2024