Skip to content

Commit 0e7b710

Browse files
gregg-miskellyntrogh
gregg-miskelly
and
ntrogh
authored
Add 'walkthrough' to debugger settings (#8331)
* Add 'walkthrough' to debugger settings The current C# debugger-settings.md is mostly a long list of options without a walkthrough first to better guide users on how to use launchSettings.json. This PR: 1. Adds a walkthrough so this is hopefully more understandable. 2. Moves the 'Configuring launchSettings.json file' up to the top after the walkthrough 3. Clarifies the 'launchSettings.json support' section, since we didn't do a great job there explaining those options were for `coreclr`/`clr` These changes are based on feedback in dotnet/vscode-csharp#8184 * Apply suggestions from code review Co-authored-by: Nick Trogh <[email protected]> --------- Co-authored-by: Nick Trogh <[email protected]>
1 parent 4e5579d commit 0e7b710

File tree

1 file changed

+108
-74
lines changed

1 file changed

+108
-74
lines changed

‎docs/csharp/debugger-settings.md

Lines changed: 108 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,112 @@ MetaDescription: Configuring C# debugging
1010

1111
You can configure the C# debugger in Visual Studio Code with a `launch.json`, `launchSettings.json`, or your user `settings.json` file.
1212

13-
Below are common options you may want to change while debugging.
13+
## Walkthrough: setting command-line arguments
14+
15+
Before we get into the details of all the possible options, let's walk through a basic scenario: setting command-line arguments to your program. These steps also work for updating other basic options like environment variables or the current working directory.
16+
17+
### Approach 1: `launchSettings.json`
18+
19+
For C# Dev Kit, the recommended way to debug is to let C# Dev Kit automatically figure out how to debug from settings in the project file. This means that you either don't have a `<workspace_root>/.vscode/launch.json` file, or if you have one, you have `"type": "dotnet"` set for the active configuration. For command-line arguments, "figure out from the project file" means to pull the value from `<Project-Directory>/Propeties/launchSettings.json`. The advantage of `launchSettings.json` is that it allows settings to be shared between Visual Studio Code, full Visual Studio, and `dotnet run`.
20+
21+
For this case, here are the steps to set the command-line arguments:
22+
1. In workspace Explorer view, navigate to the directory of the project (.csproj file) you want to launch
23+
2. If there isn't a `Properties` directory already, create it
24+
3. If there isn't a `launchSettings.json` file already, create one, you can use the below text as an example
25+
4. Change the `commandLineArgs` property to what you would like the command-line arguments to be
26+
27+
**Example `launchSettings.json` file**:
28+
```json
29+
{
30+
"profiles": {
31+
"MyLaunchProfileName": {
32+
"commandName": "Project",
33+
"commandLineArgs": "MyFirstArgument MySecondArgument"
34+
}
35+
}
36+
}
37+
```
38+
39+
### Approach 2: `launch.json`
40+
41+
If you are using the `coreclr` or `clr` debug adapter type in VS Code, command-line arguments are stored in your `<workspace_root>/.vscode/launch.json`. To edit them in this case:
42+
43+
1. Open up `<workspace_root>/.vscode/launch.json`
44+
2. Find the `coreclr` or `clr` launch configuration you want to launch
45+
3. Edit the `args` property. This can either be a string, or an array of strings
46+
47+
## Configuring launchSettings.json
1448

15-
## Configuring VS Code's debugging behavior
49+
With C# Dev Kit, you can bring your `launchSettings.json` from Visual Studio to work with Visual Studio Code
1650

17-
### PreLaunchTask
51+
Example:
52+
53+
```json
54+
{
55+
"iisSettings": {
56+
"windowsAuthentication": false,
57+
"anonymousAuthentication": true,
58+
"iisExpress": {
59+
"applicationUrl": "http://localhost:59481",
60+
"sslPort": 44308
61+
}
62+
},
63+
"profiles": {
64+
"EnvironmentsSample": {
65+
"commandName": "Project",
66+
"dotnetRunMessages": true,
67+
"launchBrowser": true,
68+
"applicationUrl": "https://localhost:7152;http://localhost:5105",
69+
"environmentVariables": {
70+
"ASPNETCORE_ENVIRONMENT": "Development"
71+
}
72+
},
73+
"EnvironmentsSample-Staging": {
74+
"commandName": "Project",
75+
"dotnetRunMessages": true,
76+
"launchBrowser": true,
77+
"applicationUrl": "https://localhost:7152;http://localhost:5105",
78+
"environmentVariables": {
79+
"ASPNETCORE_ENVIRONMENT": "Staging",
80+
"ASPNETCORE_DETAILEDERRORS": "1",
81+
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
82+
}
83+
},
84+
"EnvironmentsSample-Production": {
85+
"commandName": "Project",
86+
"dotnetRunMessages": true,
87+
"launchBrowser": true,
88+
"applicationUrl": "https://localhost:7152;http://localhost:5105",
89+
"environmentVariables": {
90+
"ASPNETCORE_ENVIRONMENT": "Production"
91+
}
92+
},
93+
"IIS Express": {
94+
"commandName": "IISExpress",
95+
"launchBrowser": true,
96+
"environmentVariables": {
97+
"ASPNETCORE_ENVIRONMENT": "Development"
98+
}
99+
}
100+
}
101+
}
102+
```
103+
104+
## Profile properties
105+
106+
* `commandLineArgs` - The arguments to pass to the target being run.
107+
* `executablePath` - An absolute or relative path to the executable.
108+
* `workingDirectory` - Sets the working directory of the command.
109+
* `launchBrowser` - Set to `true` if the browser should be launched.
110+
* `applicationUrl` - A semi-colon delimited list of URL(s) to configure for the web server.
111+
* `sslPort` - The SSL port to use for the web site.
112+
* `httpPort` - The HTTP port to use for the web site.
113+
114+
# List of configurable options
115+
116+
Below are common options you may want to change while debugging.
117+
118+
## PreLaunchTask
18119

19120
The `preLaunchTask` field runs the associated taskName in `tasks.json` before debugging your program. You can get the default build prelaunch task by executing the command **Tasks: Configure Tasks Runner** from the VS Code Command Palette.
20121

@@ -194,9 +295,9 @@ Example:
194295

195296
![Example of inputting text to the Console to be set to the target process's standard input](images/debugging/console-input.gif)
196297

197-
## launchSettings.json support
298+
## `launchSettingsProfile` and `launchSettingsFilePath`
198299

199-
In addition to `launch.json`, launch options can be configured through a `launchSettings.json` file. The advantage of `launchSettings.json` is that it allows settings to be shared between Visual Studio Code, full Visual Studio, and `dotnet run`.
300+
While full support for `launchSettings.json` requires use of a launch configuration with `"type": "dotnet"`, the `coreclr` and `clr` debugger types also support a limited subset of `launchSettings.json` functionality. This is useful for users who want to use the same settings in both Visual Studio Code and full Visual Studio.
200301

201302
To configure which `launchSettings.json` profile to use (or to prevent it from being used), set the `launchSettingsProfile` option:
202303

@@ -221,9 +322,9 @@ Which would then, for example, use `myVariableName` from this example `launchSet
221322

222323
If `launchSettingsProfile` is NOT specified, the first profile with `"commandName": "Project"` will be used.
223324

224-
If `launchSettingsProfile` is set to null/an empty string, then Properties/launchSettings.json will be ignored.
325+
If `launchSettingsProfile` is set to null/an empty string, then `Properties/launchSettings.json` will be ignored.
225326

226-
By default, the debugger will search for `launchSettings.json` in {cwd}/Properties/launchSettings.json. To customize this path, set `launchSettingsFilePath`:
327+
By default, the debugger will search for `launchSettings.json` in `{cwd}/Properties/launchSettings.json`. To customize this path, set `launchSettingsFilePath`:
227328

228329
```json
229330
"launchSettingsFilePath": "${workspaceFolder}/<Relative-Path-To-Project-Directory/Properties/launchSettings.json"
@@ -510,73 +611,6 @@ Example:
510611
* `settings.json` ❌
511612
* `launchSettings.json` ✔️ as `useSSL`
512613

513-
## Configuring launchSettings.json
514-
515-
With C# Dev Kit, you can bring your `launchSettings.json` from Visual Studio to work with Visual Studio Code
516-
517-
Example:
518-
519-
```json
520-
{
521-
"iisSettings": {
522-
"windowsAuthentication": false,
523-
"anonymousAuthentication": true,
524-
"iisExpress": {
525-
"applicationUrl": "http://localhost:59481",
526-
"sslPort": 44308
527-
}
528-
},
529-
"profiles": {
530-
"EnvironmentsSample": {
531-
"commandName": "Project",
532-
"dotnetRunMessages": true,
533-
"launchBrowser": true,
534-
"applicationUrl": "https://localhost:7152;http://localhost:5105",
535-
"environmentVariables": {
536-
"ASPNETCORE_ENVIRONMENT": "Development"
537-
}
538-
},
539-
"EnvironmentsSample-Staging": {
540-
"commandName": "Project",
541-
"dotnetRunMessages": true,
542-
"launchBrowser": true,
543-
"applicationUrl": "https://localhost:7152;http://localhost:5105",
544-
"environmentVariables": {
545-
"ASPNETCORE_ENVIRONMENT": "Staging",
546-
"ASPNETCORE_DETAILEDERRORS": "1",
547-
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
548-
}
549-
},
550-
"EnvironmentsSample-Production": {
551-
"commandName": "Project",
552-
"dotnetRunMessages": true,
553-
"launchBrowser": true,
554-
"applicationUrl": "https://localhost:7152;http://localhost:5105",
555-
"environmentVariables": {
556-
"ASPNETCORE_ENVIRONMENT": "Production"
557-
}
558-
},
559-
"IIS Express": {
560-
"commandName": "IISExpress",
561-
"launchBrowser": true,
562-
"environmentVariables": {
563-
"ASPNETCORE_ENVIRONMENT": "Development"
564-
}
565-
}
566-
}
567-
}
568-
```
569-
570-
## Profile Properties
571-
572-
* `commandLineArgs` - The arguments to pass to the target being run.
573-
* `executablePath` - An absolute or relative path to the executable.
574-
* `workingDirectory` - Sets the working directory of the command.
575-
* `launchBrowser` - Set to true if the browser should be launched.
576-
* `applicationUrl` - A semi-colon delimited list of URL(s) to configure for the web server.
577-
* `sslPort` - The SSL port to use for the web site.
578-
* `httpPort` - The HTTP port to use for the web site.
579-
580614
## See Also
581615

582616
* [launchSettings.json schema](https://json.schemastore.org/launchsettings.json)

0 commit comments

Comments
 (0)