Differences between Visual Studio Code and the Visual Studio Debug Adapter Host

Differences between Visual Studio Code and the Visual Studio Debug Adapter Host

Although the Visual Studio Debug Adapter Host is intended to be broadly compatible with debug adapters written for Visual Studio Code, there are some small differences that may affect some debug adapters.

General differences

• Visual Studio only supports hosting stand-alone debug adapters. Adapters which depend on Visual Studio Code's extension system, editor, or language services to launch or debug a process will not work without modification.
• Visual Studio Code allows freeform text in many fields, such as the reason field on the stopped event. Visual Studio requires that values for enumerated fields match a value of the enumeration. Invalid values will produce a warning in the log, and may result in incorrect behavior.
• In most cases, if the success field on a response is false, Visual Studio will terminate the debug session.
• Any protocol messages received after the response to the disconnect request will be discarded and produce a warning in the log.
• Visual Studio requires all threads to enter and leave break mode at the same time. Stepping, stopping, or continuing a single thread is not supported.
• Visual Studio issues a variables request after any variable is modified or expression is evaluated while in break mode under the assumption that any evaluation could have side effects. Debug adapters should be sure that the response to the variables request always reflects the current state of the program.
• Visual Studio uses 32-bit signed integers to represent number or integer fields defined in the protocol. If a protocol message is received that contains a value for a number or integer field that is too large to fit into a 32-bit signed integer, an error will be displayed and the debugging session will be terminated. We recommend that adapters not directly use ID or handle values received from the underlying operating system to avoid this issue. Instead, adapters should maintain a mapping between a small, opaque value used in protocol messages and the underlying OS object.

Breakpoint Object

• The id field should be set on all breakpoints. Failure to set this field will produce a warning in the log, and may result in incorrect behavior.
• The message field should be set if the verified field is set to false. This message will be shown in the UI. Failure to provide a message for a non-verified breakpoint will produce a warning in the log.
• The line field must be set if the verified field is set to true. Failure to set this field will cause the debug session to terminate.

ColumnDescriptor Object

• The format field is ignored.
• The width field is ignored.
• The label field is ignored.

ExceptionPathSegment Object

• Visual Studio does not set the negate field.

Message Object

• The sendTelemetry field is ignored.
• The showUser field is ignored.
• The url field is ignored.
• The urlLabel field is ignored.

Module Object

• The dateTimeStamp field is ignored.
• The addressRange field is ignored.

Scope Object

• The namedVariables field is ignored.
• The indexedVariables field is ignored.
• The expensive field is ignored.
• The source field is ignored.
• The line field is ignored.
• The column field is ignored.
• The endLine field is ignored.
• The endColumn field is ignored.

Source Object

• The presentationHint field is ignored.
• The origin field is ignored.
• The adapterData field is ignored.

StackFrame Object

• The only supported values for the presentationHint field are normal and label.
• If the moduleId field is specified, it must match the id of a Module object previously provided. An invalid module ID will cause the debug session to terimnate.

Variable Object

• The kind field is ignored.
• The namedVariables field is ignored.
• The indexedVariables field is ignored.
• The evaluateName field must be specified in order to use the "Add to Watch" feature. Failure to set this field will produce a warning in the log.

module Event

• The value of the id field for a module event with a reason of new must be unique. A duplicate module ID will cause the debug session to terminate.
• The value of the id field for a module event with a reason of removed must match an existing module ID. An invalid module ID will cause the debug session to terminate.

output Event

• The variablesReference field is ignored.
• The data field is ignored for events with a category value other than telemetry.

stopped Event

• The description field is ignored. The UI will reflect the value passed in the reason field instead.
• The text field is ignored.
• The allThreadsStopped field is ignored. Visual Studio requires that all threads enter and leave break mode at the same time.
• The threadId field is required. Failure to set this field will cause the debug session to terminate.
• The value of the threadId field must match an existing thread ID. An invalid thread ID will cause the debug session to terminate.

terminated Event

• The restart field is ignored.

thread Event

• The value of the id field for a thread event with a reason of started must be unique. A duplicate thread ID will cause the debug session to terminate.
• The value of the id field for a thread event with a reason of exited must match an existing thread ID. An invalid thread ID will cause the debug session to terminate.

continue Response

• The allThreadsContinued field is ignored. Visual Studio requires that all threads enter and leave break mode at the same time.

exceptionInfo Response

• The exceptionId field must be of the form Category/Id, e.g. CLR/System.ArgumentException. Specifying a value with an invalid format will produce a warning in the log.
• The description field should be specified, as its value is shown in Visual Studio's exception popup. Failure to set this field will produce a warning in the log.

setVariable Response

• The type field is ignored.
• The variablesReference field is ignored.
• The namedVariables field is ignored.
• The indexedVariables field is ignored.

stackTrace Response

• The totalFrames field is ignored.

initialize Request

• The clientID field will always be set to visualstudio.

runInTerminal Request

• The title field is ignored.
• The kind field must be set to external, or the request will fail.