| Debugging Tools for Windows |
The debugger engine API provides methods to execute commands and evaluate expressions, like those typed into WinDbg's Debugger Command Window. To execute a debugger command, use Execute. Or, to execute all of the commands in a file, use ExecuteCommandFile.
The method Evaluate will evaluate expressions using the C++ or MASM syntax. The syntax used by the debugger engine to evaluate expressions—such as in the Evaluate method—is given by GetExpressionSyntax and can be changed using SetExpressionSyntaxByName and SetExpressionSyntax. The number of different syntaxes that are recognized by the debugger is returned by GetNumberExpressionSyntaxes, and their names are returned by GetExpressionSyntaxNames.
The type of value that is returned by Evaluate is determined by the symbols and constants used in the string that was evaluated. The value is contained in a DEBUG_VALUE structure and can be cast to different types using CoerceValue and CoerceValues.
Aliases are character strings that are automatically replaced with other character strings when used in debugger commands and expressions. For an overview of aliases, see Using Aliases. The debugger engine has several classes of aliases.
The fixed-name aliases are indexed by number and have the names $u0, $u1, …, $u9. The values of these aliases can be set using the SetTextMacro method and can be retrieved using GetTextMacro method.
The automatic aliases and user-named aliases can have any name. The automatic aliases are defined by the debugger engine and the user-named aliases are defined by the user through debugger commands or the debugger engine API. To define or remove a user-named alias, use the SetTextReplacement method. The GetTextReplacement method returns the name and value of an automatic alias or a user-named alias. All the user-named aliases can be removed using the RemoveTextReplacements method. The GetNumberTextReplacements method will return the number of user-name and automatic aliases; this can be used with GetTextReplacement to iterate over all these aliases. The OutputTextReplacements method will print a list of all the user-named aliases, including their names and values.
Note if a user-named alias is given the same name as an automatic alias, the user-named alias will hide the automatic alias so that when retrieving the value of the alias by name, the user-named alias will be used.
The engine has a number of options that control its behavior. These options are listed in DEBUG_ENGOPT_XXX. They are returned by GetEngineOptions and can be set using SetEngineOptions. Individual options can be set using AddEngineOptions and unset using RemoveEngineOptions.
An interrupt is a way to force a break into the debugger or to tell the engine to stop processing the current command, for example, by pressing Ctrl+Break in WinDbg.
To request a break into the debugger, or to interrupt the debugger's current task, use SetInterrupt. To check if there has been an interrupt, use GetInterrupt.
Note When undertaking a long task from a debugger extension, it is recommended that the extension check GetInterrupt regularly and stop processing if an interrupt has been requested.
When requesting a break into the debugger, the engine might time out if it takes too long for the target to carry out the break-in. This can occur if the target is in a non-responsive state or if the break-in request is blocked or delayed by resource contention. The length of time the engine will wait is returned by GetInterruptTimeout and can be set using SetInterruptTimeout.