|
| 1 | +# Configurating launch.json for C# debugging |
| 2 | +The launch.json file is used to configure the debugger in Visual Studio Code. |
| 3 | + |
| 4 | +Visual Studio Code generates a launch.json with almost all of the required information. |
| 5 | +If your workspace has only one launchable project, the C# extension will offer to automatically generate this file. |
| 6 | +If you missed this prompt, you can force the generation by executing the command `.NET: Generate Assets for Build and Debug` from the VS Code command palette. |
| 7 | +The generated file contains two sections. One that configures debugging for launch and a second that configures debugging for attach. |
| 8 | + |
| 9 | +If you have more than one launchable project, then you will need to modify your launch.json file by hand. |
| 10 | +Visual Studio Code will still generate a basic template, but you will need to fill in the 'program' field to point at the executable dll that you would like to debug. |
| 11 | + |
| 12 | + |
| 13 | +# Configurating VS Code's debugging behavior |
| 14 | + |
| 15 | +## PreLaunchTask |
| 16 | +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. |
| 17 | + |
| 18 | +This will create a task that runs `dotnet build`. You can read more about tasks at [https://code.visualstudio.com/docs/editor/tasks](https://code.visualstudio.com/docs/editor/tasks). |
| 19 | + |
| 20 | +## Program |
| 21 | +The program field is set to the path to the application dll or .NET Core host executable to launch. |
| 22 | + |
| 23 | +Example: "${workspaceRoot}/bin/Debug/\<target-framework\>/\<project-name.dll\>" where: |
| 24 | + |
| 25 | +* \<target-framework\>: (example: 'netstandard1.5') This is the framework that the app is being built for. It is set in the project.json file. |
| 26 | +* \<project-name\>: (example: 'MyApp') The name of the project being debugged.", |
| 27 | + |
| 28 | +## Cwd |
| 29 | +The working directory of the target process. |
| 30 | + |
| 31 | +## Args |
| 32 | +These are the arguments that will be passed to your program. |
| 33 | + |
| 34 | +## Stop at Entry |
| 35 | +If you need to stop at the entry point of the target, you can optionally set `stopAtEntry` to be "true". |
| 36 | + |
| 37 | +## Launch Browser |
| 38 | +The launch browser field can be optionally added if you need to launch with a web browser. |
| 39 | +If there are web server dependencies in your project.json, the auto generated launch file will add launch |
| 40 | +browser for you. It will open with the default program to handle URLs. |
| 41 | + |
| 42 | +## Environment variables |
| 43 | +Environment variables may be passed to your program using this schema: |
| 44 | + |
| 45 | + "env": { |
| 46 | + "myVariableName":"theValueGoesHere" |
| 47 | + } |
| 48 | + |
| 49 | +## Console (terminal) window |
| 50 | +By default, processes are launched with their console output (stdout/stderr) going to the VS Code Debugger Console. This is useful for executables that take their input from the network, files, etc. But this does NOT work for applications that want to read from the console (ex: `Console.ReadLine`). For these applications, use a setting such as the following: |
| 51 | + |
| 52 | + "console": "integratedTerminal" |
| 53 | + |
| 54 | +When this is set to `integratedTerminal` the target process will run inside [VS Code's integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal). Click the 'Terminal' tab in the tab group beneath the editor to interact with your application. |
| 55 | + |
| 56 | +When this is set to `externalTerminal` the target process will run in a separate terminal. |
| 57 | + |
| 58 | +## Source File Map |
| 59 | +You can optionally configure a file by file mapping by providing map following this schema: |
| 60 | + |
| 61 | + "sourceFileMap": { |
| 62 | + "C:\foo":"/home/me/foo" |
| 63 | + } |
| 64 | + |
| 65 | +## Symbol Path |
| 66 | +You can optionally provide paths to symbols following this schema: |
| 67 | + |
| 68 | + "symbolPath": [ "/Volumes/symbols" ] |
| 69 | + |
| 70 | +## Just My Code |
| 71 | +You can optionally disable `justMyCode` by setting it to "false". You should disable Just My Code when you are trying to debug into a library that you pulled down which doesn't have symbols or is optimized. |
| 72 | + |
| 73 | + "justMyCode":false* |
| 74 | + |
| 75 | +Just My Code is a set of features that makes it easier to focus on debugging your code by hiding some of the details of optimized libraries that you might be using, like the .NET Framework itself. The most important sub parts of this feature are -- |
| 76 | + |
| 77 | +* User-unhandled exceptions: automatically stop the debugger just before exceptions are about to be caught by the framework |
| 78 | +* Just My Code stepping: when stepping, if framework code calls back to user code, automatically stop. |
| 79 | + |
| 80 | +## Require Exact Source |
| 81 | +The debugger requires the pdb and source code to be exactly the same. To change this and disable the sources to be the same add: |
| 82 | + |
| 83 | + "requireExactSource": false |
| 84 | + |
| 85 | +## Stepping into properties and operators |
| 86 | +The debugger steps over properties and operators in managed code by default. In most cases, this provides a better debugging experience. To change this and enable stepping into properties or operators add: |
| 87 | + |
| 88 | + "enableStepFiltering": false |
| 89 | + |
| 90 | +## Logging |
| 91 | +You can optionally enable or disable messages that should be logged to the output window. The flags in the logging field are: 'exceptions', 'moduleLoad', 'programOutput', 'engineLogging', and 'browserStdOut'. |
| 92 | + |
| 93 | +## PipeTransport |
| 94 | +If you need to have the debugger to connect to a remote computer using another executable to relay standard input and output bewteen VS Code and the .NET Core debugger backend (vsdbg), |
| 95 | +then add the pipeTransport field folloing this schema: |
| 96 | + |
| 97 | + "pipeTransport": { |
| 98 | + "pipeProgram": "ssh", |
| 99 | + "pipeArgs": [ "-T", "ExampleAccount@ExampleTargetComputer" ], |
| 100 | + "debuggerPath": "~/vsdbg/vsdbg", |
| 101 | + "pipeCwd": "${workspaceRoot}", |
| 102 | + "quoteArgs": true |
| 103 | + } |
| 104 | + |
| 105 | +More information about pipe transport can be found [here](https://github.com/OmniSharp/omnisharp-vscode/wiki/Attaching-to-remote-processes). |
| 106 | + |
| 107 | +You can find information on configuring pipe transport for [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) (WSL) [here](https://github.com/OmniSharp/omnisharp-vscode/wiki/Windows-Subsystem-for-Linux). |
| 108 | + |
| 109 | +## Operating System Specific Configurations |
| 110 | +If there specific commands that need to be changed per operating system, you can use the fields: 'windows', 'osx', or 'linux'. |
| 111 | +You can replace any of the fields mentioned above for the specific operating system. |
| 112 | + |
0 commit comments