CloudIDEaaS VSCode Debugger

A lightweight Visual Studio Code debugger for browser-based JavaScript, TypeScript, and HTML projects.

CloudIDEaaS VSCode Debugger is designed around convention over configuration: start debugging from VS Code, launch the local web application and Chrome debugging session, set breakpoints, step through code, and inspect runtime values without relying on console.log or constantly switching to browser DevTools.

Features

Launch browser debugging directly from Visual Studio Code.
Starts a local web server for the current workspace.
Launches Chrome with the Chrome DevTools Protocol (CDP) enabled.
Supports source breakpoints.
Supports conditional breakpoints and exception breakpoint configuration.
Step over, step into, and step out.
Continue and pause execution.
View call stacks and scopes.
Inspect local and object variable values.
Evaluate expressions while debugging.
Modify supported variable values.
View loaded JavaScript sources.
Handles breakpoint resolution after the application is loaded.
Editor-title Start Debugging and Stop Debugging buttons.

Getting Started

Read our free online book on https://publications.lavedajones.com/vscode-debugger/index.html

for a complete guide to using and understanding the debugger.

Create a VS Code debug configuration using the cloudideaas-vscode-debugger debugger type and specify the URL for the page you want to debug.

Example .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Chrome Explicit",
            "type": "cloudideaas-vscode-debugger",
            "request": "launch",
            "url": "http://localhost:8000/index.html"
        }
    ]
}

Set a breakpoint in your browser-side code and press F5, or use the Start Debugging button in the editor title area.

The debugger launches Chrome initially without loading the application, establishes the debugging connection, configures your breakpoints, and then navigates to the requested URL. This allows breakpoints in startup code to be active before the application begins executing.

Requirements

The initial Marketplace release is intended for 64-bit Windows.

The extension includes its C# debug adapter and supporting runtime assemblies in the extension package. Chrome must be available on the system for browser debugging.

Debug Configuration

`url`

The application URL to launch and debug.

Example:

"url": "http://localhost:8000/index.html"

`port`

Chrome remote-debugging port. The default is 9222.

Example:

"port": 9222

How It Works

The extension provides the Visual Studio Code integration layer while a C# debug adapter communicates with VS Code using the Debug Adapter Protocol (DAP). The adapter communicates with Chrome using the Chrome DevTools Protocol (CDP).

Visual Studio Code
        |
        | DAP
        v
CloudIDEaaS C# Debug Adapter
        |
        | CDP / WebSocket
        v
      Chrome

This architecture allows VS Code breakpoints, stepping, scopes, variables, expression evaluation, and other debugging operations to be translated into Chrome debugging operations.

Known Limitations

This is an early release and is not intended to duplicate every feature of Microsoft's JavaScript debugger.

Current limitations may include:

Windows x64 only for the initial release.
Advanced source-map and bundled-application scenarios may require additional support.
Multi-target debugging such as workers, multiple tabs, and complex browser target topologies is limited.
Advanced DAP features such as reverse debugging, instruction breakpoints, data breakpoints, and disassembly are not currently provided.

Contributing

If you want to contribute but not include dependent projects, change references to Extension\cloudideaas-vscode-debugger\bin
Also set the following in VSCodeDebugger.csproj to false as such:

<TrimUnusedAssemblies>false</TrimUnusedAssemblies>

You will need to do above steps if you fork. Otherwise if you want to take advantage of the full solution, let us know and we will help.

Building and Publishing the Extension

The extension project includes npm scripts that automate the release workflow. Run these commands from the Extension\cloudideaas-vscode-debugger directory.

The normal release workflow can:

Bump the extension version
        |
        v
Publish the C# debug adapter as Release / x64
        |
        v
Bundle extension.js with esbuild
        |
        v
List the files that VSCE will package
        |
        v
Create the win32-x64 VSIX
        |
        v
Optionally publish the VSIX to the Visual Studio Marketplace

Create a VSIX Without Publishing

For a normal patch release:

npm run release:patch

This bumps the patch version, publishes the C# debug adapter, bundles the extension, displays the VSCE file list, and creates the VSIX without publishing it to the Marketplace.

For minor or major releases:

npm run release:minor
npm run release:major

Create a VSIX Without Rebuilding the C# Adapter

If the C# debug adapter has already been published and the extension's bin directory contains the files you want to package, use the skip-adapter variant:

npm run release:patch:skip-adapter

Minor and major versions are also available:

npm run release:minor:skip-adapter
npm run release:major:skip-adapter

These commands leave the existing adapter files in place and perform the version bump, JavaScript bundle, VSCE file listing, and VSIX packaging.

Package and Publish to the Marketplace

To perform the complete workflow and publish the resulting VSIX to the Visual Studio Marketplace:

npm run publish:patch

For minor or major releases:

npm run publish:minor
npm run publish:major

The publish scripts package the extension first and then publish that generated VSIX.

Publish Without Rebuilding the C# Adapter

If the adapter files are already prepared and tested:

npm run publish:patch:skip-adapter

Minor and major variants are also available:

npm run publish:minor:skip-adapter
npm run publish:major:skip-adapter

Recommended Release Workflow

For a release that you want to test before publishing:

npm run release:patch

Install and test the generated VSIX locally before publishing it.

For a fully automated release when the adapter and extension have already been validated:

npm run publish:patch

Use minor or major in place of patch when appropriate.

Troubleshooting the Debug Adapter

The extension includes a PowerShell troubleshooting script at:

scripts\Test-DebugAdapter.ps1

This script exercises the C# debug adapter directly using the Debug Adapter Protocol (DAP), independently of Visual Studio Code. It can help determine whether a problem is occurring in the packaged debug adapter/runtime or in the Visual Studio Code extension integration.

The simulator performs a basic debugging sequence through launch and shutdown:

initialize
launch
setBreakpoints
setExceptionBreakpoints
configurationDone
disconnect

Finding the Installed Extension Directory

Visual Studio Code normally installs extensions under:

%USERPROFILE%\.vscode\extensions

Open that directory in File Explorer, or from PowerShell run:

explorer "$env:USERPROFILE\.vscode\extensions"

Look for the CloudIDEaaS VSCode Debugger folder. Its name will include the publisher, extension name, version, and may include the target platform, for example:

cloudideaas.cloudideaas-vscode-debugger-0.1.7-win32-x64

You can also locate the extension from Visual Studio Code:

Open the Extensions view.
Find CloudIDEaaS VSCode Debugger under installed extensions.
Open the extension's gear/menu.
Choose Open Extension Folder if that option is available.

Once you have located the installed extension directory, open PowerShell in that directory. You should see folders such as bin, dist, resources, and scripts.

Copying Development Builds to the Installed Extension

When developing or troubleshooting the C# debug adapter, it can be useful to copy the latest Visual Studio build output directly into the bin directory of an installed CloudIDEaaS VSCode Debugger extension. This allows changes to the C# adapter to be tested through the normally installed Visual Studio Code extension without rebuilding, packaging, publishing, and reinstalling the entire VSIX for every change.

The standard Visual Studio Code extension directory is located under the current Windows user's profile:

%USERPROFILE%\.vscode\extensions

In MSBuild, the equivalent user-independent path can be referenced using:

$(UserProfile)

Because Visual Studio Code includes the extension version in the installed directory name, define the version as an MSBuild property rather than embedding it throughout the project:

<PropertyGroup>
    <InstalledVSCodeExtensionVersion>0.1.33</InstalledVSCodeExtensionVersion>
</PropertyGroup>

The following target copies the current project build output into the installed extension after a successful build:

<Target Name="CopyToInstalledVSCodeExtension" AfterTargets="Build">
    <PropertyGroup>
        <InstalledVSCodeExtensionBin>$(UserProfile)\.vscode\extensions\cloudideaas.cloudideaas-vscode-debugger-$(InstalledVSCodeExtensionVersion)-win32-x64\bin</InstalledVSCodeExtensionBin>
    </PropertyGroup>

    <MakeDir Directories="$(InstalledVSCodeExtensionBin)" />

    <ItemGroup>
        <InstalledExtensionFiles Include="$(TargetDir)*.*" />
    </ItemGroup>

    <Copy
        SourceFiles="@(InstalledExtensionFiles)"
        DestinationFolder="$(InstalledVSCodeExtensionBin)"
        SkipUnchangedFiles="true"
    />
</Target>

For example, with:

<InstalledVSCodeExtensionVersion>0.1.33</InstalledVSCodeExtensionVersion>

the destination resolves to a path similar to:

C:\Users\<user>\.vscode\extensions\cloudideaas.cloudideaas-vscode-debugger-0.1.33-win32-x64\bin

When a new Marketplace version of the extension is installed, update InstalledVSCodeExtensionVersion to match the installed version.

This technique intentionally copies only the current build output over the existing extension bin directory. It does not delete the destination directory first. This is important when the installed extension contains self-contained .NET runtime files or other packaged dependencies that are not present in a normal Visual Studio build output.

This target is intended as a development and troubleshooting convenience. Production extension packages should continue to be created through the normal publish and VSIX packaging workflow.

Running the Troubleshooting Script

From the installed extension directory, run:

.\scripts\Test-DebugAdapter.ps1 `
    -DebuggerPath ".\bin\VSCodeDebugger.exe" `
    -Url "http://localhost:8000/index.html" `
    -WebRoot "C:\Path\To\Your\Project"

To test a specific breakpoint, also provide the source file and line number:

.\scripts\Test-DebugAdapter.ps1 `
    -DebuggerPath ".\bin\VSCodeDebugger.exe" `
    -Url "http://localhost:8000/index.html" `
    -WebRoot "C:\Path\To\Your\Project" `
    -BreakpointFile "C:\Path\To\Your\Project\index.html" `
    -BreakpointLine 25

If -BreakpointFile is omitted, the script uses index.html under the specified WebRoot.

Interpreting the Results

If the script successfully completes the DAP launch sequence and disconnects normally, the packaged C# debug adapter and its supporting runtime are able to start and respond to the basic DAP requests. A problem that occurs only when debugging through Visual Studio Code is therefore more likely to involve extension integration, launch configuration, Chrome startup, or the specific debugging scenario.

If the script fails before completing the launch sequence, include its console output when reporting the issue. This can help identify missing runtime files, adapter startup failures, DAP request failures, or other packaging/runtime problems.

Reporting Issues

When reporting a debugger problem, please include:

Visual Studio Code version.
Windows version.
Chrome version.
Relevant launch.json configuration.
Whether the issue occurs during launch, breakpoint setup, stepping, variable inspection, or shutdown.
Any relevant extension/debug-adapter log output.
Output from scripts\Test-DebugAdapter.ps1, if the troubleshooting script also reproduces the problem.

Release Notes

See CHANGELOG.md for release history.

License

See the repository's LICENSE file for licensing information.

CloudIDEaaS JavaScript Debugger

CloudIDEaaS