Debug Adapter Protocol

Dart includes support for debugging using the Debug Adapter Protocol as an alternative to using the VM Service directly, simplifying the integration for new editors.

The debug adapters are started with the dart debug_adapter command and are intended to be consumed by DAP-compliant tools such as Dart-specific extensions for editors, or configured by users whose editors include generic configurable DAP clients.

Two adapters are available:

• dart debug_adapter
• dart debug_adapter --test

The standard adapter will run scripts using dart while the --test adapter will cause scripts to be run using dart test and will emit custom dart.testNotification events (described below).

Because in the DAP protocol the client speaks first, running this command from the terminal will result in no output (nor will the process terminate). This is expected behaviour.

For details on the standard DAP functionality, see the Debug Adapter Protocol Overview and the Debug Adapter Protocol Specification. Custom extensions are detailed below.

Flutter: Flutter apps should be run using the debug adapter in the flutter tool - see this document.

Launch/Attach Arguments

Arguments common to both launchRequest and attachRequest are:

• bool? debugExternalPackageLibraries - whether to enable debugging for packages that are not inside the current workspace
• bool? debugSdkLibraries - whether to enable debugging for SDK libraries
• bool? showGettersInDebugViews - whether to include getters in Variables and Evaluation responses (inc. hovers/watch windows)
• bool? evaluateGettersInDebugViews - whether to eagerly evaluate getters in Variables and Evaluation responses (inc. hovers/watch windows) without needing user action. Implies showGettersInDebugViews=true.
• bool? evaluateToStringInDebugViews - whether to invoke toString() in expression evaluation requests (inc. hovers/watch windows)
• bool? sendLogsToClient - used to proxy all VM Service traffic back to the client in custom dart.log events (has performance implications, intended for troubleshooting)
• int? vmServicePort - the port to bind the VM Service too
• List<String>? additionalProjectPaths - paths of any projects (outside of cwd) that are open in the users workspace
• String? cwd - the working directory for the Dart process to be spawned in
• Map<String, String>? env - environment variables to be passed to any spawned process
• bool? sendCustomProgressEvents - whether to send custom dart.progressStart, dart.progressUpdate, dart.progressEnd progress events in place of standard DAP progressStart, progressUpdate, progressEnd events. When this is set, only standard events will not be sent regardless of the supportsProgressReporting capability.
• bool? allowAnsiColorOutput - whether to allow ansi color codes in Output events

Arguments specific to launchRequest are:

• bool? noDebug - whether to run in debug or noDebug mode (if not supplied, defaults to debug)
• String program - the path of the Dart program to run
• List<String>? args - arguments to be passed to the Dart program (after the program on the command line)
• List<String>? toolArgs - arguments passed after the tool that will run program (after dart for CLI scripts and after dart run test:test for test scripts)
• List<String>? vmAdditionalArgs - arguments passed directly to the Dart VM (after dart for both CLI scripts and test scripts)
• String? console - if set to "terminal" or "externalTerminal" will be run using the runInTerminal reverse-request; otherwise the debug adapter spawns the Dart process
• String? customTool - an optional tool to run instead of dart - the custom tool must be completely compatible with the tool/command it is replacing
• int? customToolReplacesArgs - the number of arguments to delete from the beginning of the argument list when invoking customTool - e.g. setting customTool to dart_test and customToolReplacesArgs to 2 for a test run would invoke dart_test foo_test.dart instead of dart run test:test foo_test.dart (if larger than the number of computed arguments all arguments will be removed, if not supplied will default to 0)

Arguments specific to attachRequest are:

• String? vmServiceInfoFile - the file to read the VM Service info from *
• String? vmServiceUri - the VM Service URI to attach to *

* Exactly one of vmServiceInfoFile or vmServiceUri should be supplied.

Expression Evaluation Format Specifiers

Special suffixes can be added to evaluation expressions (such as a Watch window or Debug Console) that will affect the formatting of variables:

• ,nq - don't add quotes around strings
• ,h - format integers as hex
• ,d - format integers as decimal (base 10)

A format specifier overrides any other formatting (such as the format argument that can be supplied to variablesRequest and evaluateRequest). Format specifiers also carry down the variables tree, so adding ,h to an expression that is a List<int> will cause the values inside the list (once expanded) to be rendered as hex. Multiple format specifiers can be comma-separated (myVariable,nq,h on a class will cause Strings in child fields to be unquoted and ints to be formatted as hex).

Custom Requests

Some custom requests are available for clients to call.

updateDebugOptions

updateDebugOptions allows updating some debug options usually provided at launch/attach while the session is running. Any keys included in the request will overwrite the previously set values. To update only some values, include only those in the parameters.

{
	"debugSdkLibraries": true
	"debugExternalPackageLibraries": false
}

callService

callService allows calling arbitrary services (for example service extensions that have been registered). The service RPC/method should be sent in the method field and params will depend on the service being called.

{
	"method": "myFooService",
	"params": {
		// ...
	}
}

hotReload

hotReload calls the VM's reloadSources service for each active isolate, reloading all modified source files.

{
	"method": "hotReload",
	"params": null
}

Custom Events

The debug adapter may emit several custom events that are useful to clients.

dart.debuggerUris

When running in debug mode, a dart.debuggerUris event will be emitted containing the URI of the VM Service.

{
	"type": "event",
	"event": "dart.debuggerUris",
	"body": {
		"vmServiceUri": "ws://127.0.0.1:123/abdef123="
	}
}

dart.log

When sendLogsToClient in the launch/attach arguments is true, debug logging and all traffic to the VM Service will be proxied back to the client in dart.log events to aid troubleshooting.

{
	"type": "event",
	"event": "dart.log",
	"body": {
		"message": "<log message or json string>"
	}
}

dart.serviceRegistered

Emitted when a VM Service is registered.

{
	"type": "event",
	"event": "dart.serviceRegistered",
	"body": {
		"service": "ServiceName",
		"method": "methodName"
	}
}

dart.serviceUnregistered

Emitted when a VM Service is unregistered.

{
	"type": "event",
	"event": "dart.serviceUnregistered",
	"body": {
		"service": "ServiceName",
		"method": "methodName"
	}
}

dart.serviceExtensionAdded

Emitted when a VM Service Extension is added.

{
	"type": "event",
	"event": "dart.serviceExtensionAdded",
	"body": {
		"extensionRPC": "<extensionRPC to call>",
		"isolateId": "<isolateId>"
	}
}

dart.testNotification

When running the --test debug adapter, package:test JSON messages will be passed back to the client in a dart.testNotification event. For details on this protocol, see the package:test documentation.

{
	"type": "event",
	"event": "dart.testNotification",
	"body": {
		"type": "testStart",
		"test": {
			"id": 1,
			"name": "my test name",
			// ...
		}
	}
}