Special Properties Recognized by the Debug Adapter Host

The Visual Studio Debug Adapter Host accepts additional parameters that control its behavior. In general, these parameters can be specified in either the pkgdef associated with an adapter or the "launch.json" used to invoke the adapter.

Adapter Path

Specifies the path to the debug adapter executable.

Examples

launch.json

{
    "$adapter": "c:\\path\\to\\adapter.exe"
}

pkgdef

"Adapter"="c:\path\to\adapter.exe"

Note: When running on a 64bit version of Windows, for any executables that are in %windir%\system32 folder (e.g. c:\Windows\System32\bash.exe) you will need to specify the native location of the application in %windir%\sysnative (c:\Windows\SysNative\bash.exe) otherwise the VS Debug Adapter Host won't be able to find the exe.

Adapter Arguments

Specifies arguments to be passed to the debug adapter executable when it is launched.

Examples

launch.json

{
    "$adapterArgs": "--arg1 --arg2"
}

pkgdef

"AdapterArgs"="--arg1 --arg2"

Adapter Runtime

Specifies the runtime which should be used to execute the adapter. Currently available runtimes include:

node-x86-6.4.0
node-x86-6.4.0-debug
node-x86-7.4.0
node-x86-7.4.0-debug

Examples

launch.json

{
    "$adapterRuntime": "node-x86-6.4.0"
}

pkgdef

"AdapterRuntime"="node-x86-6.4.0"

Locals Scope Name

Specifies the name of a scope that should be treated as containing "local" variables, if the debug adapter provides multiple scopes. In general, if more than one scope is provided, the Debug Adapter Host will show each scope as an expandable top-level item, with the variables available in that scope nested within. Variables in the "local" scope, however, will be placed at the top-level.

Examples

launch.json

{
    "$localsScopeName": "Locals"
}

pkgdef

"LocalsScopeName"="Locals"

Suppress modules Request on Attach

Specifies that the Debug Adapter Host should not issue a modules request when attaching to a process using the debug adapter. This is useful when using an adapter which automatically sends a set of module events on attach, avoiding a redundant query.

Examples

launch.json

{
    "$suppressModulesRequestOnAttach": true
}

pkgdef

"SuppressModulesRequestOnAttach"=dword:00000001

Language Mappings

Specifies the mapping between file extensions and language information.

Examples

launch.json

{
    "$languageMappings": {
        "C#": {
            "languageId": "3F5162F8-07C6-11D3-9053-00C04FA302A1",
            "extensions": [ "*" ]
        },
        "C++": {
            "languageId": "3a12d0b7-c26c-11d0-b442-00a0244a1dd2",
            "extensions": [ "cpp", "h", "hpp", "cxx", "hxx" ]
        }
    }
}

NOTE: An extension of * indicates the default language mapping, which will be applied if no other mapping matches.

pkgdef

"Language"="C#"
"LanguageId"="3F5162F8-07C6-11D3-9053-00C04FA302A1"

NOTE: When specified via a pkgdef, only a default language mapping can currently be provided.

Exception Category Mappings

Specifies the mapping between a Visual Studio exception category GUID and the "category" portion of a CDP exception ID. A protocol ID of * indicates a default exception category mapping, which will be applied if no category is present in an exception ID received from the debug adapter, or if no mapping is available for a category.

Examples

The following examples show how a debug adapter might map protocol categories "CLR" and "MDA" to the Visual Studio exception categories for "Common Language Runtime Exceptions" and "Managed Debugging Assistants", respectively.

launch.json

{
    "$exceptionCategoryMappings": {
        "CLR": "449EC4CC-30D2-4032-9256-EE18EB41B62B",
        "MDA": "6ECE07A9-0EDE-45C4-8296-818D8FC401D4"
    }
}

pkgdef

[$RootKey$\AD7Metrics\Engine\{engine-guid}\ExceptionCategoryMappings]
"CLR"="449EC4CC-30D2-4032-9256-EE18EB41B62B"
"MDA"="6ECE07A9-0EDE-45C4-8296-818D8FC401D4"

Exception Breakpoint Category

Specifies the GUID of the Visual Studio exception category that contains items that correspond to an adapter's Exception Breakpoint Filters.

Examples

launch.json

{
    "$exceptionBreakpointCategory": "{87DD2261-67DA-4AF6-B65D-212312B737DC}"
}

pkgdef

"ExceptionBreakpointCategory"="{87DD2261-67DA-4AF6-B65D-212312B737DC}"

Exception Breakpoint Mappings

Specifies the mapping between the exceptions in the Exception Breakpoint Category and the Exception Breakpoint Filter IDs exposed by a debug adapter.

Examples

The following examples show how a debug adapter might map Visual Studio exceptions named "All Exceptions" and "Unhandled Exceptions" to Exception Breakpoint Filters with IDs of "all" and "unhandled", respectively.

launch.json

{
    "$exceptionBreakpointMappings": {
        "All Exceptions": "all",
        "Unhandled Exceptions": "unhandled"
    }
}

pkgdef

[$RootKey$\AD7Metrics\Engine\{engine-guid}\ExceptionBreakpointMappings]
"All Exceptions"="all"
"Uncaught Exceptions"="uncaught"

Debug Server

Specifies a TCP port on the local machine that the Debug Adapter Host should use to establish communication with the debug adapter, rather than launching the debug adapter itself and communicating via stdin / stdout. This can be useful for debugging a debug adapter, as it allows the developer to control its lifecycle.

Examples

launch.json

{
    "$debugServer": 4711
}

pkgdef

Not supported.