WDBG API

Architecture Overview

WDBG is a lightweight stack analyser that delivers a debugging experience with no external dependency. Thus it is not based on true debugging API available on arguably all operating systems, but on the AOP injection technique that modifies the script at runtime by embedding inspection routines in the appropriate places of the script.

This is the script that we want to debug:

using System;

class Program
{
    static void Main(string[] args)
    {
        for (int i = 0; i < 3; i++)
        {
            Console.WriteLine($"Hello World! ({i})"); 
        }
    }
}

And this is how this script is modified at runtime by the Debug Info Injector (pseudo-code):

//css_inc C:\ProgramData\chocolatey\lib\cs-script\tools\-wdbg\dbg-runtime.cs
using System;

class Program
{
    static void Main(string[] args)
    { dbg_inspect();
        dbg_inspect();for (int i = 0; i < 3; i++)
        { dbg_inspect();
            dbg_inspect();Console.WriteLine($"Hello World! ({i})");
        dbg_inspect();}
    dbg_inspect();}
}

The dbg_inspect() is defined in dbg-runtime.cs. This routine is nothing else but a conditional wait-loop (pseudo-code):

dbg_inspect()
{
    if (current_line_has_breakpoint)
    {
        REST.send_local_variables_to_debugger_client();
        while (!resume_requested_by_user)
        {
            sleep_one_second();
        }
    }
}

The file dbg-runtime.cs is an implementation of the WDBG Debug Agent component. This component interacts with the Debugger Client via REST interface.

There are two distinct phases of debugging: debug preparation and the debugging session as on the diagram below.

All this is orchestrated by the /-wdbg/-run.cs script. Thus when you execute css -wdbg script.cs the script engine interprets it as css -wdbg/-run.cs script.cs.

--- under construction ---