Vscode: Allow debug extensions to provide configurations to display in Select and Start Debugging

[connor4312]

Goals

In some scenarios, it's possible for the debug adapters to provide a quality debugging experience without additional user configuration. For example, the new js-debug can debug npm scripts, and languages where entrypoints are easily identifiable. Go, C#, Java... may offer to debug the program without extra configuration.

In a similar way to how build tasks are provided, we'd like the ability to provide default run tasks that show up under the Select and Start Debugging quick-pick.

Proposal

Launch configurations already have an optional presentation key, with the following properties (this interface is not exposed in vscode.d.ts):

export interface IConfigPresentation {
    hidden?: boolean;
    group?: string;
    order?: number;
}

This proposes adding a new property:

export interface IConfigPresentation {
+   locations: ('debug.start' | 'debug.selectandstart' | 'debugView')[];

When set, this configures the locations in the UI where the returned configuration is displayed. If not provided, the locations returned from DebugConfigurationProvider.provideDebugConfigurations default to ['debug.start']. provideDebugConfigurations would now be called when the select and start quick-pick is opened to retrieve configurations to display.

Questions

• Why are we proposing this over the existing initial configuration/F5 experience?

  • It's hard (impossible?) to discover if you have any configured launch configurations, you don't get the quick pick again;
  • Start debugging is contextual to the active text editor file, where the these tasks are intended to be project-level.

• Should we surface all existing provided configurations in select and start?

  • + this would require no change to existing adapters
  • - existing returned tasks are contextual to the active editor, while select and start currently only displays project-level configurations.
  • - the names of most existing tasks are simply "Node.js" or "Go", which don't provide explaination and would confuse users in select and start.

• Should there be a separate method to return the pick-able configurations?

  • + in this proposal, we start calling provideDebugConfigurations more frequently, which may lead to side-effects or slowdowns; a separate method avoids that.
  • + this proposal is somewhat of an overload to the existing method to potentially return a new (non-contextual) type of task.
  • - this proposal has a smaller API and the property fits in well with the presentation properties
  • - the API here allows configurations to be surfaced in multiple locations easily, including "Run and Debug" if we want to allow that.

• ~Should we also be able to provide default configurations for the "Run and Debug" dropdown in the debug view?~ added

  • + this is most discoverable for users who don't enter through the command palette
  • + allowing this as an option in locations would let consumers in launch.json take advantage of it, rather than hidden: true/false.
  • - in cases where there are many discovered tasks (e.g. lots of npm scripts) this could get noisy
  • - would we need to call provideDefaultLaunchConfigurations every time the debug view is opened? If files change, would we call that again?

cc @isidorn @roblourens @weinand

https://github.com/microsoft/vscode-js-debug/issues/197

[roblourens]

Are you saying that when the user presses F5 and sees this:

Then there would be a second quick pick with the list of possible launch configs? Or that they would show up in a dropdown in the viewlet like configured ones?

I could see a flow like we do for tasks, where you see the list of autodetected configs, but then it prompts you to "configure" that task by adding it to a tasks.json file.

[connor4312]

In Select and Start Debugging

There would be a new section with discovered configuration, something like:

I imagine selecting those would immediately run the chosen configuration. I think it would be good to allow the user some way to persist the config into their launch.json file, but I'm not sure the best way for that interaction to work. Perhaps discovered configs appear as intellisense autocompletion entries while editing launch.json?

[roblourens]

Oh I didn't know that's what that menu was called, yeah it is similar to tasks then, where we show configured and detected tasks.

One annoying thing about this for tasks is that the detection slows down showing that menu. But I think the discovery that debuggers do is probably simpler than that for tasks.

[connor4312]

I don't see an API for it, but it would be nice to have a way to update the items in a quick pick after instantiation. That'd allow us to show some 'loading' placeholder to avoid delaying the pick opening. But yes I think the debug discovery should generally be simple.

[isidorn]

I think this makes sense overall to me.
If I understand everything correctly you want to provide dynamic launch configuraitons which are not written in launch.json. This sounds like a duplicate of https://github.com/microsoft/vscode/issues/54212
Since that issue was driven by @weinand I will let him comment here

As for where we surface this in the UX we can sync on that once we figure out the API. The select and start is not so discoverable, so I would push more that we just show them everywhere when it makes sense.

[connor4312]

I think that showing them by default in debug view's dropdown would be nice for discoverability. But I think it's important to be able to easily turn them off; once I have my project built and set up with custom launch configs, I may no longer need any of the auto-discovered tasks. Maybe the gear beside the dropdown turns into a menu with the options [x] Auto-discover configurations, Edit launch.json.

I also want to be careful to avoid cluttering the dropdown like build tasks can get.

I'll update the proposal to add debugView as a possible location.

[weinand]

If I understand this request correctly, I can break it down into one new VS Code feature and two independent API requests:

• New feature: a new locations property in a launch config's presentation section determines where in the UI VS Code will show the launch config. This feature is independent from the extension API and applies to launch configurations in general: for every launch config the locations attribute can be used to determine where it appears in the UI.
• API for contributing launch configurations dynamically (somewhat related to #54212 as pointed out by @isidorn). But as already discussed in #54212, I think it is questionable whether an "in-memory-only debug configuration" is really that useful. In #54212 we concluded that regular VS Code "commands" are a more useful abstraction. That means that we could use existing extension API for contributing commands to the debug UI. And the provideDebugConfigurations hook should only be used to contribute the "source" of launch configs to launch.json but not for a more dynamic use in the UI where the source is not visible (and editable) to the end user. The npm: run start command shown above in the screenshot is a good example for this approach: instead of wrapping a npm script into an internal (in-memory) "launch config", we could just contribute a "run task" command to the debug QuickPick.
• API request: reflect the new presentation attribute of debug configurations properly in the extension API (including the new locations attribute). Here is my take on that:
  ```ts
  export interface DebugConfiguration {
  // ...
  presentation?: DebugConfigPresentation;
  }

export interface DebugConfigPresentation {
    hidden?: boolean;
    group?: string;
    order?: number;
    locations?: DebugUILocation[];
}

export type DebugUILocation = 'debug.start' | 'debug.selectandstart' | 'debugView';

```

IMO the first and the last items make complete sense but the second item needs more discussion. I've removed the "api-proposal" for now and added a "feature-request" label.

[connor4312]

• ✅
• The downside of contributing the command would be that we can't expand them dynamically (e.g. a single action for npm scripts). But that would solve the bloat issue, the concerns about adding additional calls to provideDebugConfigurations, and performance questions when opening select and start and run and debug, so I like that approach 🙂
• Adding locations in the API would be less useful with the command approach since adapters only emit it in a meaningful way from the existing provideDebugConfigurations where display intent probably is not known. I can't think of when I'd want to use it off the top of my head, but someone might find cases for it.

[weinand]

After revisiting this API feature request and investigating how to improve "single file debugging" I got some new insights:

In bullet item two of my comment above I had argued that the value of "in-memory-only debug configuration" is questionable because there is no need for editing them. Instead we could just allow to add regular commands to the debug configuration drop-down menu (and other places).

But now after having reviewed what "tasks" is doing and what other feature requests (e.g. #92269) are asking for, I'm leaning more towards the following "homogenous" approach (similar to "tasks"):

• there is only a single type of debug configuration: the JSON-based one a user sees in the launch.json. The downside of this is that regular commands need to be wrapped as debug configurations but the advantage is, that there is an editable representation for them (see below).
  
  
  
  • a debug configuration has optional presentation hints for controlling where it is shown in the UI.
  
  
  • expanded debug extension API for creating debug configuration in the following situations:
  
  
  • initial ("static") debug configurations for launch.json (API already exists)
  
  
  • a debug configuration for starting debugging a "workspace-project" (new API proposed in #92269)
  
  
  • a debug configuration for starting debugging of a file (new API proposed in #92269)
  
  
  • "dynamic" debug configurations, e.g. generated for npm scripts from package.json (new API proposed here),
  
  
  • all debug configurations can be launched with the startDebugging API (API exists).
  
  
  • all debug configurations can be easily added as JSON to a launch.json and become available for further customization (today we only have UX for the initial (empty) launch.json case; additional debug configs can be added via snippets),
  
  

Since we are not introducing new types of debug configurations, the VS Code implementation does not require big changes.

Work needed:

• calling into debug extensions for acquiring the dynamic launch configs,
• supporting the presentation hints,
• optional: designing UX for adding dynamic debug configurations to launch.json

---

Proposed API:

/**
 * Debug UI locations.
 */
export type DebugUILocation = 'debug.start' | 'debug.selectandstart' | 'debugView';

/**
 * How a debug configuration is presented in the UI.
 */
export interface DebugConfigPresentation {
  hidden?: boolean;
  group?: string;
  order?: number;
  locations?: DebugUILocation[];
}

/**
 * Configuration for a debug session.
 */
export interface DebugConfiguration {
  // ...
  presentation?: DebugConfigPresentation;
}

export interface DebugConfigurationProvider {
  /**
   * Provides [debug configuration](#DebugConfiguration). If more than one debug configuration provider is
   * registered for the same type, debug configurations are concatenated in arbitrary order.
   *
   * @param token A cancellation token.
   * @return An array of [debug configurations](#DebugConfiguration).
   */
  provideDynamicDebugConfigurations?(token?: CancellationToken): ProviderResult<DebugConfiguration[]>;
}

[isidorn]

This makes good sense to me and feels like a natural progression of the current api.

Some minor comments:
1) Can you clarify a bit the DebugUILocation each value and how would that look in the UI - I confess I did not read the whole discussion before the last comment. debug.start I guess it is only in the drop down, but why would we have a configuration which is only available in the selectandstart? These two experiences need to be aligned imho. Also what does debugView mean
2) Should the provideDynamicDebugConfigurations also get a folder: WorkspaceFolder | undefined as an argument. And in multi root workspaces we would call it for each folder.
3) We would call this provideDynamicDebugConfigurations as soon as each debug extension gets activated. Does that make sense?
4) We can always have a "Pin configuration" command / button which just writes it into launch.json
5) provideDebugConfiguariotns seems like a good name for this, however since that one is already taken using the word dynamic makes sense, however something more cleaner would be even better. I do not have good ideas...

[awschristou]

Should the provideDynamicDebugConfigurations also get a folder: WorkspaceFolder | undefined as an argument. And in multi root workspaces we would call it for each folder.

It would be ideal if provideDynamicDebugConfigurations was called more often then during extension activation. If an implementation returned configurations based on workspace contents, it would be great for users to be able to update those contents, and have extensions offer up corresponding configurations without requiring an extension restart.

[weinand]

@isidorn @awschristou thanks for the feedback.

Here my replies to the bullets:

1. We have different locations in the UI where we show debug configurations: the drop down menu in the debug viewlet, the "Select and Start Debugging" command, the Welcome View. With the locations attribute a provider can control where a debug configuration shows up (to avoid clutter in the UI). The problem with locations is that it semantically overlaps with the hidden presentation attribute, so I'm inclined to drop the locations attribute. @connor4312 could you please try to convince us why we need the locations attribute?
2. provideDynamicDebugConfigurations is modelled after TaskProvider.provideTasks which does not have a folder argument. @dbaeumer and @alexr00 could you please shed some light on why TaskProvider.provideTasks does not need the folder?
3. provideDynamicDebugConfigurations needs to be called whenever we need the list of "auto-discovered" debug configurations. This might be the case when opening the debug configuration drop down menu, or when running the "Select and Start Debugging" command. But we have to be careful not to run into the same scalability issues as tasks (performance and too many configs detected). See https://github.com/microsoft/vscode/issues/88230#issuecomment-572301951.
4. yes, a "Pin configuration" command/button would be a good UX for copying a "auto-discovered" debug configuration into the launch.json for further configuration.
5. yes, provideDynamicDebugConfigurations is not the best name. What's about provideDetectedDebugConfigurations?

[isidorn]

1. Exactly my point I do not see a point for having locations attribute. If a configuration is presented in one place it should be in all for consistency and to avoid user confusion
2. Makes sense, let's see what Alex and Dirk have to say
3. Makes sense, however we need all the option as soon as we construct the debug configuration drop down. Also calling it at different times might give different experiences, for example the user opens the debug viewlet, we need to contruct the debug dropdown thus we call provideDynamicDebugConfigurations. Some time later user exectures select and start debugging command, thus we need to call this again potentialy getting back different results. Point being I am still not too convinced how dynamic this should really be? Now reading @awschristou comment I see the use case. So in practice I think we should call this only once per workspace and as late as possible.
4. great
5. Yeah, I like that name better! Since we might also use that word detected in the UI (for example quick pick grouping name)

[weinand]

to 5: OK then let's use provideDetectedDebugConfigurations.

to 3: In order to have provideDetectedDebugConfigurations return up-to-date information without slowing down the UI, we should use the same strategies as Tasks.

[alexr00]

provideDynamicDebugConfigurations is modelled after TaskProvider.provideTasks which does not have a folder argument. @dbaeumer and @alexr00 could you please shed some light on why TaskProvider.provideTasks does not need the folder?

provideTasks doesn't need the folder because the tasks that the extension returns from provideTasks each have a task source scope, which can specify which folder they belong to.

[connor4312]

1. The idea with location was that having items in "select and start" make the selection harder to use. It's sort of navigable with the keyboard, but is much harder to use this way than a quick pick. I would wager that most users will use their mouse to open and pick an item in this selection box, so if there are a bunch of auto-discovered tasks there, it could be difficult to find what they're looking for. For instance, this is what all my auto discovered tasks in vscode-js-debug look like, and having that within my select and start all the time would be very annoying.

   A nice alternative might be for "select and start" to open a quickpick instead of a <select>.

[weinand]

Incorporating latest feedback:

• the name of the proposed provide...DebugConfiguration method is now provideDetectedDebugConfiguration.
• location attribute: I see the argument that too many detected debug configurations might clutter the UI. But the DebugConfiguration already has a hidden attribute which we can use to hide configurations. I suggest to wait with adding the location attribute until we find the existing hidden attribute to be insufficient.
• passing the WorkspaceFolder to provideDetectedDebugConfiguration: TaskProvider.provideTasks doesn't do this because in their case the implementation of provideTasks has to walk all folders themselves and return the folder as the scope attribute of the found tasks. Since we already have a "twin" method provideDebugConfigurations which takes a WorkspaceFolder as an argument, I suggest that we do the same for provideDetectedDebugConfiguration. As a consequence provideDetectedDebugConfiguration is called for each folder of a multi-folder workspace.

Here is the final proposal:

In some scenarios, it's possible for the debug extension to provide a good debugging experience without need for explicit debug configurations in a launch.json.

For example, the new js-debug can debug npm scripts, and languages where entrypoints are easily identifiable.

In a similar way to how build tasks are provided, we'd like the ability to provide dynamic debug configurations that show up under the "Select and Start Debugging" quick-pick.

The new optional API DebugConfigurationProvider.provideDetectedDebugConfigurations
will be called when VS Code needs to populate the debugging UI with all debug configurations.

export interface DebugConfigurationProvider {
  /**
   * Provide additional "detected" [debug configurations](#DebugConfiguration).
   *
   * @param folder The workspace folder for which the configurations are used or `undefined` for a folderless setup.
   * @param token A cancellation token.
   * @return An array of [debug configurations](#DebugConfiguration).
   */
  provideDetectedDebugConfigurations?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugConfiguration[]>;
}

Alternative name provideAdditionalDebugConfigurations.

[isidorn]

This makes sense from the API perspective to me.
Now we just need to finalize when would VS Code call this API. There were some discussions above but I do not feel like we have reached a final conclussion.

We can call it:

• Whenever the Select and start command is triggered
• For the debug dropdown we use a native selectBox and there do not seem to be any html events when the dropdown is about to be opened. So we can not call the provideDetectedDebugConfigurations then, we can only call it when the dropdown gets constructed, and that is when the debug viewlet gets opened for the first time. If the provideDetectedDebugConfigurations takes a long time we would simply add the resutls to the native dropdown once they are computed.

Also the provideDetectedDebugConfigurations might be called before any other debug method so we need to introduce an activation event
onProvideDetectedDebugConfigurations

[weinand]

Feedback from the API meeting:

• we agreed on provideDynamicDebugConfigurations instead of provideDetectedDebugConfigurations.
• the cancellation token argument must be mandatory.
• Instead of introducing a new method provideDetectedDebugConfigurations we could reuse the existing DebugConfigurationProvider and support to register it for the "dynamic" case (by adding an optional enum argument to registerDebugConfigurationProvider. The default value of this argument would be initialisation (which is the current behavior). Another value would be dynamic. The problem of this elegant approach is that the DebugConfigurationProvider has two additional methods resolveDebugConfiguration... for which the new argument is not applicable (and would be ignored). @jrieken what's your take on this?

[weinand]

@isidorn in order to avoid the performance issues seen with Tasks we should consider to use the "lazy and selective" approach Task is using now:

Initially we would only show the debug types that implement the provideDynamicDebugConfigurations hook but we would call the method only if selected by the user. And from the sub quickpick the user can select a config for execution or for configuration (which moves the config into the launch.json).

If it is difficult to provide the same experience in the debug drop down menu, we could only show the "configured" configs there, but not the "contributed".

@isidorn @connor4312 what do you think?

[isidorn]

@weinand this makes sense to me and could work. However I would first check with @connor4312 how slow will this be in practice, since it might be much faster than Tasks and than it might not be required to optimize.

An alterntive to not showing these in the debug drop down menu: we could have a static entry called: "Detect Configurations" once user picks that we call the provideDetecetedDebugConfigurations and show them via quick pick. We already have some static options there like "Add Configuration" so I think this would align nicely.

[jrieken]

The problem of this elegant approach is that the DebugConfigurationProvider has two additional methods resolveDebugConfiguration... for which the new argument is not applicable (and would be ignored). @jrieken what's your take on this?

Makes it a little less elegant but I think that's something documentation can easily clarify

[weinand]

@isidorn even if Connor's provideDynamicDebugConfigurations is fast, we cannot assume the same for all other debug extensions that will start to use the feature... So it is better to have a solution that addresses scalability upfront.

[awschristou]

@weinand in this proposal, is there an expectation that provideDetectedDebugConfigurations would not return entries that are essentially duplicates of either what is returned from provideDebugConfigurations or are already present in launch.json? Specifically, I am wondering what the experience looks like when the same entry is emitted from provideDebugConfigurations and provideDetectedDebugConfigurations

I'm a bit unclear from more recent posts whether provideDetectedDebugConfigurations will be called only once per VS Code session, or as-needed based on user activity. I'd like to use this method to return entries based on the workspace's current code/files, which would allow users to iterate on code between debugging sessions, and have access to provideDetectedDebugConfigurations results that reflect the iteration's changes.

[connor4312]

• I agree that calling the provideDynamicDebugConfigurations lazily is preferable. js-debug will be fast but other providers might not be.

  Could we show the categories in the dropdown like we do in the quickpick, and just open a quickpick if one of those are chosen? I.e. have the items in the dropdown be identical to those that we would show in the quickpick.

  Going further, I wonder whether we could make place where the dropdown is now a "button" that opens the quickpick rather than a <select> menu; personally I find quickpicks infinitely more usable than the OS' select menu and would be happy with such a change.

• Regarding the proposal for an enum in registerDebugConfigurationProvider. I think that can be a good direction, but imo if we go that route we should split DebugConfigurationProvider into a DebugConfigurationResolver as well and have a corresponding registerDebugConfigurationResolver to avoid the 'ignored methods' problem. Something like:

export interface DebugConfigurationResolver {
  resolveDebugConfiguration(...);
  resolveDebugConfigurationWithSubstitutedVariables(...);
}

export interface DebugConfigurationProviderSimple {
  provideDebugConfigurations(...)
}

export interface DebugConfigurationProvider extends DebugConfigurationResolver, DebugConfigurationProviderSimple {}

export enum DebugConfigurationScope { /* ... */ }

// existing method:
export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider);

// new overload--registering in scopes does not include any resolve methods in its interface:
export function registerDebugConfigurationProvider(debugType: string, scope: DebugConfigurationScope, provider: DebugConfigurationProviderSimple);
export function registerDebugConfigurationResolver(debugType: string, provider: DebugConfigurationResolver);

[weinand]

@connor4312 yep, in my prototype I started exactly the same approach by splitting the DebugConfigurationProvider. And I ended in the same problem of finding a good name for the DebugConfigurationProviderSimple...

[isidorn]

@connor4312 yes we can show the categories in the debug dropdown. That makes sense.

Problem with drop down going to quick pick always: users eyes have to jump to the right. Though I do think this makes sense, especially when there are a lot of configurations. However I do not think this is related to this discussion, so please create a new issue and we can discuss there. Thanks!

[weinand]

After experimenting with @connor4312's suggestion to split the DebugConfigurationProvider into a DebugConfigurationProviderSimple and a DebugConfigurationResolver, I've come to the conclusion that the benefit is not worth the effort: with the split the important (new) abstraction gets the ugly name DebugConfigurationProviderSimple whereas the obsolete abstraction keeps the nice name DebugConfigurationProvider.

So the final proposal continues to use the existing DebugConfigurationProvider but allows to register it for different scopes:

/**
 * VS Code can call the `provideDebugConfigurations` method of a `DebugConfigurationProvider` in two situations (aka 'scopes'):
 * to provide the initial debug configurations for a newly created launch.json or to provide debug configurations dynamically based on context.
 * A scope can be used when registering a `DebugConfigurationProvider` with #debug.registerDebugConfigurationProvider.
 */
export enum DebugConfigurationProviderScope {
    /**
     * The 'initial' scope is used to ask for debug configurations to be copied into a newly created launch.json.
     */
    Initial = 1,
    /**
     * The 'dynamic' scope is used to ask for additional dynamic debug configurations to be presented to the user (in addition to the static configurations from the launch.json).
     */
    Dynamic = 2
}

export namespace debug {
    /**
     * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type.
     * The optional [scope](#DebugConfigurationProviderScope) argument can be used to bind the `provideDebugConfigurations` method of the provider to a specific context (aka scope).
     * Currently two scopes are possible: with the value `Initial` (or if no scope argument is given) the `provideDebugConfigurations` method is used to find the initial debug configurations to be copied into a newly created launch.json.
     * With a scope value `Dynamic` the `provideDebugConfigurations` method is used to dynamically determine debug configurations to be presented to the user in addition to the static configurations from the launch.json.
     * Please note that the scope argument only applies to the `provideDebugConfigurations` method: so the `resolveDebugConfiguration` methods are not affected at all.
     * Registering a single provider with resolve methods for different scopes, results in the same resolve methods called multiple times.
     * More than one provider can be registered for the same type.
     *
     * @param type The debug type for which the provider is registered.
     * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register.
     * @param scope The [scope](#DebugConfigurationProviderScope) for which the 'provideDebugConfiguration' method of the provider is registered.
     * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
     */
    export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, scope?: DebugConfigurationProviderScope): Disposable;
}

In addition we've added a corresponding activation event onDebugDynamicConfigurations.

Here is an example usage from mock-debug.

[awschristou]

@weinand this is looking great.

Registering a single provider with resolve methods for different scopes, results in the same resolve methods called multiple times.

What do you do if you would like the single provider's provideDebugConfigurations method to be used with both scopes? It seems like we'd want to avoid the resolve method being called more than once in this case.

The motivation would be that the same debug configurations identified dynamically could be just as relevant/valid for seeding a launch.json file.

[weinand]

Since all methods of a DebugConfigurationProvider are optional you can create one provider with one provideDebugConfiguration method and register it for both scopes. And another provider with the resolve methods registered without scopes.

[weinand]

@isidorn a good first step for the UI would be a "contributed" section in the "debug: Select and Start Debugging" Quickpick:

The contributed section would show entries for all debug extensions that have a DebugConfigurationProvider registered for the "Dynamic" scope, similar to the tasks quickpick:

Selecting one would retrieve the contributed launch configs by running the provider.

[weinand]

We might want to consider to add a "description" attribute to the DebugConfiguration type (most likely in the - yet to be added - "presentation" section). The description could be shown in the QuickPick.

[isidorn]

A description makes sense.

[isidorn]

Pushed an initial version of this for the "Select and Start Debug" action. Gif attached.
Note the following:

• As agreed we show each dynamic configuration provider once user chooses it we fetch the configurations for that provider (for multi root workspace we call provide for every root)
• We pass the cancelation token, so if the user cancles a long running quick pick the cancelation should be passed to the debug adapter
• group names: first is "launch.json", second is "contributed". That was more clear to me than "configured" and "contributed" as tasks does

I will now look into adding this into the debug dropdown.
Try it out and let me know what you think.

[weinand]

@isidorn I've pushed a small change to mock-debug to return two more launch configs to make your UI a bit more interesting ;-)

[isidorn]

I have pushed support to also show dynamic providers in the debug dropdown.
For now I decded to use the "LABEL..." as the label. The ... at the end to make it distinguishable and that the user is aware that an additional dialog will follow. Also there is a separator.
Note that I do not use a separator between the launch configurations and a

Try it out and let me know how it behaves for you.
Since we have done what we planned for this item I am closing this.
For pinning launch configurations and other ideas we have discussed here please open follow up feature requests.
I plan to make a test plan item for this issue

[jrieken]

Let's keep this open until the API is finalised

[weinand]

@isidorn I've created new issues #95835 and #95836 for the VS Code implementation work.

[isidorn]

@weinand thanks.

[weinand]

@connor4312 you might want to try the new feature with js-debug (may be as part of testing this; see #95837).

[weinand]

In the API meeting it was suggested to rename the enum DebugConfigurationProviderScope to DebugConfigurationProviderTrigger (because "scope" is a rather unusual term in the VS Code extension API).

With this the final proposal becomes:

/**
 * A DebugConfigurationProviderTrigger specifies when the `provideDebugConfigurations` method of a `DebugConfigurationProvider` is triggered.
 * Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or
 * to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
 * A trigger is used when registering a `DebugConfigurationProvider` with #debug.registerDebugConfigurationProvider.
 */
export enum DebugConfigurationProviderTrigger {
    /**
     *  `DebugConfigurationProvider.provideDebugConfigurations` is called to provide the initial debug configurations for a newly created launch.json.
     */
    Initial = 1,
    /**
     * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
     */
    Dynamic = 2
}

export namespace debug {
    /**
     * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type.
     * The optional [trigger](#DebugConfigurationProviderTrigger) can be used to specify when the `provideDebugConfigurations` method of the provider is triggered.
     * Currently two triggers are possible: with the value `Initial` (or if no trigger argument is given) the `provideDebugConfigurations` method is used to provide the initial debug configurations to be copied into a newly created launch.json.
     * With the trigger `Dynamic` the `provideDebugConfigurations` method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json).
     * Please note that the `trigger` argument only applies to the `provideDebugConfigurations` method: so the `resolveDebugConfiguration` methods are not affected at all.
     * Registering a single provider with resolve methods for different triggers, results in the same resolve methods called multiple times.
     * More than one provider can be registered for the same type.
     *
     * @param type The debug type for which the provider is registered.
     * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register.
     * @param trigger The [trigger](#DebugConfigurationProviderTrigger) for which the 'provideDebugConfiguration' method of the provider is registered.
     * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
     */
    export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, trigger?: DebugConfigurationProviderTrigger): Disposable;
}

@jrieken @connor4312 @isidorn I've optimistically released the change (hoping that it will be accepted in the API meeting)

[jrieken]

fyi - we haven't yet used Trigger by itself but as TriggerKind, e.g SignatureHelpTriggerKind and CompletionTriggerKind

[weinand]

@jrieken thanks, renamed DebugConfigurationProviderTrigger to DebugConfigurationProviderTriggerKind

@connor4312 @isidorn FYI

[weinand]

The test of this API is covered by test item #95837

[jrieken]

Re-open to keep this item around for API finalization

[weinand]

The API submitted for finalisation is this:

/**
 * A DebugConfigurationProviderTriggerKind specifies when the `provideDebugConfigurations` method of a `DebugConfigurationProvider` is triggered.
 * Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or
 * to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
 * A trigger kind is used when registering a `DebugConfigurationProvider` with #debug.registerDebugConfigurationProvider.
 */
export enum DebugConfigurationProviderTriggerKind {
  /**
   * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide the initial debug configurations for a newly created launch.json.
   */
  Initial = 1,
  /**
   * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
   */
  Dynamic = 2
}

export namespace debug {
  /**
   * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type.
   * The optional [triggerKind](#DebugConfigurationProviderTriggerKind) can be used to specify when the `provideDebugConfigurations` method of the provider is triggered.
   * Currently two trigger kinds are possible: with the value `Initial` (or if no trigger kind argument is given) the `provideDebugConfigurations` method is used to provide the initial debug configurations to be copied into a newly created launch.json.
   * With the trigger kind `Dynamic` the `provideDebugConfigurations` method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json).
   * Please note that the `triggerKind` argument only applies to the `provideDebugConfigurations` method: so the `resolveDebugConfiguration` methods are not affected at all.
   * Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times.
   * More than one provider can be registered for the same type.
   *
   * @param type The debug type for which the provider is registered.
   * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register.
   * @param triggerKind The [trigger](#DebugConfigurationProviderTrigger) for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed.
   * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
   */
  export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable;
}

[awschristou]

~@weinand would it be reasonable to indicate in the comments what the behavior is when triggerKind is not provided to registerDebugConfigurationProvider?~

What I meant to ask was if the default behavior could be added to the @param triggerKind line too

[weinand]

Moved the proposed API to vscode.d.ts.