Container Tools launch settings

In the Properties folder in an ASP.NET Core project, you can find the launchSettings.json 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 ASP.NET development, see Use multiple environments in ASP.NET 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 launchSettings.json, the settings in the Docker section are related to how Visual Studio handles containerized apps.

    "Docker": {
      "commandName": "Docker",
      "launchBrowser": true,
      "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}",
      "DockerfileRunArguments": "-l mylabel=value",
      "environmentVariables": {
        "ASPNETCORE_URLS": "https://+:443;http://+:80",
        "ASPNETCORE_HTTPS_PORT": "44360"
      },
      "httpPort": 51803,
      "useSSL": true,
      "sslPort": 44360
    }

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

Most of the settings in launchSettings.json 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:

Property in Debug Profile UI	Setting name in launchSettings.json	Example	Description
Command line arguments	commandLineArgs	"commandLineArgs": "--mysetting myvalue"	These command-line arguments for starting your app are used when launching your project in the container.
Container run arguments	containerRunArguments ContainerRunArguments	"containerRunArguments": "-l mylabel=value"	Additional arguments to pass to the docker 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 path to the project directory. - {OutDir} - The value of the MSBuild property OutDir.
N/A	DockerfileRunArguments	dockerfileRunArguments": "-l mylabel=value"	Like containerRunArguments, but only for projects that use the Dockerfile build type. For Visual Studio 17.12 and later, it is recommended to use containerRunArguments instead.
Environment Variables	environmentVariables	"environmentVariables": { "ASPNETCORE_URLS": "https://+:443;http://+:80", "ASPNETCORE_HTTPS_PORT": "44381" }	These environment variable values are passed to the process when it's launched in the container.
Container Name	containerName	mycontainer	(17.12 and later) A name for the container matching the regular expression [a-zA-Z0-9][a-zA-Z0-9_.-].
Container environment files	containerRunEnvironmentFiles	"containerRunEnvironmentFiles": "abc.env;xyz.env"	(17.12 and later) A list of environment 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 port 80 when launching the container.
Launch Browser	launchBrowser	"launchBrowser": true	Indicates whether to 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": "{Scheme}://{ServiceHost}:{ServicePort}"	This URL is used when launching the browser. 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 Windows containers on Windows 10 RS3 or older, though, it's replaced with either 443 or 80, depending on whether SSL is used.
Publish all ports	publishAllPorts	"publishAllPorts": true	If true, pass -P to 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 port 443 when launching the container.
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.

Not all settings are available in the UI, for example, useSSL. To change those settings, edit launchSettings.json directly.

The setting DockerfileRunArguments is superceded in Visual Studio 2022 17.12 and later by containerRunArguments, which can be set in the Launch Profiles UI as Container run arguments.

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