You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Explore improving the single file debug experience #92269
Today VS Code debugging has no generic way to know whether a debug extension implements "single file debugging". Without this knowledge it is not possible to provide a standardised UX experience for this case.
Because of this some debug extension have started to create their own UI. A good example is the Python extension which shows a play button in the editor:
based on language type of current editor all debug extensions are searched that are configured for that language (languages property in the debuggers contribution).
if more than one is found, a Quickpick is used to let user pick one debug extension
the extension is activated
if the extension implements resolveDebugConfiguration, it is called with an empty in-memory launch config
If the debug extension supports "single-file debugging without launch.json", it understands the empty in-memory launch config and "upgrades" it, so that it starts debugging on the file that is open in the editor.
if no extension can be found or if an extension doesn't support the "single-file debugging without launch.json" nothing happens.
Andre Weinand (@weinand) yes this is faithful description of the current flow.
Just a nitpick: if no extension can be found we do not open launch.json. We will only open launch.json if an extension explicitly tells us to do that by returning null.
changed the title [-]Explore improving the debug experience when a single file is open without a launch config[/-][+]Explore improving the single file debug experience[/+]on Mar 24, 2020
What are the problems/paint points that we try to address?
A first pair of problems is related to the fact that VS Code behaves differently if the workspace has a "launch.json" or not:
Assuming that no "launch.json" exists in the workspace, VS Code does not know (upfront) whether a project (workspace) is debuggable, e.g. whether pressing a play button would successfully start a debug session. Corollary: VS Code does not know the reason why a project (workspace) is not in a debuggable state either. These problems makes it difficult to offer a robust "Run" button in the Welcome view. If the debug extension does not support "single-file debugging without launch.json", pressing "Run" does nothing (and we do not really know why and cannot help the user).
If a launch.json exists, VS Code assumes that the user uses it exclusively (by selecting a launch config and executing it) and no smartness is employed. Even if a debug extension implements the "single-file debugging without launch.json" scenario, it is no longer available in the UI. That's the reason why the Python debug extension adds a "Play" button to the editor: with this button a user can quickly and easily override a currently selected launch config and start debugging on the file open in the editor.
Another problem comes from the fact that VS Code does not want to activate debug extensions eagerly. As a consequence VS Code can only rely on the declarative information available in the package.json but not on running extension code.
Today VS Code only knows the supported languages of a debugger. This information is used in the "single-file debugging without launch.json" scenario for activating a debug extension based on the language open in the current editor. But this mechanism does not work if a file with an unsupported language is open in the editor or if there is no file open at all. Running extension code could easily figure out that the project (workspace) is runnable/debuggable. E.g. it could determine the entry-point of the project by analysing the package.json. (Actually this code exists already in many debug extensions but it cannot be used without activating the debug extension).
"Run without debugging":
DAP defines protocol for "Run without debugging" and VS Code implements it, but not all debug extensions are implementing it.
Since there is no way to figure out whether a debug extension implements the "Run without debugging", VS Code always provides UI for "Run without debugging" even if the debugger doesn't support it. Typically this is not a big problem because a debug extension will fall back to "Debug" if "Run without debugging" is not implemented.
Some proposals (in no specific order):
Introduce explicit extension API (e.g. provideWorkspaceDebugConfiguration) to have the debug extension communicate back to VS Code the following information:
whether debug extension supports a "Run/Debug" in the current situation (without relying on launch.json or relying on an active file in the editor)
if the debug extension cannot figure out what to run/debug, it should report back a message explaining why run/debug doesn't work and what to do.
VS Code would use this API for the Welcome view and "F5" (if no launch.json exists and there is no active file). E.g. in the a Node.js this API could find the program's entry point in the package.json. Today the resolveDebugConfiguration is able to launch the program in that case but we are not able to show a Play button if the user has the package.json open in the editor.
If "run/debug" is not possible the welcome view could show how to fix this.
Introduce explicit API for running/debugging a file (or resource?), e.g. provideFileDebugConfiguration or provideResourceDebugConfiguration. VS Code would use this API for supporting a "Play" button in the editor.
Introduce new API for determining whether the DA supports the "noDebug" mode (surfaced as "Run without debugging"). I'm not sure whether it is sufficient to add this to the DAP or whether this must be extension API or just a new attribute on the "debuggers" contribution (dependent on the location of the API the info would be available statically, dynamically on extension activation, or dynamically on debug session start).
the problems resulting from the fact that VS Code tries to avoid activating debug extensions eagerly are more difficult to solve. Possible approaches:
activate at least one debug extension eagerly based on historic information from previous debug sessions. We have this information already as a "when" context.
try to match an active language extension automatically with the corresponding debugger extension. This is based on the assumption, that a beginning user starting a Python project most likely needs a Python debugger.
How to design the APIs?
Today some of the debug extension APIs revolve around "debug configurations" (provideDebugConfigurations, resolveDebugConfiguration, startDebugging).
To continue this "style", I propose that new APIs follow suit:
instead of introducing a new API for "start debugging a workspace/project" or "start debugging a file", we could introduce a new function provideDebugConfiguration(options) that based on the passed ´options´ returns a debug configuration (or an descriptive error if debugging isn't possible). The debug configuration can be passed to startDebugging to actually launch a debug session. Since provideDebugConfiguration(options) does not start the debug session itself, it can be used for probing whether debugging is possible.
Good analysis of our current limitations. I can brainstorm on potential ideas on how to solve some of these, but you might be already writing this, so let me know once you are looking for feedback. Thanks!
In order to know if VS Code should put a Play button in the editor title VS Code should ask all activated debug extensions if they support a Play button for that file. If any of them do, the Play action should be there. The extensino can not decide this based on VS Code api, but VS Code debug UX would have to pass the file / uri for who it is asking. Because there can be inactive editors opened side by side.
This could be done by your proposel of provideDebugConfiguration. VS Code would simply call this for any visible editor for all adapters, and if there is 'candidate' we would show the play button.
Extension activation
I do not see the issues of extensions not being activated. If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type.
To make this discussions more scoped and tue to the previous reason I suggest to handle the issue of extension activation seperatly.
If you think we should solve this with this issue what would be the example scenario where the extension is not activated? The only scenario I see is I just opened a workspace and I did not open a file, I just want to press F5 to run. However that seems unrelated to the single file discussion.
Run without debugging
This sounds best fitted for a static contribution point via package.json imho. However if a debug extension says no to this how would that change the VS Code debug ux experience. Just some actions would be disabled?
Play Button:
"should ask all activated debug extensions": yes, but the "activated" is already a problem: if a user has created a new Python file, the debugger is not activated and no Play button will be shown. This can be solved by either adding some static contribution point attribute ("supportsFileDebug") or by activating the debug extension together with the language extension and using the proposed provideFileDebugConfiguration.
Extension Activation:
"what would be the example scenario where the extension is not activated": see above.
You said: "If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type." With "extension" you mean language extension, right? But language extension and debugger extension do not yet have a dependency. So activating the language extension does not activate the debugger extension.
Run without Debugging:
Yes, with a contribution point attribute we could more precisely show/hide the actions: e.g. no "Run without Debugging" if the extension does not support it. If the contribution point attribute
is missing we would fall back to the current imprecise behavior.
I have introduced the run group to the Editor Title area as we agreed upon, the run group is left of the navigation group.
I have also adopted this in Mock Debug via this commit. I have used the order 10 and 20 to give the group more flexibility if other extensions want to introduce actions between these.
After discussion we decided to go with the group name 1_run to be better aligned with the current group names.
I have updated our docs to reflect the new group name.
To recap Andre Weinand (@weinand) and me came up with the following recommendations for debug extensions (we will also cover this in our release notes):
Use the $(play) icon for Run, $(debug-alt-small) for debug
Put actions in the 1_run group, use order 10 and 20.
Use title "Run File" and "Debug File" or "Run Python File" and "Debug Python File"
Put either one or two actions based on your use case
Try to not to put other debug actions, if those are needed please let us know so we think about having a consistent experience
To verify: clone the mock debug repo from here, run the extension and make sure the commands are properly contributed for every markdown file in the editor title area.
After discussion we decided to go with the group name 1_run to be better aligned with the current group names.
I have updated our docs to reflect the new group name.
To recap Andre Weinand (@weinand) and me came up with the following recommendations for debug extensions (we will also cover this in our release notes):
Use the $(play) icon for Run, $(debug-alt-small) for debug
Put actions in the 1_run group, use order 10 and 20.
Use title "Run File" and "Debug File" or "Run Python File" and "Debug Python File"
Put either one or two actions based on your use case
Try to not to put other debug actions, if those are needed please let us know so we think about having a consistent experience
To verify: clone the mock debug repo from here, run the extension and make sure the commands are properly contributed for every markdown file in the editor title area.
As for the $(play) and $(debug-alt) we simply need to resize them so they are the same size and aligned. Looking at them the problem is the debug-alt which is not designed to be used in a horisontal action bar. We should resize it, and if that is not possible (activity bar might get broken) then we simply need to introduce a new codicon. @misolori is it possible that you look into this?
Is this being tracked anywhere? It definitely looks a bit weird right now with different sizes.
Isidor Nikolic (@isidorn) aha, perfect - already shipped! :) I copied the original name (from #92269 (comment)) so if that's the main source for this info, might be worth editing in there (I did check the release notes, but it didn't seem to include the specifics).
Activity
weinand commentedon Mar 20, 2020
How "single-file debugging" works today:
languagesproperty in thedebuggerscontribution).resolveDebugConfiguration, it is called with an empty in-memory launch configIsidor Nikolic (@isidorn) is that a faithful description of the current behavior?
isidorn commentedon Mar 20, 2020
Andre Weinand (@weinand) yes this is faithful description of the current flow.
Just a nitpick: if no extension can be found we do not open
launch.json. We will only openlaunch.jsonif an extension explicitly tells us to do that by returningnull.[-]Explore improving the debug experience when a single file is open without a launch config[/-][+]Explore improving the single file debug experience[/+]weinand commentedon Mar 25, 2020
What are the problems/paint points that we try to address?
A first pair of problems is related to the fact that VS Code behaves differently if the workspace has a "launch.json" or not:
Another problem comes from the fact that VS Code does not want to activate debug extensions eagerly. As a consequence VS Code can only rely on the declarative information available in the package.json but not on running extension code.
Today VS Code only knows the supported languages of a debugger. This information is used in the "single-file debugging without launch.json" scenario for activating a debug extension based on the language open in the current editor. But this mechanism does not work if a file with an unsupported language is open in the editor or if there is no file open at all. Running extension code could easily figure out that the project (workspace) is runnable/debuggable. E.g. it could determine the entry-point of the project by analysing the package.json. (Actually this code exists already in many debug extensions but it cannot be used without activating the debug extension).
"Run without debugging":
DAP defines protocol for "Run without debugging" and VS Code implements it, but not all debug extensions are implementing it.
Since there is no way to figure out whether a debug extension implements the "Run without debugging", VS Code always provides UI for "Run without debugging" even if the debugger doesn't support it. Typically this is not a big problem because a debug extension will fall back to "Debug" if "Run without debugging" is not implemented.
Some proposals (in no specific order):
Introduce explicit extension API (e.g.
provideWorkspaceDebugConfiguration) to have the debug extension communicate back to VS Code the following information:VS Code would use this API for the Welcome view and "F5" (if no launch.json exists and there is no active file). E.g. in the a Node.js this API could find the program's entry point in the package.json. Today the
resolveDebugConfigurationis able to launch the program in that case but we are not able to show a Play button if the user has the package.json open in the editor.If "run/debug" is not possible the welcome view could show how to fix this.
Introduce explicit API for running/debugging a file (or resource?), e.g.
provideFileDebugConfigurationorprovideResourceDebugConfiguration. VS Code would use this API for supporting a "Play" button in the editor.Introduce new API for determining whether the DA supports the "noDebug" mode (surfaced as "Run without debugging"). I'm not sure whether it is sufficient to add this to the DAP or whether this must be extension API or just a new attribute on the "debuggers" contribution (dependent on the location of the API the info would be available statically, dynamically on extension activation, or dynamically on debug session start).
the problems resulting from the fact that VS Code tries to avoid activating debug extensions eagerly are more difficult to solve. Possible approaches:
How to design the APIs?
Today some of the debug extension APIs revolve around "debug configurations" (
provideDebugConfigurations,resolveDebugConfiguration,startDebugging).To continue this "style", I propose that new APIs follow suit:
instead of introducing a new API for "start debugging a workspace/project" or "start debugging a file", we could introduce a new function
provideDebugConfiguration(options)that based on the passed ´options´ returns a debug configuration (or an descriptive error if debugging isn't possible). The debug configuration can be passed tostartDebuggingto actually launch a debug session. SinceprovideDebugConfiguration(options)does not start the debug session itself, it can be used for probing whether debugging is possible.isidorn commentedon Mar 25, 2020
Good analysis of our current limitations. I can brainstorm on potential ideas on how to solve some of these, but you might be already writing this, so let me know once you are looking for feedback. Thanks!
weinand commentedon Mar 25, 2020
Isidor Nikolic (@isidorn) I'm done with my proposals. Please review and provide feedback. Thanks.
weinand commentedon Mar 26, 2020
Discussion will be continued in April.
isidorn commentedon Mar 26, 2020
Good writeup. Some feedback:
Play button
In order to know if VS Code should put a Play button in the editor title VS Code should ask all activated debug extensions if they support a Play button for that file. If any of them do, the Play action should be there. The extensino can not decide this based on VS Code api, but VS Code debug UX would have to pass the file / uri for who it is asking. Because there can be inactive editors opened side by side.
This could be done by your proposel of
provideDebugConfiguration. VS Code would simply call this for any visible editor for all adapters, and if there is 'candidate' we would show the play button.Extension activation
I do not see the issues of extensions not being activated. If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type.
To make this discussions more scoped and tue to the previous reason I suggest to handle the issue of extension activation seperatly.
If you think we should solve this with this issue what would be the example scenario where the extension is not activated? The only scenario I see is I just opened a workspace and I did not open a file, I just want to press
F5to run. However that seems unrelated to the single file discussion.Run without debugging
This sounds best fitted for a static contribution point via
package.jsonimho. However if a debug extension saysnoto this how would that change the VS Code debug ux experience. Just some actions would be disabled?fyi Connor Peet (@connor4312) roblourens
weinand commentedon Mar 30, 2020
Isidor Nikolic (@isidorn) thanks for the feedback.
Play Button:
"should ask all activated debug extensions": yes, but the "activated" is already a problem: if a user has created a new Python file, the debugger is not activated and no Play button will be shown. This can be solved by either adding some static contribution point attribute ("supportsFileDebug") or by activating the debug extension together with the language extension and using the proposed
provideFileDebugConfiguration.Extension Activation:
"what would be the example scenario where the extension is not activated": see above.
You said: "If the extension is not activated then 99% it can not handle the open file, since it would already activated on that file type." With "extension" you mean language extension, right? But language extension and debugger extension do not yet have a dependency. So activating the language extension does not activate the debugger extension.
Run without Debugging:
Yes, with a contribution point attribute we could more precisely show/hide the actions: e.g. no "Run without Debugging" if the extension does not support it. If the contribution point attribute
is missing we would fall back to the current imprecise behavior.
39 remaining items
add "run" group to editor title actions
isidorn commentedon Jun 25, 2020
I have introduced the
rungroup to the Editor Title area as we agreed upon, the run group is left of thenavigationgroup.I have also adopted this in Mock Debug via this commit. I have used the order
10and20to give the group more flexibility if other extensions want to introduce actions between these.I will update the docs here https://code.visualstudio.com/api/references/contribution-points#Sorting-of-groups
The open question is should the group be called
0_runwhich is a bit ugly. Will check with Ben.I have created this follow up item for @misolori #101026
Andre Weinand (@weinand) and me can work on finalising on what is the exact recommnedation for extensions and post it here and in the release notes.
title control: use 1_run as a group name
isidorn commentedon Jun 26, 2020
After discussion we decided to go with the group name
1_runto be better aligned with the current group names.I have updated our docs to reflect the new group name.
To recap Andre Weinand (@weinand) and me came up with the following recommendations for debug extensions (we will also cover this in our release notes):
$(play)icon for Run,$(debug-alt-small)for debug1_rungroup, use order10and20.Mock debug example can be found here
fyi Connor Peet (@connor4312) since we could also do this in js-debug
To verify: clone the mock debug repo from here, run the extension and make sure the commands are properly contributed for every markdown file in the editor title area.
weinand commentedon Jul 1, 2020
Verified that the proposal works and looks fine.
The icons are not yet aligned, but I commented here: #101026 (comment)
akaroml commentedon Jul 6, 2020
Jinbo Wang (@testforstephen) please take a look at the recommendations and see how Java debugger can benefit.
testforstephen commentedon Jul 6, 2020
Rome Li (@akaroml) sure, tracked with issue microsoft/vscode-java-debug#834
DanTup commentedon Jul 28, 2020
Isidor Nikolic (@isidorn)
Is this being tracked anywhere? It definitely looks a bit weird right now with different sizes.
isidorn commentedon Jul 28, 2020
Danny Tuppeny (@DanTup) yes, here #101026
DanTup commentedon Jul 28, 2020
Isidor Nikolic (@isidorn) aha, perfect - already shipped! :) I copied the original name (from #92269 (comment)) so if that's the main source for this info, might be worth editing in there (I did check the release notes, but it didn't seem to include the specifics).
Thanks!
isidorn commentedon Jul 28, 2020
Makes sense, I have updated my comments from above. Thanks for pointing this out.