Today variables used in a debug configuration are substituted after the DebugConfigurationProvider.resolveDebugConfiguration hook has resolved the debug configuration and before passing it to the debug adapter.
This makes it possible to add and modify attributes of the debug configuration by adding more variables to it and still get them substituted in time.
On the other hand this approach makes it difficult to use the resolved variables in the resolveDebugConfiguration hook, e.g. for validation or for implementing functionality that solely exists in the extension (and not in the debug adapter where the substituted values are available). See #85206 for an example.
From an end users perspective this is confusing: in some (debug configuration) attributes variables can be used (because they are processed in the DA after substitution has occurred), in some attributes variables can not be used (because they are processed in the extension where substitution has not yet occurred). Issue #87450 is a good example for the latter problem.
There are basically two approaches to solve this issue:
- provide extension API to resolve the values.
- add a second hook to
DebugConfigurationProvider into which the debug configuration with substituted values is passed.
The first approach sounds simple but is quite complex because variables can be tied to commands which might result in arbitrary user interactions. Or an interactive variable (with UI) is used more than once in a debug configuration. In this case we only want to show the UI once and apply the resulting value in different places. If the extension can use the variable substitution API freely, the UI might pop up multiple times.
To avoid these complications I propose the second (two-phase) approach instead.
API Proposal:
export interface DebugConfigurationProvider {
/**
* This hook is directly called after 'resolveDebugConfiguration' but with all variables substituted.
* It can be used to resolve or verify a [debug configuration](#DebugConfiguration) by filling in missing values or by adding/changing/removing attributes.
* If more than one debug configuration provider is registered for the same type, the 'resolveDebugConfigurationWithSubstitutedVariables' calls are chained
* in arbitrary order and the initial debug configuration is piped through the chain.
* Returning the value 'undefined' prevents the debug session from starting.
* Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.
*
* @param folder The workspace folder from which the configuration originates from or `undefined` for a folderless setup.
* @param debugConfiguration The [debug configuration](#DebugConfiguration) to resolve.
* @param token A cancellation token.
* @return The resolved debug configuration or undefined or null.
*/
resolveDebugConfigurationWithSubstitutedVariables?(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>;
}
Today variables used in a debug configuration are substituted after the
DebugConfigurationProvider.resolveDebugConfigurationhook has resolved the debug configuration and before passing it to the debug adapter.This makes it possible to add and modify attributes of the debug configuration by adding more variables to it and still get them substituted in time.
On the other hand this approach makes it difficult to use the resolved variables in the
resolveDebugConfigurationhook, e.g. for validation or for implementing functionality that solely exists in the extension (and not in the debug adapter where the substituted values are available). See #85206 for an example.From an end users perspective this is confusing: in some (debug configuration) attributes variables can be used (because they are processed in the DA after substitution has occurred), in some attributes variables can not be used (because they are processed in the extension where substitution has not yet occurred). Issue #87450 is a good example for the latter problem.
There are basically two approaches to solve this issue:
DebugConfigurationProviderinto which the debug configuration with substituted values is passed.The first approach sounds simple but is quite complex because variables can be tied to commands which might result in arbitrary user interactions. Or an interactive variable (with UI) is used more than once in a debug configuration. In this case we only want to show the UI once and apply the resulting value in different places. If the extension can use the variable substitution API freely, the UI might pop up multiple times.
To avoid these complications I propose the second (two-phase) approach instead.
API Proposal: