Debug Adapter Protocol

Dart includes support for debugging using the Debug Adapter Protocol as an alternative to using the VM Service directly, simplying 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? evaluateGettersInDebugViews - whether to evaluate getters in expression evaluation requests (inc. hovers/watch windows)
  • 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

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
  • List<String>? toolArgs - arguments for the Dart VM
  • String? console - if set to "terminal" or "externalTerminal" will be run using the runInTerminal reverse-request; otherwise the debug adapter spawns the Dart process
  • bool? enableAsserts - whether to enable asserts (if not supplied, defaults to enabled)

Arguments specific to attachRequest are:

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

* Exactly one of vmServiceInfoFile or vmServiceInfoFile should be supplied.

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": {
		// ...
	}
}

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",
			// ...
		}
	}
}