DartDebugAdapter<TL extends LaunchRequestArguments, TA extends AttachRequestArguments> class abstract

A base DAP Debug Adapter implementation for running and debugging Dart-based applications (including Flutter and Tests).

This class implements all functionality common to Dart, Flutter and Test debug sessions, including things like breakpoints and expression eval.

Sub-classes should handle the launching/attaching of apps and any custom behaviour (such as Flutter's Hot Reload). This is generally done by overriding fooImpl methods that are called during the handling of a fooRequest from the client.

A DebugAdapter instance will be created per application being debugged (in multi-session mode, one DebugAdapter corresponds to one incoming TCP connection, though a client may make multiple of these connections if it wants to debug multiple scripts concurrently, such as with a compound launch configuration in VS Code).

The lifecycle is described in the DAP spec here: https://microsoft.github.io/debug-adapter-protocol/overview#initialization

In summary:

The client will create a connection to the server (which will create an instance of the debug adapter) and send an initializeRequest message, wait for the server to return a response and then an initializedEvent The client will then send breakpoints and exception config (setBreakpointsRequest, setExceptionBreakpoints) and then a configurationDoneRequest. Finally, the client will send a launchRequest or attachRequest to start running/attaching to the script.

The client will continue to send requests during the debug session that may be in response to user actions (for example changing breakpoints or typing an expression into an evaluation console) or to events sent by the server (for example when the server sends a StoppedEvent it may cause the client to then send a stackTraceRequest or scopesRequest to get variables).

Mixed-in types

• FileUtils

Constructors

DartDebugAdapter.new(ByteStreamServerChannel channel, {bool ipv6 = false, @Deprecated('DAP never spawns DDS now, this `enableDds` does nothing') bool enableDds = true, @Deprecated('DAP never spawns DDS now, this `enableAuthCodes` does nothing') bool enableAuthCodes = true, Logger? logger, Function? onError})

Properties

args ↔ DartCommonLaunchAttachRequestArguments

late, final

clientSupportsUri → bool

Whether the current client supports URIs in place of file paths, including file-like URIs that are not the 'file' scheme (such as 'dart-macro+file').

no setter

dartSdkRoot ↔ String

The root of the Dart SDK containing the VM running the debug adapter.

late, final

debuggerInitialized → Future<void>

Completes when the debugger initialization has completed. Used to delay processing isolate events while initialization is still running to avoid race conditions (for example if an isolate unpauses before we have processed its initial paused state).

no setter

evaluateToStringInDebugViews → bool

no setter

hashCode → int

The hash code for this object.

no setter, inherited

initializeArgs → DartInitializeRequestArguments?

The InitializeRequestArguments provided by the client in the initialize request.

no setter

ipv6 → bool

Whether to use IPv6 for DAP/Debugger services.

final

isAttach ↔ bool

Whether the current debug session is an attach request (as opposed to a launch request). Only set during attachRequest so will always be false prior to that.

getter/setter pair

isDetaching ↔ bool

Whether or not the current termination is happening because the user chose to detach from an attached process.

getter/setter pair

isolateManager ↔ IsolateManager

Manages VM Isolates and their events, including fanning out any requests to set breakpoints etc. from the client to all Isolates.

late, final

isTerminating ↔ bool

Whether or not the DAP is terminating.

getter/setter pair

logger → Logger?

A logger for printing diagnostic information.

final

orgDartlangSdkMappings → Map<String, Uri>

Mappings of file paths to 'org-dartlang-sdk:///' URIs used for translating URIs/paths between the DAP client and the VM.

final

parseAttachArgs → TA Function(Map<String, Object?>)

Parses arguments for attachRequest into a type of TAttachArgs.

no setter, inherited

parseLaunchArgs → TL Function(Map<String, Object?>)

Parses arguments for launchRequest into a type of TLaunchArgs.

no setter, inherited

pauseIsolatesOnExitSetByDap ↔ bool

Whether this adapter set the --pause-isolates-on-exit flag, specifying that isolates should pause on exiting.

getter/setter pair

pauseIsolatesOnStartSetByDap ↔ bool

Whether this adapter set the --pause-isolates-on-start flag, specifying that isolates should pause on starting.

getter/setter pair

projectPaths → List<String>

A list of all possible project paths that should be considered the users own code.

late, final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

sendLogsToClient → bool

Whether verbose internal logs (such as VM Service traffic) should be sent to the client in dart.log events.

no setter

supportsRestartRequest → bool

Whether or not this adapter can handle the restartRequest.

no setter

terminateOnVmServiceClose → bool

Whether the VM Service closing should be used as a signal to terminate the debug session.

no setter

vmService ↔ VmService?

The VM service of the app being debugged.

getter/setter pair

Methods

attachImpl() → Future<void>

Overridden by sub-classes to handle when the client sends an attachRequest (a request to attach to a running app).

attachRequest(Request request, TA args, void sendResponse()) → Future<void>

attachRequest is called by the client when it wants us to attach to an existing app. This will only be called once (and only one of this or launchRequest will be called).

buildEvaluateName(String suffix, {required String? parentInstanceRefId}) → String?

Builds an evaluateName given a parent VM InstanceRef ID and a suffix.

combineEvaluateName(String? prefix, String suffix) → String?

Builds an evaluateName given a prefix and a suffix.

configurationDoneRequest(Request request, ConfigurationDoneArguments? args, void sendResponse()) → Future<void>

configurationDone is called by the client when it has finished sending any initial configuration (such as breakpoints and exception pause settings).

connectDebugger(Uri uri) → Future<void>

Connects to the VM Service at uri and initializes debugging.

continueRequest(Request request, ContinueArguments args, void sendResponse(ContinueResponseBody)) → Future<void>

Handles the clients "continue" ("resume") request for the thread in args.threadId.

convertOrgDartlangSdkToPath(Uri uri) → Uri?

Converts a URI in the form org-dartlang-sdk:///sdk/lib/collection/hash_set.dart to a local file-like URI based on the current SDK.

convertPathToOrgDartlangSdk(String input) → String?

Converts a file path inside the current SDK root into a URI in the form org-dartlang-sdk:///sdk/lib/collection/hash_set.dart.

convertUriToOrgDartlangSdk(Uri input) → Uri?

Converts a file URI inside the current SDK root into a URI in the form org-dartlang-sdk:///sdk/lib/collection/hash_set.dart.

customRequest(Request request, RawRequestArguments? args, void sendResponse(Object?)) → Future<void>

customRequest handles any messages that do not match standard messages in the spec.

debuggerConnected(VM vmInfo) → Future<void>

Overridden by sub-classes to perform any additional setup after the VM Service is connected.

disconnectImpl() → Future<void>

Overridden by sub-classes to handle when the client sends a disconnectRequest (a forceful request to shut down).

disconnectRequest(Request request, DisconnectArguments? args, void sendResponse()) → Future<void>

disconnectRequest is called by the client when it wants to forcefully shut us down quickly. This comes after the terminateRequest which is intended to allow a graceful shutdown.

evaluateRequest(Request request, EvaluateArguments args, void sendResponse(EvaluateResponseBody)) → Future<void>

evaluateRequest is called by the client to evaluate a string expression.

extractEvaluationErrorMessage(String rawError) → String

Tries to extract the useful part from an evaluation exception message.

extractUnhandledExceptionMessage(String rawError) → String

Tries to extract the useful part from an unhandled exception message.

fromClientPathOrUri(String filePathOrUriString) → Uri

Converts a String used by the client as a path/URI into a Uri.

getFullString(ThreadInfo thread, InstanceRef? ref) → Future<String?>

Helper to convert to InstanceRef to a complete untruncated unquoted String, handling vm.InstanceKind.kNull which is the type for the unused fields of a log event.

handle<TArg, TResp>(Request request, RequestHandler<TArg, TResp> handler, TArg fromJson(Map<String, Object?>), void responseWriter(Response)) → Future<void>

Calls handler for an incoming request, using fromJson to parse its arguments from the request.

inherited

handleDebugEvent(Event event) → Future<void>

handleDetach() → Future<void>

Handles a detach request, removing breakpoints and unpausing paused isolates.

handleExtensionEvent(Event event) → Future<void>

handleIncomingRequest(Request request, void responseWriter(Response)) → void

Handles an incoming request, calling the appropriate method to handle it.

inherited

handleIsolateEvent(Event event) → Future<void>

handleLoggingEvent(Event event) → Future<void>

Handles a dart:developer log() event, sending output to the client.

handleServiceEvent(Event event) → Future<void>

handleSessionTerminate([String exitSuffix = '']) → void

Sends a TerminatedEvent if one has not already been sent.

handleToolEvent(Event event) → Future<void>

initializeRequest(Request request, DartInitializeRequestArguments args, void sendResponse(Capabilities)) → Future<void>

initializeRequest is the first call from the client during initialization and allows exchanging capabilities and configuration between client and server.

isExternalPackageLibrary(ThreadInfo thread, Uri uri) → Future<bool>

Checks whether this library is from an external package.

isInUserProject(Uri targetUri) → bool

Checks whether uri is inside the users project. This is used to support debugging "Just My Code" (via isExternalPackageLibrary) and also for stack trace highlighting, where non-user code will be faded.

isSdkLibrary(Uri uri) → bool

Checks whether this library is from the SDK.

isSupportedFileScheme(Uri uri) → bool

Returns whether uri is a file-like URI scheme that is supported by the client.

launchAndRespond(void sendResponse()) → Future<void>

Overridden by sub-classes that need to control when the response is sent during the launch process.

launchImpl() → Future<void>

Overridden by sub-classes to handle when the client sends a launchRequest (a request to start running/debugging an app).

launchRequest(Request request, TL args, void sendResponse()) → Future<void>

launchRequest is called by the client when it wants us to start the app to be run/debug. This will only be called once (and only one of this or attachRequest will be called).

libraryIsDebuggable(ThreadInfo thread, Uri uri) → Future<bool>

Checks whether a library URI should be considered debuggable.

nextRequest(Request request, NextArguments args, void sendResponse()) → Future<void>

Handles the clients "next" ("step over") request for the thread in args.threadId.

normalizePath(String filePath) → String

Normalizes filePath to avoid issues with different casing of drive letters on Windows.

inherited

normalizeUri(Uri uri) → Uri

Normalizes a Uri via normalizePath.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

pauseRequest(Request request, PauseArguments args, void sendResponse()) → Future<void>

Handles the clients "pause" request for the thread in args.threadId.

preventBreakingAndResume() → Future<void>

Removes any breakpoints or pause behaviour and resumes any paused isolates.

resolveToolEventUris(IsolateRef? isolate, Map<String, Object?> data, String field) → Future<void>

Resolves any URI stored in data with key field to a local file URI via the VM Service and adds it to data with a 'resolved' prefix.

restartFrameRequest(Request request, RestartFrameArguments args, void sendResponse()) → Future<void>

Handles the clients "restartFrame" request for the frame in args.frameId.

restartRequest(Request request, RestartArguments? args, void sendResponse()) → Future<void>

restart is called by the client when the user invokes a restart (for example with the button on the debug toolbar).

scopesRequest(Request request, ScopesArguments args, void sendResponse(ScopesResponseBody)) → Future<void>

scopesRequest is called by the client to request all of the variables scopes available for a given stack frame.

sendConsoleOutput(String? message) → void

Sends an OutputEvent with a trailing newline to the console.

sendDebuggerUris(Uri uri) → void

sendEvent(EventBody body, {String? eventType}) → void

Sends an event, lookup up the event type based on the runtimeType of body.

inherited

sendEventToChannel(Event event) → void

inherited

sendOutput(String category, String message, {int? variablesReference, bool? parseStackFrames}) → void

Sends an OutputEvent (without a newline, since calls to this method may be using buffered data that is not split cleanly on newlines).

sendPrefixedOutput(String category, String prefix, String message) → void

Sends an OutputEvent for message, prefixed with prefix and with message indented to after the prefix.

sendRequest(RequestArguments arguments) → Future<Object?>

Sends a request to the client, looking up the request type based on the runtimeType of arguments.

inherited

setBreakpointsRequest(Request request, SetBreakpointsArguments args, void sendResponse(SetBreakpointsResponseBody)) → Future<void>

Handles a request from the client to set breakpoints.

setExceptionBreakpointsRequest(Request request, SetExceptionBreakpointsArguments args, void sendResponse(SetExceptionBreakpointsResponseBody)) → Future<void>

Handles a request from the client to set exception pause modes.

shutdown() → Future<void>

Shuts down the debug adapter, including terminating/detaching from the debugee if required.

sourceRequest(Request request, SourceArguments args, void sendResponse(SourceResponseBody)) → Future<void>

sourceRequest is called by the client to request source code for a given source.

stackTraceRequest(Request request, StackTraceArguments args, void sendResponse(StackTraceResponseBody)) → Future<void>

Handles a request from the client for the call stack for args.threadId.

startProgressNotification(String id, String title, {String? message}) → DapProgressReporter

Starts reporting progress to the client for a single operation.

stepInRequest(Request request, StepInArguments args, void sendResponse()) → Future<void>

Handles the clients "step in" request for the thread in args.threadId.

stepOutRequest(Request request, StepOutArguments args, void sendResponse()) → Future<void>

Handles the clients "step out" request for the thread in args.threadId.

storeEvaluateName(InstanceRef instanceRef, String? evaluateName) → void

Stores evaluateName as the expression that can be evaluated to get instanceRef.

terminateImpl() → Future<void>

Overridden by sub-classes to handle when the client sends a terminateRequest (a request for a graceful shut down).

terminateRequest(Request request, TerminateArguments? args, void sendResponse()) → Future<void>

terminateRequest is called by the client when it wants us to gracefully shut down.

threadsRequest(Request request, void args, void sendResponse(ThreadsResponseBody)) → Future<void>

Handles a request from the client for the list of threads.

toClientPathOrUri(Uri? uri) → String?

Converts a URI into a form that can be used by the client.

toString() → String

A string representation of this object.

inherited

uriConverter() → UriConverter?

variablesRequest(Request request, VariablesArguments args, void sendResponse(VariablesResponseBody)) → Future<void>

variablesRequest is called by the client to request child variables for a given variables variablesReference.

vmEvaluate(ThreadInfo thread, String targetId, String expression, {bool? disableBreakpoints = true}) → Future<Response?>

Sends a VM 'evaluate' request for thread.

vmEvaluateInFrame(ThreadInfo thread, int frameIndex, String expression, {bool? disableBreakpoints = true}) → Future<Response?>

Sends a VM 'evaluateInFrame' request for thread.

vmServiceUriToHttp(Uri uri) → Uri

Fixes up a VM Service WebSocket URI to not have a trailing /ws and use the HTTP scheme which is what DDS expects.

vmServiceUriToWebSocket(Uri uri) → Uri

Fixes up a VM Service uri to a WebSocket URI with a trailing /ws for connecting when not using DDS.

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

toolEventStreamId → String

The ID of the custom VM Service stream that emits events intended for tools/IDEs.

final