15 First Execution in the Debugger (F5)

VSCode extension development uses an integrated debugging environment started via F5. Two configuration files work together: launch.json defines the debugger parameters, while tasks.json controls build processes. This configuration functionally corresponds to Run Configurations in Eclipse.

15.1 The Extension Development Host

When pressing F5, VSCode starts a new instance — the Extension Development Host. This process:

• Runs as a separate VSCode process titled “[Extension Development Host]”
• Automatically loads the developed extension
• Provides full debugging functionality with breakpoints
• Enables live reload on code changes

The Development Host simulates a productive VSCode installation with the installed extension.

15.2 Debugging Workflow Overview

15.3 Launch Configuration (launch.json)

The .vscode/launch.json file defines debugging scenarios analogous to Eclipse Run Configurations:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Extension",
            "type": "extensionHost",
            "request": "launch",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}"
            ],
            "outFiles": [
                "${workspaceFolder}/out/**/*.js"
            ],
            "preLaunchTask": "${workspaceFolder}/npm: watch"
        }
    ]
}

15.3.1 Configuration Parameters

type: "extensionHost" specifies the VSCode extension debugger

• Other types: "node", "chrome" for different debugging scenarios

request: "launch" starts a new Extension Host instance

• Alternative: "attach" for debugging running processes

args: Command line parameters for the Extension Host

• --extensionDevelopmentPath: directory of the extension
• --disable-extensions: disables other extensions for isolated testing

outFiles: source map paths for TypeScript debugging

• Enables breakpoints in TypeScript source files
• Must match TypeScript outDir

preLaunchTask: build task before debugging start

• Automatically compiles TypeScript code
• References task from tasks.json

15.3.2 Advanced Launch Configurations

{
    "configurations": [
        {
            "name": "Run Extension",
            "type": "extensionHost",
            "request": "launch",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}",
                "--disable-extensions"
            ],
            "outFiles": ["${workspaceFolder}/out/**/*.js"],
            "preLaunchTask": "${workspaceFolder}/npm: watch",
            "sourceMaps": true,
            "smartStep": true,
            "skipFiles": ["<node_internals>/**"]
        },
        {
            "name": "Extension Tests",
            "type": "extensionHost",
            "request": "launch",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}",
                "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
            ],
            "outFiles": ["${workspaceFolder}/out/test/**/*.js"],
            "preLaunchTask": "${workspaceFolder}/npm: watch"
        }
    ]
}

15.4 Task Configuration (tasks.json)

The .vscode/tasks.json file defines build processes executed before or during debugging:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "npm",
            "script": "watch",
            "problemMatcher": "$tsc-watch",
            "isBackground": true,
            "presentation": {
                "reveal": "never"
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "type": "npm", 
            "script": "compile",
            "problemMatcher": "$tsc",
            "group": "build"
        }
    ]
}

15.4.1 Task Parameters

type: task provider

• "npm": executes npm scripts from package.json
• "shell": runs shell commands
• "typescript": direct TypeScript compilation

script: reference to npm script in package.json

{
  "scripts": {
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  }
}

problemMatcher: parser for compiler output

• "$tsc": TypeScript compiler errors
• "$tsc-watch": TypeScript watch mode
• "$eslint-stylish": ESLint output

isBackground: task runs continuously in background

• Required for watch mode
• Task is considered “ready” after first successful build

presentation: terminal display control

• "reveal": "never": terminal stays hidden
• "reveal": "always": terminal always shown
• "clear": true: clears terminal before task start

15.5 Interaction of Launch and Tasks

The debugging workflow works as follows:

1. F5 pressed: VSCode starts the launch configuration
2. preLaunchTask: watch task starts (if not already active)
3. TypeScript compilation: source code transpiled to out/
4. Extension Host start: new VSCode instance with loaded extension
5. Debugging active: breakpoints and live debugging available

15.5.1 Watch Mode for Continuous Development

The watch task enables automatic recompilation on code changes:

{
    "type": "npm",
    "script": "watch", 
    "isBackground": true,
    "problemMatcher": {
        "base": "$tsc-watch",
        "background": {
            "activeOnStart": true,
            "beginsPattern": "^\\s*(?:message TS6032:|\\[?\\d{1,2}:\\d{1,2}:\\d{1,2}(?:\\.\\d+)?\\]?) File change detected\\. Starting incremental compilation\\.\\.\\.",
            "endsPattern": "^\\s*(?:message TS6042:|\\[?\\d{1,2}:\\d{1,2}:\\d{1,2}(?:\\.\\d+)?\\]?) (?:Compilation complete\\.|Found \\d+ errors?\\.) Watching for file changes\\."
        }
    }
}

15.6 Source Maps and TypeScript Debugging

VSCode uses source maps for TypeScript debugging:

15.6.1 tsconfig.json Configuration

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "outDir": "out",
        "sourceMap": true,
        "strict": true
    }
}

sourceMap: generates .js.map files for debugging outDir: target directory for compiled code target: JavaScript version for Extension Host

15.6.2 Breakpoint Behavior

Breakpoints can be set in both TypeScript and JavaScript files:

• TypeScript breakpoints: directly in source code
• JavaScript breakpoints: in generated files (less recommended)
• Conditional breakpoints: with JavaScript expressions

15.7 Debugging Workflow

15.7.1 Typical Development Cycle

1. Write code in src/extension.ts
2. Press F5 to start Extension Host
3. Test extension in Development Host
4. Set breakpoints for debugging
5. Ctrl+R for reload on changes

15.7.2 Live Reload vs. Restart

Ctrl+R (Reload Window):

• Quick refresh on code changes
• Extension is reactivated
• Debugging connection remains

Extension Host Restart:

• Complete restart of the extension process
• Necessary for major config changes
• Command: “Developer: Restart Extension Host”

15.8 Advanced Debugging Configurations

15.8.1 Multi-Root Workspace Debugging

{
    "name": "Run Extension (Multi-root)",
    "type": "extensionHost",
    "request": "launch",
    "args": [
        "--extensionDevelopmentPath=${workspaceFolder}",
        "${workspaceFolder}/test-workspace.code-workspace"
    ]
}

15.8.2 External Extension Tests

{
    "name": "Extension Tests",
    "type": "extensionHost", 
    "request": "launch",
    "args": [
        "--extensionDevelopmentPath=${workspaceFolder}",
        "--extensionTestsPath=${workspaceFolder}/out/test/suite/index",
        "${workspaceFolder}/test-fixtures"
    ],
    "env": {
        "NODE_ENV": "test"
    }
}

15.9 Troubleshooting and Common Debugging Errors

15.9.1 Source Map Issues

Breakpoint is grayed out or not hit:

• Cause: incorrect outFiles paths in launch.json
• Solution: check path references and outDir in tsconfig.json

// Incorrect: relative paths without workspace root
"outFiles": ["out/**/*.js"]

// Correct: absolute paths with workspace variable
"outFiles": ["${workspaceFolder}/out/**/*.js"]

Source maps not available:

• Cause: sourceMap: false in tsconfig.json
• Solution: enable "sourceMap": true

15.9.2 Task Dependencies

{
    "dependsOn": ["compile"],
    "dependsOrder": "sequence"
}

15.9.3 Performance Optimization

Selective Source Maps:

{
    "compilerOptions": {
        "sourceMap": true,
        "inlineSourceMap": false,
        "sourceRoot": "../src"
    }
}

Incremental Compilation:

{
    "compilerOptions": {
        "incremental": true,
        "tsBuildInfoFile": ".tsbuildinfo"
    }
}