The Runtime Debugger helps tools vendors and application developers find and fix bugs in programs that target the Shared Source CLI (SSCLI) 2.0. This tool uses the runtime Debug API to provide debugging services. The source code for cordbg is included as a sample application. This debugger is a good example of how to use the debugging services and APIs.
The application file for the Runtime Debugger is named cordbg.exe in SSCLI builds on Microsoft Windows®.
The following options supported by the Microsoft .NET Framework implementation of this tool are not supported by the SSCLI implementation:
The following options are supported by the SSCLI implementation of the Runtime Debugger.
cordbg [ProgramName[Program arguments]][optional arguments ]
(cordbg)
prompt)command[command arguments]
To view the usage text at the console use cordbg -?.
Command | Description |
---|---|
|
|
|
Associates the given file name with the current stack frame pointer (option s) or the specified breakpoint (option b). |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Displays descriptions for the specified commands. If you do not specify any arguments, cordbg displays a list of debugger commands. You can use the ? command the same way you use help. |
|
Displays a list of event types or causes the specified event type to be ignored by the debugger. If you do not specify an event
argument, the tool displays a list of event types, where event types that are
ignored are marked off and event types that stop the debugger are marked
on. If you specify an argument, the tool ignores events of the specified type. To set an event type to stop the debugger, use the catch command.
The event argument can be one of the following event types:
|
|
See step. |
|
Stops the current process. The debugger remains active to process further commands. |
|
Displays a list of loaded modules, classes, or global functions.
The option argument can be one of the following:
|
|
Sets and displays debugger modes for various debugger features. To set a value, specify the mode name and a 1 for on or 0 for off. If you do not specify an argument, the tool displays a list of current mode settings. The modes are persisted in the Windows registry between runs of cordbg. For more information, see the table of debugger mode arguments. |
|
Creates a new object using the current thread without running a constructor on the object. The new object is initialized to zero. The tool stores the new object in the variable $result and can use it for subsequent evaluations. |
|
Creates a new object using the current thread. The tool stores the new object in the variable $result and can use it for subsequent evaluations. |
|
Creates a new string using the current thread. The tool stores the new object in the variable $result and can use it for subsequent evaluations. |
|
Steps the program to the next source line, stepping over function calls. If you do not specify an argument, the tool steps one source line. If you specify an argument, the tool steps the specified number of lines. You can use the so command the same way you use next. |
|
Steps the program one or more instructions, skipping over function calls. If you do not specify an argument, the tool steps one instruction. If you specify a count argument, the tool steps the specified number of instructions. |
|
Steps the program out of the current function. If you do not specify an argument, the tool performs a step out once for the current function. If you specify an argument, the tool performs a step out the specified number of times. |
|
Displays or sets the path used to search for source files and debugging symbols. If you do not specify an argument, the tool displays the current path. If you specify a new path argument, it becomes the new path used to search for source files and debugging symbols. This path persists between sessions in the Windows registry. |
|
Displays one or more local variables together with their values. If you do not specify an argument, the tool displays all local variables and their values. If you specify an argument, the tool displays the value of only the specified local variable. For details, see Using the print command in the Examples section. |
|
Enumerates all managed processes and the application domains in each process. |
|
See exit. |
|
Reloads the source code for a given source file. The source file to be reloaded must be part of the currently executing program. After setting a source file path with the path command, you can use the refreshsource command to bring in missing source code. |
|
Sets the default just-in-time (JIT) debugger to cordbg. The command does nothing if another debugger is already registered. Use the force argument to overwrite the registered JIT debugger. |
|
Displays the contents of the registers for the current thread. |
|
See delete. |
|
Resumes the thread specified by the tid argument when the debugger continues. If you use the ~ syntax, the tool resumes all threads except the specified thread. If you do not specify an argument, the command has no effect. |
|
Terminates the current process (if there is one) and starts a new one. If you do not specify an executable argument, this command runs the program that was previously executed with the run command. If you specify an executable argument, the tool runs the specified program using the optionally supplied args. If cordbg is ignoring class load, module load, and thread start events (as it is by default), the program stops on the first executable instruction of the main thread. |
|
Sets the value of the specified variable to the specified value. The value can be a literal or another variable. For details, see Using the set command in the Examples section. |
|
Sets the next statement to execute to the specified line number. |
|
Displays source code lines. If you do not specify an argument, the tool displays the five source code lines before and after the current source code line. If you specify an argument, the tool displays the specified number of lines before and after the current line. The last count specified becomes the default for the current session. |
|
See step. |
|
See next. |
|
Steps the program one or more instructions, stepping into function calls. If you do not specify an argument, the tool steps into only one instruction. If you specify an argument, the tool performs the specified number of steps. |
|
Steps the program to the next source line, stepping into function calls. If you do not specify an argument, the program steps to the next line. If you specify an argument, the program steps the specified number of lines. You can use the si command or the in command the same way you use step. |
|
See break. |
|
Suspends the thread specified by the tid argument when the debugger continues. If you use the ~ syntax, the tool suspends all threads except the specified thread. If you do not specify an argument, the command has no effect. |
|
Displays a list of threads, or sets the current thread. If you do not specify an argument, the tool displays the list of all threads that are still active and that have run managed code. If you specify an argument, the tool sets the current thread to the specified thread. |
|
Moves the stack frame pointer up the stack toward frames that called the current frame for inspection purposes. If you do not specify an argument, the stack frame pointer moves up one frame. If you specify an argument, the stack frame pointer moves up by the specified number of stack frames. If source-level information is available, the tool displays the source line for the frame. |
|
Displays a stack trace for the current thread. If you do not specify an argument, the tool displays a complete stack trace. If you specify an argument, the tool displays the specified number of stack frames. |
|
Writes the specified bytes to the target process. The address argument specifies the location in which to write the bytes. The count argument specifies the number of bytes to write. The byte arguments specify what to write to the process. If the number of bytes in the list is less than the count argument, the tool wraps the byte list and copies it again. If the number of bytes in the list is more than the count argument, the tool ignores the extra bytes. |
|
Steps the application by native instructions, starting from the current instruction and printing the call tree as it goes. The tool prints the number of native instructions executed in each function with the call trace. Tracing stops when the tool reaches the return instruction for the function in which the command was originally executed. At the end of the trace, the tool prints the total number of instructions executed. This command mimics the Windows NT Symbolic Debugger wt command, and you can use it for basic performance analysis. Currently, the tool only counts managed code. |
|
Displays symbols in the specified module that match the pattern specified by the string_to_look_for argument. You can use the asterisk (*) character in the string_to_look_for argument to indicate to the tool to match anything. The tool ignores any characters after the * character. |
|
See help. |
>filename | Writes all executed commands to the specified filename. If you do not specify filename, the command stops writing commands to the file. |
|
Reads and executes commands from the specified filename. |
Note: The Runtime Debugger commands are case-sensitive. In addition, several commands have synonyms, meaning that you can use any one of several commands to produce the same result. For example, you can use either the break or the stop command to set breakpoints.
You can specify mode arguments using the fewest number of characters necessary to make the mode unique. For example, "mode m 1" is equivalent to "mode moduleloads 1".
Argument | Description |
---|---|
AppDomainLoads | Displays application domain and assembly load events. |
ClassLoads | Displays class load events. |
DumpMemoryInBytes | Displays memory contents as bytes or DWORDS. |
EnhanceDiag | Displays enhanced diagnostic information. |
HexDisplay | Displays numbers in hexadecimal or decimal format. |
ILNatPrint | Displays offsets in common intermediate language (CIL) or native-relative language, or both. |
ISAll | Steps through all interceptors. |
ISClinit | Steps through class initializers. |
ISExceptF | Steps through exception filters. |
ISInt | Steps through user interceptors. |
ISPolicy | Steps through context policies. |
ISSec | Steps through security interceptors. |
JitOptimizations | Specifies whether JIT compilation generates code that is easier to debug. |
LoggingMessages | Displays managed code log messages. |
ModuleLoads | Displays module load events. |
SeparateConsole | Specifies whether the process being debugged gets its own console. |
ShowArgs | Displays method arguments in the stack trace. |
ShowModules | Displays module names in the stack trace. |
ShowStaticsOnPrint | Displays static fields for objects. |
ShowSuperClassOnPrint | Displays contents of base class for objects. |
USAll | Steps through all unmapped stop locations. |
USEpi | Steps through method epilogs. |
USPro | Steps through method prologs. |
You should compile the application to debug using compiler-specific flags, which cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can still debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible, and source lines will be inaccurate.
After you compile the application, type cordbg at the command prompt to start a debugging session, as shown in the following example.
C:\Program Files\Microsoft Visual Studio 8>cordbg
Microsoft (R) Common Language Runtime Test Debugger Shell Version 2.0.50727.42 (RTM.050727-4200)
Copyright (C) Microsoft Corporation. All rights reserved.
(cordbg)
The (cordbg) prompt indicates that you are in the debugger.
Once you are in the debugger, use the commands and appropriate arguments to invoke the required functionality.
When you start a debugging session from the command line, you can also provide the name of the application you want to debug, program arguments, and optional arguments. The Managed Debugger optional arguments are the same commands that you would use while in cordbg but you must prefix them with the exclamation point (!) character. You can use the ! character as a literal in a string by prefixing it with the backslash (\) character. This is necessary when using the x command.
If a numeric argument to a command begins with the prefix 0x, cordbg assumes the argument is in hexadecimal format. Otherwise, it assumes the argument is in decimal format.
Most commands in cordbg can be prefixed with an asterisk (*), which causes the command to execute once for each managed thread in the process. The command is executed in the context of each thread. The most useful command to prefix with an asterisk is the w[here] command. For example, *w will cause the stack trace of every managed thread to be printed.
The following command starts a cordbg session for the application MyApplication.exe
with the program arguments a
and 2
and the following optional commands: set a breakpoint in MyApplication.cs
at line 42; continue the application; display symbols in MyApplication.exe
matching the string 'SomeString'
.
cordbg MyApplication.exe a 2 !b MyApplication.cs:42 !g !x MyApplication.exe\!SomeString
The following command entered from within a cordbg session (at the (cordbg)
prompt) runs the executable MyApplication.exe
with the program arguments a
and 2
.
run MyApplication.exe a 2 b
The following commands demonstrate that you can use dot notation with the print command to specify variables within objects.
print obj.var1 print obj1.obj2.var1
If a class extends another class, the print command shows both the specified class's fields and the base class's fields. For example, if class m1 has fields a, b, and c and class m2 extends m1 and has fields d, e, and f, then an instance myInstance of m2 prints as follows.
myInstance = <addr> <m2> a = 1 b = 2 c = 3 m2::d = 4 m2::e = 5 m2::f = 6
You can specify class static variables by prefixing the variable name with the class name, as follows.
print MyClass::StaticVar1 print System::Boolean::True
Array indexes must be simple expressions. The following array indexes are valid for use with the print command.
print arr[1] print arr[i] print arr1[arr2[1]] print md[1][5][myObject.a]
The following array indexes are not valid for use with the print command, because the array index is not a simple expression.
print arr[i + 1] print arr[i + 2]
When you use the set command, the value being assigned to the specified variable can be a literal or another variable. The following are valid uses of the set command.
set int1 0x2a set float1 3.1415 set char1 'a' set bool1 true set obj1 0x12345678 set obj1 obj2 set obj1.m_length[obj1.m_height] obj3.m_length[2]
Copyright (c) 2006 Microsoft Corporation. All rights reserved.