Class ScriptDebugger

Namespace: Alternet.Scripter.Debugger

Assembly: Alternet.Scripter.Debugger.v9.dll

Enables communication with a debugger.

public class ScriptDebugger : IScriptDebugger, IScriptDebuggerBase, IDisposable, IDebuggerCommandDispatcher

Inheritance: object

ScriptDebugger

Implements: IScriptDebugger

IScriptDebuggerBase

IDisposable

IDebuggerCommandDispatcher

Examples

Here is how to declare a ScriptDebugger and start debugging the script from the C# code:

public partial class Form1 : Form
{
    private void Form1_Load(object sender, EventArgs e)
    {
        var scriptDebugger = new Alternet.Scripter.Debugger.ScriptDebugger();
        scriptDebugger.GeneratedModulesPath = generatedModulesPath;
        scriptDebugger.ScriptRun = scriptRun;
        scriptDebugger.ExecutionStopped += ScriptDebugger_ExecutionStopped;
        scriptDebugger.StartDebugging();
    }

    private void ScriptDebugger_ExecutionStopped(object sender, Alternet.Scripter.Debugger.ExecutionStoppedEventArgs e)
    {
        if (e.StopReason == ExecutionStopReason.Exception)
        {
            System.Windows.Forms.MessageBox.Show(e.Exception.ToString());
        }
    }

}

Here is how to declare a ScriptDebugger and start debugging the script from the Visual Basic code:

Partial Public Class Form1
    Inherits Form

    Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
        Dim scriptDebugger = New Alternet.Scripter.Debugger.ScriptDebugger()
        scriptDebugger.GeneratedModulesPath = generatedModulesPath
        scriptDebugger.ScriptRun = scriptRun
        AddHandler scriptDebugger.ExecutionStopped, AddressOf ScriptDebugger_ExecutionStopped
        scriptDebugger.StartDebugging()
    End Sub

    Private Sub ScriptDebugger_ExecutionStopped(ByVal sender As Object, ByVal e As Alternet.Scripter.Debugger.ExecutionStoppedEventArgs)
        If e.StopReason = ExecutionStopReason.Exception Then
            System.Windows.Forms.MessageBox.Show(e.Exception.ToString())
        End If
    End Sub
End Class

Remarks

ScriptDebugger is a non-visual component that provides all commonly used debugging features for C# and Visual Basic scripts, like step-by-step execution, stopping on breakpoints, examining local variables, expression evaluations, etc.

The most important properties of the ScriptDebugger are:

The ScriptRun property specifies the information required to compile and run the script.

The GeneratedModulesPath property gets or sets the directory where the compiled assemblies are located.

The MyCodeModules property contains a collection of module names that the Script debugger can trace.

The Breakpoints property represents a collection of the breakpoints in the source code.

The IsStarted property indicates whether debugging has been started.

Constructors

ScriptDebugger(): Initializes a new instance of the ScriptDebugger class with default settings.

Properties

Breakpoints: Returns collection of debugger breakpoints.

Capabilities: Gets debugger capabilities.

EventsSyncAction: Gets or sets an action used to synchronize events raising. This is normally a function provided by the application to sync raised debugger events (for example, perform Control.Invoke)

ExpressionEvaluator: Gets IExpressionEvaluator object used to evaluate expressions.

GeneratedModulesPath: Gets directory where assemblies for the scripts being debugged are located.

IsStarted: Indicates whether debugging was started.

MyCodeModules: Gets or sets collection of module names to be debugged.

Options: Gets start debugging options.

ScopeResolutionService: Gets IExpressionEvaluator object used to evaluate expressions.

ScriptRun: Contains all information required to compile and run the script.

SourceFilesSearchPaths: Gets or sets an array of directory paths used to search for the debugged source paths when a source path specified in a symbol file (pdb) was not found on disk.

State: Gets current debugger state.

Methods

ActivateThread(int): Switches debugging to the specified thread.

AddBreakpoint(string, int): Adds a Breakpoint to the list.

AttachToProcessAsync(int, StartDebuggingOptions, CancellationToken): Attaches debugger to the process.

AttachToProcessAsync(int, CancellationToken): Attaches debugger to the process.

Break(): Causes the given process to pause its execution so that its current state can be analyzed.

ClearTemporaryGeneratedModules(): Clears temporary generated modules on disk.

Continue(): Continues given process to the next breakpoint or until process finishes.

Dispose(): Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Dispose(bool)

EnableBreakpoint(string, int, bool): Enables or disables breakpoint at specified position.

EvaluateCurrentExceptionAsync(CancellationToken): Evaluates current expression based on the current stack frame.

EvaluateExpressionAsync(ExpressionEvaluationRequest, CancellationToken): Evaluates an expression based on the current stack frame. If the expression can be parsed but not evaluated, an object is returned but will not contain a valid value.

EvaluateExpressionsAsync(IEnumerable<ExpressionEvaluationRequest>, CancellationToken): Evaluates an expression based on the current stack frame. If the expression can be parsed but not evaluated, an object is returned but will not contain a valid value.

ExecuteCommandInDebuggerThread(Action): Executes action in the UI thread.

ExecuteCommandInDebuggerThreadAndMarshalException(Action): Executes action in the UI thread; in case action throws exception, it's handled in the UI thread as well.

~ScriptDebugger(): Destructs the instance of the ScriptDebugger class.

GetExecutionPositionAsync(CancellationToken): Finds out current ExecutionPosition based on the current stack frame.

GetStackFramesAsync(CancellationToken): Gets list of method calls that are currently on a stack.

GetThreadsAsync(CancellationToken): Gets list of active threads.

GetVariablesInScopeAsync(CancellationToken): Receives all local variables based on the current stack frame.

RaiseActiveThreadChanged(ActiveThreadChangedEventArgs)

RaiseBeforeContinue()

RaiseBeforeStep()

RaiseBeforeStop()

RaiseDebuggerErrorOccured(DebuggerErrorOccuredEventArgs)

RaiseDebuggingStarted(DebuggingStartedEventArgs)

RaiseDebuggingStopped(DebuggingStoppedEventArgs)

RaiseExecutionResumed(ExecutionResumedEventArgs)

RaiseExecutionStopped(ExecutionStoppedEventArgs)

RaiseLogMessageReceived(LogMessageReceivedEventArgs)

RaiseStackFrameSwitched(StackFrameSwitchedEventArgs)

RaiseStateChanged(DebuggerStateChangedEventArgs)

ReinitializeScriptIfNeeded()

RemoveBreakpoint(string, int): Removes a Breakpoint from the list.

RunScript(string[]): Starts executing the script without debugging.

RunScriptAsync(string[]): Starts executing the script without debugging.

SetRunToPositionBreakpoint(RunToPositionBreakpoint): Causes debugger to stop at the specified position.

StartDebugging(): Starts executing the program from the entry point with default settings.

StartDebugging(StartDebuggingOptions): Starts executing the program from the entry point with specified settings.

StepInto(): Executes one statement of code; steps into the next function call, if possible.

StepOut(): Executes one statement of code; steps out of the function currently being executed.

StepOver(): Executes one statement of code; steps over the next function call.

StopDebuggingAsync(CancellationToken): Stops executing the program.

SwitchToStackFrame(StackFrame): Switches debugging to the given stack frame.

TrySetNextStatementAsync(int, CancellationToken): Tries to set the execution point to the specified line of code.

Events

ActiveThreadChanged: Occurs when thread to be debugged changes.

BeforeContinue: Occurs before debugger continues to program execution.

BeforeStep: Occurs before debugger performs a step.

BeforeStop: Occurs before debugger stop debugging.

DebuggerErrorOccured: Occurs when encounters error during debugging session.

DebuggingStarted: Occurs when debugging session is started.

DebuggingStopped: Occurs when debugging session is stopped.

ExecutionResumed: Occurs when debugging is resumed after being paused.

ExecutionStopped: Occurs when debugging is paused.

LogMessageReceived: Occurs when debug message is received.

SourceFileLocationResolve: Occurs when source file location resolution is requested.

StackFrameSwitched: Occurs debugger switches to the stack frame.

StateChanged: Occurs when debugger state is changed.