|
1 | 1 | --- |
2 | | -title: Configure Visual Studio Container Tools |
| 2 | +title: Configure Container Tools |
3 | 3 | description: Use Visual Studio Container Tools to control how Visual Studio works with Docker containers, including performance settings and resource usage. |
4 | 4 | author: ghogen |
5 | 5 | ms.author: ghogen |
6 | 6 | ms.topic: how-to |
7 | | -ms.date: 07/13/2023 |
| 7 | +ms.date: 04/23/2025 |
8 | 8 | ms.subservice: container-tools |
9 | 9 | f1_keywords: |
10 | 10 | - VS.ToolsOptionsPages.Container_Tools.General |
11 | 11 | - VS.ToolsOptionsPages.Container_Tools.Docker |
12 | 12 | - VS.ToolsOptionsPages.Container_Tools.Containers_Tool_Window |
13 | 13 | - VS.ToolsOptionsPages.Container_Tools.Settings |
| 14 | + |
| 15 | +#customer intent: As a deveoloper, I want to learn how to configure Visual Studio Container Tools so I can get the best performance and resource usage for my container projects. |
14 | 16 | --- |
15 | 17 |
|
16 | 18 | # Configure Visual Studio Container Tools |
17 | 19 |
|
18 | | -Using Visual Studio settings, you can control some aspects of how Visual Studio works with Docker containers, including settings that affect performance and resource usage when working with Docker containers. |
| 20 | +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. |
19 | 21 |
|
20 | 22 | ## Container Tools settings |
21 | 23 |
|
22 | | -From the main menu, choose **Tools > Options**, and expand **Container Tools > Settings**. The container tools settings appear. |
| 24 | +To access the settings, select **Tools > Options** from the main Visual Studio menu. In the left pane, scroll down and expand **Container Tools**. |
23 | 25 |
|
24 | | -Container Tools **General** settings: |
| 26 | +### General settings |
25 | 27 |
|
26 | | - |
| 28 | +:::moniker range="<=vs-2019" |
| 29 | + |
27 | 30 |
|
28 | | -Container Tools **Single Project** and **Docker Compose** settings: |
| 31 | +The following table describes the **General** settings: |
| 32 | + |
| 33 | +|Setting|Default value|Description| |
| 34 | +|-----|---------------|----------|-----------| |
| 35 | +|Install Docker Desktop if needed|Prompt me|Choose whether you want to be prompted if Docker Desktop isn't installed.| |
| 36 | +|Start Docker Desktop if needed|Always|If Docker Desktop isn't started, choose whether to start it automatically or whether to prompt you.| |
| 37 | +|Trust ASP.NET Core SSL certificate|Prompt me|Choose whether to prompt if the `localhost` SSL certificate isn't trusted in an ASP.NET Core project.| |
29 | 38 |
|
30 | | -:::moniker range="<=vs-2019" |
31 | | - |
32 | 39 | :::moniker-end |
33 | 40 | :::moniker range=">=vs-2022" |
34 | | - |
| 41 | + |
| 42 | + |
| 43 | +The following table describes the **General** settings: |
| 44 | + |
| 45 | +|Setting|Default value|Description| |
| 46 | +|-----|---------------|-----------| |
| 47 | +|Install Docker Desktop if needed|Prompt me|Choose whether you want to be prompted if Docker Desktop isn't installed.| |
| 48 | +|Start Docker Desktop if needed|Prompt me|If Docker Desktop isn't started, choose whether to start it automatically or whether to prompt you.| |
| 49 | +|Trust ASP.NET Core SSL certificate|Prompt me|Choose whether to prompt if the `localhost` SSL certificate isn't trusted in an ASP.NET Core project.| |
| 50 | + |
35 | 51 | :::moniker-end |
36 | 52 |
|
37 | | -The following table might help you decide how to set these options. |
| 53 | +> [!IMPORTANT] |
| 54 | +> If you set **Trust ASP.NET 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 ASP.NET Core SSL certificate** to **Prompt me**, run your project, and indicate trust at the prompt. |
| 55 | +
|
| 56 | +### Single Project or Docker Compose settings |
38 | 57 |
|
39 | | -The following table describes **General** settings: |
| 58 | +The Container Tools **Single Project** and **Docker Compose** settings are identical. |
40 | 59 |
|
41 | | -| Name | Default Setting | Applies To | Description | |
42 | | -| -----|:---------------:|:----------:| ----------- | |
43 | | -| Install Docker Desktop if needed | Prompt Me | Single Project, Docker Compose | Choose whether you want to be prompted if Docker Desktop is not installed. | |
44 | | -| Trust ASP.NET Core SSL certificate | Prompt Me | ASP.NET Core 2.x projects | When set to **Prompt Me**, if the `localhost` SSL certificate is not trusted, Visual Studio will prompt every time you run an ASP.NET Core 2.x project. | |
| 60 | +:::moniker range="<=vs-2019" |
| 61 | + |
| 62 | +:::moniker-end |
| 63 | +:::moniker range=">=vs-2022" |
| 64 | + |
| 65 | +:::moniker-end |
45 | 66 |
|
46 | 67 | The following table describes **Single Project** and **Docker Compose** settings: |
47 | 68 |
|
48 | 69 | :::moniker range="<=vs-2019" |
49 | | -| Name | Default Setting | Applies To | Description | |
50 | | -| -----|:---------------:|:----------:| ----------- | |
51 | | -| Pull required Docker images on project open | True | Single Project, Docker Compose | For increased performance when loading projects, Visual Studio will start a Docker pull operation in the background so that when you're ready to run your code, the image is already downloaded or in the process of downloading. If you're just loading projects and browsing code, you can set to **False** to avoid downloading container images you don't need. | |
52 | | -| Pull updated Docker images on project open | .NET Core projects | Single Project, Docker Compose | When you open a project, check for updates to images and download if available. | |
53 | | -| Run containers on project open | True | Single Project, Docker Compose | Again for increased performance, Visual Studio creates a container ahead of time so that it's ready for when you build and run your container. If you want to control when your container is created, set to **False**. | |
54 | | -| Remove containers on project close | True | Single Project, Docker Compose | Set to **False** if you would like containers for your solution to be retained after closing the solution or closing Visual Studio. | |
| 70 | +|Setting|Default value|Description| |
| 71 | +|-----|---------------|-----------| |
| 72 | +|Pull required Docker images on project open|True|Whether to start a background Docker pull operation when loading a container project. Required images are downloaded or downloading when 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.| |
| 73 | +|Pull updated Docker images on project open|.NET Core projects|Whether or on which projects to run a Docker pull for all images on project open to get the latest updates.| |
| 74 | +|Run containers on project open|True|Whether to create a container when loading a container project, so it's ready when you build and run. If you prefer to control when your container is created, set to **False**.| |
| 75 | +|Remove containers on project close|True|Whether to remove containers for your solution after closing the solution or closing Visual Studio.| |
55 | 76 | :::moniker-end |
56 | 77 | :::moniker range=">=vs-2022" |
57 | | -| Name | Default Setting | Applies To | Description | |
58 | | -| -----|:---------------:|:----------:| ----------- | |
59 | | -| Pull required Docker images on project open | True | Single Project, Docker Compose | For increased performance when loading projects, Visual Studio will start a Docker pull operation in the background so that when you're ready to run your code, the image is already downloaded or in the process of downloading. If you're just loading projects and browsing code, you can set to **False** to avoid downloading container images you don't need. | |
60 | | -| Pull updated Docker images on project open | .NET Core projects | Single Project, Docker Compose | When you open a project, check for updates to images and download if available. | |
61 | | -| Run containers on project open | True | Single Project, Docker Compose | Again for increased performance, Visual Studio creates a container ahead of time so that it's ready for when you build and run your container. If you want to control when your container is created, set to **False**. | |
62 | | -| Remove containers on project close | True | Single Project, Docker Compose | Set to **False** if you would like containers for your solution to be retained after closing the solution or closing Visual Studio. | |
63 | | -| Run a service in containers to enable Azure Authentication | True | Single Project, Docker Compose | Visual Studio version 17.6 or later runs a [token proxy](#configure-azure-authentication) service in the container that assists with Azure Authentication, so your apps can use Azure services during development. Set to `False` if you don't want this service to be installed and run.| |
64 | | -| Run a service in containers to enable Hot Reload | True | Single Project, Docker Compose | Set to `False` if you don't want this service to be installed and run. The Hot Reload service is available in Visual Studio 2022 version 17.7 and later and only supports running without debugging (**Ctrl**+**F5**). | |
| 78 | +|Setting|Default value|Description| |
| 79 | +|-----|:---------------|-----------| |
| 80 | +|Pull required Docker images on project open|True|Whether to start a background Docker pull operation when loading a container project. Required images are downloaded or downloading when 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.| |
| 81 | +|Pull updated Docker images on project open|.NET Core projects|Whether or on which projects to run a Docker pull for all images on project open to get the latest updates.| |
| 82 | +|Run containers on project open|True|Whether to create a container when loading a container project, so it's ready when you build and run. If you prefer to control when your container is created, set to **False**.| |
| 83 | +|Remove containers on project close|True|Whether to remove containers for your solution after closing the solution or closing Visual Studio.| |
| 84 | +|Run a service in containers to enable Azure Authentication|True|For Visual Studio version 17.6 or later, whether to install and run a token proxy service in the container to enable Azure Authentication. This service lets your apps use Azure services during development. For more information, see the [Configure Azure authentication](#configure-azure-authentication) section.| |
| 85 | +|Run a service in containers to enable Hot Reload|True|For Visual Studio version 17.7 and later, whether to install and run the Hot Reload service. This service only supports running without debugging, **Ctrl**+**F5**.| |
65 | 86 | :::moniker-end |
66 | 87 |
|
67 | | -The **Containers Tool Window** settings control the settings that apply to the **Containers** tool window, which shows information about Docker containers and images. See [Use the Containers window](view-and-diagnose-containers.md) |
| 88 | +:::moniker range="<=vs-2019" |
| 89 | +### Containers Tool Window settings |
68 | 90 |
|
69 | | - |
| 91 | +The **Containers Tool 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](view-and-diagnose-containers.md). |
70 | 92 |
|
71 | | -The following table describes the **Containers** window settings: |
| 93 | + |
72 | 94 |
|
73 | | -| Name | Default Setting | Description | |
74 | | -| -----|:---------------:| ----------- | |
75 | | -| Confirm before pruning containers | Always | Controls whether you are prompted when pruning unused containers. | |
76 | | -| Confirm before pruning images | Always | Controls whether you are prompted when pruning unused images. | |
77 | | -| Confirm before removing a container | Always | Controls whether you are prompted when removing a container. | |
78 | | -| Confirm before removing an image | Always | Controls whether you are prompted when removing an image. | |
79 | | -| Confirm before running large number of images | Always | Controls whether you are prompted before starting containers from more than 10 images at a time. | |
| 95 | +The following table describes the **Containers Tool Window** settings: |
80 | 96 |
|
81 | | -> [!WARNING] |
82 | | -> If the `localhost` SSL certificate is not trusted, and you select the box to suppress prompting, then HTTPS web requests might fail at run time in your app or service. In that case, clear the **Do not prompt** checkbox, run your project, and indicate trust at the prompt. |
| 97 | +|Setting|Default value|Description| |
| 98 | +|-----|---------------|-----------| |
| 99 | +|Confirm before pruning containers|Always|Whether to prompt you when pruning unused containers.| |
| 100 | +|Confirm before pruning images|Always|Whether to prompt you when pruning unused images.| |
| 101 | +|Confirm before removing a container|Always|Whether to prompt you when removing a container.| |
| 102 | +|Confirm before removing an image|Always|Whether to prompt you when removing an image.| |
| 103 | +|Confirm before running large number of images|Always|Whether to prompt you before starting containers from more than 10 images at a time.| |
83 | 104 |
|
| 105 | +:::moniker-end |
84 | 106 | :::moniker range=">=vs-2022" |
| 107 | +### Containers Window settings |
| 108 | + |
| 109 | +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](view-and-diagnose-containers.md). |
| 110 | + |
| 111 | + |
| 112 | + |
| 113 | +The following table describes the **Containers Window** settings: |
| 114 | + |
| 115 | +|Setting|Default value|Description| |
| 116 | +|-----|---------------|-----------| |
| 117 | +|Confirm before pruning containers|Always|Whether to prompt you when pruning unused containers.| |
| 118 | +|Confirm before pruning images|Always|Whether to prompt you when pruning unused images.| |
| 119 | +|Confirm before removing a container|Always|Whether to prompt you when removing a container.| |
| 120 | +|Confirm before removing an image|Always|Whether to prompt you when removing an image.| |
| 121 | +|Confirm before running large number of images|Always|Whether to prompt you before starting containers from more than 10 images at a time.| |
| 122 | +|Display string format to use in the Containers window|Blank|A display string format to use in the Containers window, with support for {ContainerName}, {ImageName}, {ProjectName}, and {ContainerID} tokens.| |
| 123 | +|Group containers by the Docker Compose project|Always|Whether to group containers by the Docker Compose project they're part of.| |
85 | 124 |
|
86 | 125 | ## Configure Azure authentication |
87 | 126 |
|
88 | | -If your app uses Azure services, it needs the appropriate authentication credentials when it runs in a container in order to authenticate with Azure services. During development, you can usually use your own Azure credentials instead of the credentials the app uses in production, but those credentials are required in the container environment to be useful for the running containerized app. |
| 127 | +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. |
89 | 128 |
|
90 | | -Starting with Visual Studio 2022 version 17.6, in both single-container and Docker Compose projects, a [token](https://www.nuget.org/packages/Azure.Identity#readme-body-tab) proxy service is deployed and run in your containers that helps your apps and services authenticate in Azure. The feature requires [Azure Identity 1.9.0](https://www.nuget.org/packages/Azure.Identity/1.9.0#readme-body-tab) or later. With this service enabled, you can automatically use most Azure services without any additional configuration or setup within the container. Specifically, your code can use `DefaultAzureCredential` and `VisualStudioCredential` to authenticate with Azure services in the same way as outside of a container. See the [Azure Identity 1.9.0 README](https://www.nuget.org/packages/Azure.Identity/1.9.0#readme-body-tab). |
| 129 | +Visual Studio 2022 version 17.6 and later deploys and runs a [token](https://www.nuget.org/packages/Azure.Identity#readme-body-tab) 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](https://www.nuget.org/packages/Azure.Identity/1.9.0#readme-body-tab) or later. |
91 | 130 |
|
92 | | -To disable this feature, set the **Tools** > **Options** setting **Run a service in containers to enable Azure Authentication** (described earlier in this article) to `False`. |
| 131 | +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](https://www.nuget.org/packages/Azure.Identity/1.9.0#readme-body-tab). |
| 132 | + |
| 133 | +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](#single-project-or-docker-compose-settings). |
93 | 134 |
|
94 | 135 | > [!CAUTION] |
95 | | -> There is a potential security concern if you use the token proxy and have enabled certain Container Tools diagnostic logs. When logging is enabled, authentication credentials could be logged as plain text. These logs are enabled by certain environment variables. For single container projects, the environment variable is `MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED`, which then logs in `%tmp%\Microsoft.VisualStudio.Containers.Tools`. For Docker Compose projects, it is `MS_VS_DOCKER_TOOLS_LOGGING_ENABLED`, which then logs in `%tmp%\Microsoft.VisualStudio.DockerCompose.Tools`. |
| 136 | +> 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: |
| 137 | +> |
| 138 | +> - For single container projects, `MS_VS_CONTAINERS_TOOLS_LOGGING_ENABLED`, which logs in `%tmp%\Microsoft.VisualStudio.Containers.Tools`. |
| 139 | +> - For Docker Compose projects, `MS_VS_DOCKER_TOOLS_LOGGING_ENABLED`, which logs in `%tmp%\Microsoft.VisualStudio.DockerCompose.Tools`. |
96 | 140 |
|
97 | 141 | :::moniker-end |
98 | 142 |
|
99 | 143 | ## Related content |
100 | 144 |
|
101 | | -Read more about working with containers in Visual Studio in this [overview](overview.md). |
| 145 | +- [Visual Studio Container Tools for Docker](overview.md) |
| 146 | +- [Use the Containers window](container-tools-configure.md) |
| 147 | + |
0 commit comments