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(ByteStreamServerChannel channel, {bool ipv6 = false, bool enableDds = true, bool enableAuthCodes = true, Logger? logger, Function? onError})

Properties

args ↔ DartCommonLaunchAttachRequestArguments: latefinal
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.
latefinal
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
enableAuthCodes → bool: Whether to enable authentication codes for the VM Service/DDS.
final
enableDds → bool: Whether to enable DDS for launched applications.
final
evaluateToStringInDebugViews → bool: no setter
hashCode → int: The hash code for this object.
no setterinherited
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.
latefinal
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 setterinherited
parseLaunchArgs → TL Function(Map<String, Object?>): Parses arguments for launchRequest into a type of TLaunchArgs.
no setterinherited
projectPaths → List<String>: A list of all possible project paths that should be considered the users own code.
latefinal
resumeIsolatesAfterPauseExit ↔ bool: Whether isolates that pause in the PauseExit state should be automatically resumed after any in-process log events have completed.
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sendLogsToClient → bool: latefinal
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.
shutdownDebugee() → Future<void>: Shuts down/detaches from the debugee and cleans up.
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.
startDds(Uri uri, UriConverter? uriConverter) → Future<DartDevelopmentService>
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.
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