WDBG

CS-Script Web Debugger - Stack Analyser

Background

CS-Script Web Debugger is an experiential effort that was triggered by the requests from users for providing scaffolding for lightweight debugging of scripts hosted in the applications. However, the problem itself is generic by nature and simple debugging would be highly beneficial for both CLI and hosted execution scenarios.

Currently, CS-Script offers full integration with the two most popular IDEs Visual Studio and VSCode. Any other IDE or debugger capable of debugging managed applications can also be used for debugging scripts with only a few simple extra steps. Thus currently available tools fully cover an average developer debugging needs.

Though, when debugging is needed on the system where development tools (e.g. IDE) are not available or the user (not the developer) does not have adequate SW development skills, a simple low-dependency debugging infrastructure would be highly beneficial.

Overview

WDBG is an example of such infrastructure and a ready-to-go debugger with no dependency on any other product. While WDBG implementation is rather of a prototype level, it is fully capable to be used as is or as a starting point for further development of product-specific lightweight debuggers.

WDBG concept is simple. Before the start, the script is analysed and special inspection commands/routines are injected in every debuggable line of the script. Then when the script starts and the inspection command executes, it communicates with the debugger web server (REST interface) and enters a wait loop if the user requested the breakpoint stop. The same rest interface is used to analyse local variables and runtime objects while stopped in the breakpoint. The rest of the dev experience is roughly the same as with any debugger.

The important point of WDBG is that it is not relying on rather undocumented/unexposed largely proprietary debugging API and instead uses an injection technique well known in the AOP domain. Thus the only thing you need to have on your system is CS-Script and any web browser.

While the choice of this approach brings very strong benefits it also exhibits some strong limitations.

Pros

• No deployment dependency. You only need a browser and CS-Script present on the target system.
• Portable. Any OS can use it.
• A very simple architecture. Developers can use injection and dbg-runtime as is but they can easily replace the server and front end with their own implementation.

Cons

• It's not a true debugger. IE when stopped at the breakpoint, none of the process threads is suspended.
• Some advanced debugging features are impossible to implement. IE Visual Studio "edit and continue" feature that allows editing the code being debugged without stopping the debug session.
• User experience may not be as polished as with some leading IDEs. IE due to the absence of public API for discovering mapping of execution scopes and discoverable variables breakpoints placement may potentially lead to "jump over to the next". Thus using curly brackets for scope eliminates this possibility.

The debugging API/communication is very simple and can be understood by analysing the -wdbg folder in the distro. Though API documentation and architecture are described at WDBG API page .

Available Features

• Debugging commands: Start, Step Over, Step Into, Stop
• Toggle breakpoints
• Inspect local variables
• Watch local and static objects based on custom expressions. Currently, only fields and properties are evaluated. Thus expression Environment.TickCount is valid but Environment.TickCount.ToString() is not.
• Serialize inspected object. Similar to the "Immediate Window" in Visual Studio.
• Load/Save a script.
• Capture script console output stream.
• Tunnel user input to the script console input stream.

Current Limitations

These limitations are not conceptual and can be addressed in future releases.

• Only one debugging session at a time.
• Single-file scripts only.

How to use

After installing CS-Script just execute your script with the -wdbg switch:

This will automatically start the browser with the debugger web page loaded:

Now do the usual F10 or place a breakpoint and hit F5.

Roadmap

After that, depending on the user feedback WDBG will either stay as is or will start growing in some features. Though I do not see it ever replacing industry-strength IDEs.

Possible future features

• Intellisense. CS-Script already has a syntax provider (syntaxer), which drives VS, VSCode, ST3 and Notepad++ integration with CS-Script.
• Syntax highlighting
• Support for multi-file scripts. Currently, it supports single-file scripts.
• More polished UI