Skip to content

Commit 6b94bd8

Browse files
tannergoodingCopilot
tannergooding
and
Copilot
authored
Document launch profiles for dotnet run (#55785)
* Document launch profiles for dotnet run Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Update launch profile expansion guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Update launch profile expansion version guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 55e6c9e commit 6b94bd8

3 files changed

Lines changed: 116 additions & 6 deletions

File tree

‎docs/core/sdk/file-based-apps.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: File-based apps
33
description: Learn how to create, build, and run C# applications from a single file without a project file.
4-
ms.date: 04/22/2026
4+
ms.date: 08/31/2026
55
ai-usage: ai-assisted
66
---
77
# File-based apps
@@ -277,6 +277,8 @@ For more information, see [Safe storage of app secrets in development](/aspnet/c
277277

278278
File-based apps support launch profiles for configuring how the application runs during development. Instead of placing launch profiles in `Properties/launchSettings.json`, file-based apps can use a flat launch settings file named `[ApplicationName].run.json` in the same directory as the source file.
279279

280+
For the general profile format and properties that `dotnet run` supports, see [Launch profiles](../tools/dotnet-run.md#launch-profiles).
281+
280282
### Flat launch settings file
281283

282284
Create a launch settings file named after your application. For example, if your file-based app is `app.cs`, create `app.run.json` in the same directory:

‎docs/core/tools/dotnet-environment-variables.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ Starting in Visual Studio 2026, MSBuild in Visual Studio _also_ ensures that `DO
252252
253253
### `DOTNET_LAUNCH_PROFILE`
254254

255-
The [dotnet run](dotnet-run.md) command sets this variable to the selected launch profile.
255+
The [`dotnet run` command](dotnet-run.md#launch-profiles) sets this variable to the selected launch profile.
256256

257257
Given the following _launchSettings.json_ file:
258258

‎docs/core/tools/dotnet-run.md‎

Lines changed: 112 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
22
title: dotnet run command
33
description: The dotnet run command provides a convenient option to run your application from the source code.
4-
ms.date: 06/05/2026
4+
ms.date: 09/04/2026
5+
ai-usage: ai-assisted
56
---
67
# dotnet run
78

@@ -53,6 +54,112 @@ To run the application, the `dotnet run` command resolves the dependencies of th
5354

5455
[!INCLUDE [cli-advertising-manifests](includes/cli-advertising-manifests.md)]
5556

57+
## Launch profiles
58+
59+
Launch profiles configure how `dotnet run` starts an app during development. For an SDK-style project, put the settings in `Properties/launchSettings.json`. Visual Basic projects use `My Project/launchSettings.json` instead.
60+
61+
File-based apps can use an `[ApplicationName].run.json` file next to the source file. For the file lookup order and examples, see [Launch profiles for file-based apps](../sdk/file-based-apps.md#launch-profiles).
62+
63+
The launch settings file contains a top-level `profiles` object. Each property in `profiles` defines a named profile:
64+
65+
```json
66+
{
67+
"profiles": {
68+
"Local": {
69+
"commandName": "Project",
70+
"commandLineArgs": "--input sample.txt",
71+
"dotnetRunMessages": true,
72+
"environmentVariables": {
73+
"APP_MODE": "local"
74+
}
75+
}
76+
}
77+
}
78+
```
79+
80+
The .NET SDK launch settings parser accepts JSON comments and trailing commas.
81+
82+
### Select a profile
83+
84+
Use `--launch-profile <NAME>` to select a named profile. The name match is case-insensitive. Profile names that differ only by case are ambiguous and produce an error.
85+
86+
If you don't specify a name, `dotnet run` selects the first profile in file order whose `commandName` it supports. Use `--no-launch-profile` to skip the launch settings file.
87+
88+
When `dotnet run` applies a profile, it sets [`DOTNET_LAUNCH_PROFILE`](dotnet-environment-variables.md#dotnet_launch_profile) to the selected profile name in the launched process. A later environment-variable source can override the value.
89+
90+
### Supported profile types
91+
92+
The .NET SDK supports these `commandName` values for `dotnet run`. The values are case-sensitive.
93+
94+
| `commandName` | Behavior |
95+
| --- | --- |
96+
| `Project` | Builds the project and starts the command produced by the project. |
97+
| `Executable` | Starts the command specified by `executablePath`. Unless you specify `--no-build`, `dotnet run` still builds the project first. |
98+
99+
### Common properties
100+
101+
`dotnet run` recognizes these properties for both supported profile types:
102+
103+
`dotnet run` expands `%NAME%` environment-variable references in supported string values. In .NET 11 and later versions, it also expands MSBuild property references in values that it uses to launch the process, using the same token replacement as Visual Studio. It doesn't expand shell-style `$NAME` references.
104+
105+
| Property | Behavior |
106+
| --- | --- |
107+
| `commandLineArgs` | Specifies arguments for the launched process. Explicit application arguments on the command line take precedence. For a `Project` profile, arguments supplied by the project also take precedence. |
108+
| `environmentVariables` | Specifies environment variables for the launched process. Profile values override inherited and SDK-generated environment variables, and `-e\|--environment` values override profile values. |
109+
| `dotnetRunMessages` | When `true`, prints `Building...` before `dotnet run` builds the project. The default is `false`. This property doesn't control the message that identifies the launch settings file. |
110+
111+
Use `environmentVariables` to apply development-time runtime configuration settings that have an environment-variable form. For example, a profile can set GC settings such as `DOTNET_gcServer`. For the available settings, environment-variable names, and precedence rules, see [.NET runtime configuration settings](../runtime-config/index.md) and [Runtime configuration options for garbage collection](../runtime-config/garbage-collector.md).
112+
113+
Not every runtime setting has an environment-variable form. To configure an app independently of its launch profile, use an MSBuild property or `RuntimeHostConfigurationOption` item in the project, or use a `runtimeconfig.template.json` file. Some settings can also be changed in code with <xref:System.AppContext.SetSwitch*?displayProperty=nameWithType>. These mechanisms produce or modify the app's runtime configuration; they aren't additional `launchSettings.json` properties.
114+
115+
### `Project` properties
116+
117+
`dotnet run` recognizes these additional properties when `commandName` is `Project`:
118+
119+
| Property | Behavior |
120+
| --- | --- |
121+
| `applicationUrl` | Sets `ASPNETCORE_URLS` in the launched process. An `ASPNETCORE_URLS` value in `environmentVariables` or from `-e\|--environment` takes precedence. |
122+
| `launchBrowser` | Tells launch tooling whether to open a browser. `dotnet run` retains this property in the parsed profile but doesn't open a browser. |
123+
| `launchUrl` | Tells launch tooling which URL to open. `dotnet run` retains this property in the parsed profile but doesn't open a browser or use the URL. |
124+
125+
The `applicationUrl` behavior supports ASP.NET Core, but launch profiles and the other common properties apply to any runnable SDK-style .NET project.
126+
127+
### `Executable` properties
128+
129+
`dotnet run` recognizes these additional properties when `commandName` is `Executable`:
130+
131+
| Property | Behavior |
132+
| --- | --- |
133+
| `executablePath` | Required. Specifies the process to start. The SDK expands supported variable references, but it doesn't resolve a relative value against the launch settings file. Use an absolute path or a command that the operating system can locate. |
134+
| `workingDirectory` | Optional. Specifies the working directory for the launched process. The SDK expands supported variable references and resolves a relative path against the directory that contains the launch settings file. If you omit the property, the working directory defaults to the directory that contains the project or file-based app. |
135+
136+
### Visual Studio and debugger extensions
137+
138+
`launchSettings.json` is a shared input format, but each consumer decides which values to support and how to interpret them. Visual Studio, debuggers, and other tools can recognize more `commandName` values and properties than `dotnet run`.
139+
140+
The following table compares the `dotnet run` contract with the common .NET project-system behavior in Visual Studio:
141+
142+
| Setting or behavior | `dotnet run` | Visual Studio |
143+
| --- | --- | --- |
144+
| Supported profile types | Supports `Project` and `Executable`. | Supports `Project`, `Executable`, and an empty `commandName`. Installed project-system extensions can add other profile types. |
145+
| Variable expansion | Expands `%NAME%` environment-variable references. In .NET 11 and later versions, also expands MSBuild property references in values that it uses to launch the process. | Expands environment variables and MSBuild properties in `executablePath`, `commandLineArgs`, `workingDirectory`, `launchUrl`, environment-variable values, and string-valued extension settings. |
146+
| `commandLineArgs` for `Project` | Uses the profile value only when the project doesn't provide run arguments and you don't pass application arguments on the command line. | Appends the profile value to the run arguments from the project. |
147+
| `workingDirectory` for `Project` | Ignores the property. | Supports the property. A relative path is relative to the project directory. |
148+
| `workingDirectory` for `Executable` | A relative path is relative to the directory that contains the launch settings file. If omitted, the path defaults to the project or file-based app directory. | A relative path is relative to the project directory. If omitted, the path defaults to the output directory when that directory exists, or to the project directory otherwise. |
149+
| Relative `executablePath` | Passes the value to the operating system without rebasing it. | Resolves a value with path components from the profile's working directory. For a bare executable name, Visual Studio checks its own current directory and then `PATH`. |
150+
| `launchBrowser` and `launchUrl` | Retains the values in the parsed profile but doesn't open a browser. | Makes the values available to a launch provider. For example, ASP.NET Core tooling can open a browser. |
151+
| `applicationUrl` | Sets `ASPNETCORE_URLS`. | Makes the value available to installed launch providers, such as ASP.NET Core tooling. |
152+
| `dotnetRunMessages` | Controls the `Building...` message. | Doesn't use the property to control Visual Studio output. |
153+
| Debugger properties | Ignores debugger-specific properties. | Uses properties such as `nativeDebugging`, `sqlDebugging`, `jsWebView2Debugging`, `remoteDebugEnabled`, and `hotReloadEnabled` when the project and debugger support the feature. |
154+
155+
In .NET 11 and later versions, both consumers expand `"$(ProjectDir)"`. In earlier versions, no single `workingDirectory` value identifies the project directory for both consumers. Visual Studio expands `"$(ProjectDir)"`, while `dotnet run` treats it as literal text and resolves relative paths from the directory that contains the launch settings file. Therefore, use `".."` for `dotnet run` with a conventional `Properties/launchSettings.json` or `My Project/launchSettings.json` file. Visual Studio resolves the same value to the parent of the project directory.
156+
157+
Windows Forms and WPF apps don't add another `dotnet run` profile type. Use a `Project` profile with common settings such as `commandLineArgs` and `environmentVariables`. In Visual Studio, these desktop project types can also use applicable debugger properties, such as `nativeDebugging` for mixed managed and native debugging or `jsWebView2Debugging` for WebView2. Browser and URL properties only have an effect when a launch provider or the application consumes them.
158+
159+
Other project types and Visual Studio workloads can install launch providers that add profile types or interpret extra properties. Those extensions don't add support to `dotnet run`: the CLI skips unsupported profile types during default selection and reports an error when you select one explicitly.
160+
161+
For Visual Studio's supported debugger settings and project UI, see [Project settings for a .NET C# debug configuration](/visualstudio/debugger/project-settings-for-csharp-debug-configurations-dotnetcore).
162+
56163
## Arguments
57164

58165
`<applicationArguments>`
@@ -126,7 +233,7 @@ The `--` separator marks every following token as an application argument, so `d
126233

127234
- **`-lp|--launch-profile <NAME>`**
128235

129-
The name of the launch profile (if any) to use when launching the application. Launch profiles are defined in the *launchSettings.json* file and are typically called `Development`, `Staging`, and `Production`. For more information, see [Working with multiple environments](/aspnet/core/fundamentals/environments).
236+
The name of the launch profile to use when launching the application. For more information, see [Launch profiles](#launch-profiles).
130237

131238
- **`--no-build`**
132239

@@ -189,11 +296,12 @@ The `--` separator marks every following token as an application argument, so `d
189296

190297
## Environment variables
191298

192-
There are four mechanisms by which environment variables can be applied to the launched application:
299+
The following sources apply environment variables to the launched application:
193300

194301
1. Ambient environment variables from the operating system when the command is run.
195302
1. System.CommandLine `env` directives, like `[env:key=value]`. These apply to the entire `dotnet run` process, not just the project being run by `dotnet run`.
196-
1. `environmentVariables` from the chosen launch profile (`-lp`) in the project's [launchSettings.json file](/aspnet/core/fundamentals/environments#lsj), if any. These apply to the project being run by `dotnet run`.
303+
1. Values generated from the chosen launch profile. `dotnet run` sets `DOTNET_LAUNCH_PROFILE`, and `applicationUrl` in a `Project` profile sets `ASPNETCORE_URLS`.
304+
1. `environmentVariables` from the [chosen launch profile](#launch-profiles), if any. These apply to the project being run by `dotnet run`.
197305
1. `-e|--environment` CLI option values (added in .NET SDK version 9.0.200). These apply to the project being run by `dotnet run`.
198306

199307
The environment is constructed in the same order as this list, so the `-e|--environment` option has the highest precedence.

0 commit comments

Comments
 (0)