DebugSession
A DebugSession object represents a single debug session running in tandem with an adapter conforming to the Debug Adapter Protocol. Instances of this class can be used to send custom requests to and receive custom events from the adapter.
The target of a debug session (or the debuggee) can be many things, such as an external process, a web page running within a browser, or a script running on a remote host.
Debug sessions are started by providing a TaskDebugAdapterAction object when resolving an action via the Tasks API.
Debug session objects can be received from the Workspace via the debugSessions property or the onDidStartDebugSession() and onDidEndDebugSession() methods.
The DebugSession class is not subclassable.
Added in Nova 9.
Properties
identifier
The identifier of the debug session. Each session has an identifier that is unique to the workspace. Since multiple sessions may be started for a single debug adapter this value is not the same as the debug adapter’s identifier.
This property is readonly.
name
The user-readable name for the debug session as determined by the task invoked by the user to start the session.
This property is readonly.
type
The type string of the debug adapter coordinating the session. This value is the same as the adapterType argument provided when creating a TaskDebugAdapterAction object.
Methods
onCustomEvent(event, callback, [thisValue])
Adds an event listener that invokes the provided callback when a custom event is received from the adapter. The callback will receive as an argument a DebugSessionCustomEvent object representing the event that was received.
A custom event is any event not explicitly defined by the Debug Adapter Protocol. No assumptions should be made that callbacks registered with this method will receive events explicitly defined by the protocol, even those that Nova may not yet handle natively (as support for them may be added in the future). If new events are defined in a future version of the protocol this callback may be invoked until support for that event is adopted by Nova itself.
The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.
This method returns a [Disposable][disposable] that can be used to unregister the listener.
sendRequest(command, arguments)
Sends a request to the debug adapter. This request may be a custom request not defined by the Debug Adapter Protocol.
The command argument should be a string representing the request to invoke.
The arguments object can be any JSON-codable value that the adapter expects as the arguments to the request.
This method returns a Promise object which will resolve or reject when the request is handled by the adapter. It may also be rejected if the debug session ends before a response is received. The resolved value will be the JSON value provided in the response object from the adapter.
startChildSession(action)
Starts a child session running within the scope of the receiver. Child sessions are coordinated as sub-tasks of a parent session to allow grouping multiple debugged targets together (such as a subprocess started by a debuggee).
The action argument should be a TaskDebugAdapterAction defining how the IDE should connect to the child session. Most often, if a subprocess is started by the debuggee and forwarded by the adapter the child session will be started with an attach configuration to connect Nova to this new session already running.
This method will return a Promise object which will resolve or reject when the child session either starts or fails to start, respectively.
There is (as of early 2022) no mechanism within the Debug Adapter Protocol itself for forwarding notification of child sessions to the IDE. Adapters that utilize this behavior typically define a custom event that is sent when a child session in the IDE is requested. The extension can then use the onCustomEvent() method to listen for such events and start child sessions using this method.