NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Runtime Debugger (cordbg.exe)

cordbg is a command-line utility that can help tools vendors and application developers find and fix bugs in programs that target the NGWS runtime. This utility uses the Runtime Debugging Services API . Currently, cordbg can only be used for debugging managed code — there is no support for debugging unmanaged code.

For more information about the runtime's debugging services, see the following specifications:

Using cordbg

To use cordbg, you start a debugging session and then use commands (with appropriate arguments) to invoke the required functionality. This section explains how you start debugging and then lists each command along with its arguments.

Note that several commands have "synonyms," which means that you can use any one of several commands to produce a particular result. For example, either the break or the stop command can be used to set breakpoints.

Starting a Debugging Session

The application to be debugged must be compiled using compiler-specific flags to cause debugging symbols to be generated. For more information about these flags, see the compiler documentation.

After the application is compiled, you can start a debugging session in the following way:

D:\Factorial>cordbg
Microsoft (R) NGWS Runtime Test Debugger Shell.  Version 1999.14.1703.0
Copyright (c) Microsoft Corp. 1998-1999
(cordbg)

The (cordbg) prompt indicates that you are in the Debugger.

cordbg Commands

In the command line syntax shown below, brackets enclose optional characters in the command name and indicate optional arguments. Note that cordbg commands are case-sensitive.

The cordbg commands are as follows:

ap[pdomainenum] [<option>]
Enumerates all application domains, assemblies, and modules in the current process.

The option argument can be one of the following:

0 Lists the application domains and prompts the user

1 Lists only the application domains

2 Lists the application domains and assemblies

If the option argument is omitted, the command lists all the application domains, assemblies, and modules in the current process.

as[sociatesource] [s | [b <breakpoint number>] <file name>
Associates the given file name with the specified breakpoint (option b) or the current stack frame pointer (option s).
a[ttach] <pid>
Attaches the debugger to an existing process. The program currently being debugged (if there is one) is killed, and an attempt is made to attach to the process specified by the pid argument. The process identification number pid can be in decimal or hexadecimal. If no argument is specified, enables unmanaged debugging on the current process.

To attach to a NGWS application, set the environment variable CORDBG_ENABLE = 1 before launching the application. This will allow cordbg to attach to the process.

b[reak] [ [<file>:]<line number> [if <expression>] [thread <tid>] ] | [ [<class>::]<function>[:offset]]
Sets or displays breakpoints. If no arguments are passed, a list of current breakpoints is displayed; otherwise, a breakpoint is set at the specified location. A breakpoint can be set at a line number in the current source file, a line number in a fully qualified source file, or in a method qualified by a class and optional offset. You can use the stop command the same way you use break.

Breakpoints will be displayed as “unbound” if the breakpoint location you specified cannot be bound to code. When a breakpoint is unbound, it means that the underlying code for the breakpoint location has not been loaded yet. This can happen for a number of valid reasons, such as misspelling the file or class name (they are case-sensitive). Also, breakpoints will be unbound if they are set before running an application. Breakpoints become bound when the real code is loaded. The debugger tries to automatically rebind every unbound breakpoint when each module is loaded.

ca[tch] [<event>]
Displays a list of event types or causes the specified event type to stop the debugger. If no argument is passed, a list of event types is displayed, where event types that stop the debugger are marked "On," and event types that are ignored are marked "Off." If an event argument is provided, the debugger will stop when events of the specified type occur. By default, the debugger only stops on unhandled exception events (i.e., second chance exceptions). Stop events persist across runs in a session. To cause the debugger to ignore a particular type of event, use the ignore command.

The event argument can be one of the following:

e[xception] All exceptions
u[nhandled] Unhandled exceptions
c[lass] Class load events
m[odule] Module load events
t[hread] Thread start events
c[lear]
Clears a managed exception on the current thread.
c[ont] [<count>]
Continues the program. If no argument is passed, the program is continued once. If a count argument is provided, the program is continued the specified number of times. This command is useful for continuing a program when the class load event stops the debugger. You can use the go command the same way you use cont.
del[ete] [<breakpoint number>,…]
Deletes breakpoints. If no arguments are passed, all current breakpoints are deleted. If one or more breakpoint number arguments is provided, the specified breakpoint(s) are deleted. Breakpoint identifiers can be obtained using the break or stop command. You can use the remove command the same way you use delete.
de[tach]
Detachs cordbg from the currently running process.
dis[assemble] [<line count>]
Displays a disassembly of instructions around the current executable instruction. If no argument is passed, the five (5) instructions before and after the current instruction are displayed. If a line count argument is provided, the specified number of extra instructions will be shown before and after the current one. The last line count used becomes the default for the current session.
d[own] [<frame count>]
Moves the stack frame pointer down the stack toward frames called by the current frame. If no argument is passed, the stack frame pointer moves down one. If a frame count argument is provided, the stack frame pointer moves down by the specified number of frames. If source level information is available, the source line for the frame is displayed. This command is used after the up command has been used.
du[mp] <address> [<count>]
Dump a block of memory with the output in hexadecimal or decimal depending on which mode (see mode) the debugger is in. The address argument is the address of the block of memory. The count argument is the number of bytes to dump. If either argument begins with the prefix 0x, the argument is assumed to be in hexadecimal format. Otherwise, the argument is assumed to be in decimal format.
ex[it]
Stops the current program and quits the debugger. You can use the quit command in the same way you use exit.
f[unceval] [<classname>::] <function name> [<arg0> <arg1>…]
Evaluates the specified function on the current thread. Arguments should be specified in order, and for non-static methods ‘this’ should be the first argument.
g[o] [<count>]
See cont.
h[elp] [<command>…]
Displays command descriptions. If no arguments are passed, a list of debugger commands is displayed. If one or more command arguments is provided, descriptions are displayed for the specified commands. You can use the ? command the same way you use help.
ig[nore] [<event>]
Displays a list of event types or causes the specified event type to be ignored by the debugger. If no event argument is passed, a list of event types is displayed, where event types that are ignored are marked "Off" and event types that stop the debugger are marked "On." If an event argument is provided, the debugger will ignore 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:

exception All exceptions
unhandled Unhandled exceptions
class Class load events
module Module load events
thread Thread start events
i[n] [<count>]
See step.
k[ill]
Stops the program. The debugger remains active to process further commands.
list <option>
Displays the requested list.

The option argument can be one of the following:

mod Lists the loaded modules in the process
cl Lists the loaded classes in the process
m[ode] [ [<mode name> 0] | [<mode name> 1] ]
Sets and queries modes for other debugger features. To set a value, specify the mode name argument and a 1 for on and 0 for off. If no argument is passed, lists all the current mode settings. Currently, the mode argument can be one of the following:
AppDomainLoads Specifies if application domain and assembly load events are displayed
ClassLoads Specifies if class load events are displayed
EditAndContinue Specifies if Edit and Continue is enabled
HexDisplay Controls whether numbers are shown in hexadecimal or decimal
JitOptimizations Specifies if JIT compilation generates debuggable code
ModuleLoads Specifies if module load events are displayed
ILNatPrint Specifies if frame, thread, instruction offsets should be printed IL relative, native relative, or both
ISAll Specifies if cordbg should step through all interceptors or over prologs while stepping through code
ISClinit Specifies if cordbg should step through or over class initialization while stepping through code
ISExceptF Specifies if cordbg should step through or over exception filters while stepping through code
ISInt Specifies if cordbg should step through or over user interceptors while stepping through code
ISPolicy Specifies if cordbg should step through or over context policies while stepping through code
ISSec Specifies if cordbg should step through or over security interceptors while stepping through code
ShowArgs Specifies if arguments should be shown in stack trace
SeparateConsole Specifies if debuggees get their own console
USAll Specifies if cordbg should step through native assembly unmanaged stop locations, i.e., prolog, epilog, unmapped, and no mapping locations, while stepping through code
USEpi Specifies if cordbg should step through native assembly epilogs or over native assembly epilogs while stepping through code
USPro Specifies if cordbg should step through native assembly prologs or over native assembly prologs while stepping through code
USUnmanaged Specifies if cordbg should step through native assembly unmanaged code while stepping through code
newo[bj] <class name>
Creates a new object of the given class using Function Evaluation.
newobjnc <class name>
Creates a new object of the given class using Function Evaluation, but without running a constructor on the new object.
news[tr] <string>
Creates a new string with the given value using Function Evaluation.
n[ext] [<count>]
Steps the program to the next line(s), stepping over function calls. If no argument is passed, one source line is stepped over. If a count argument is provided, the specified number of lines will be stepped. You can use the so command the same way you use next.
ns[ingle] [<count>]
Steps the program one or more instructions, skipping over function calls. If no argument is passed, the program is stepped one instruction. If a count argument is provided, the program is stepped the specified number of instructions.
o[ut] [<count>]
Steps the program out of the current function. If no argument is passed, a step out is performed once for the current function. If a count argument is provided, then a step out is performed the specified number of times.
pa[th] [<new path>]
Displays the path used to search for source files or sets the path. If no argument is passed, the current source file path is displayed. If a path argument is specified, it becomes the new path used to search for source files. This path is persisted between sessions in the Windows registry.
p[rint] [<variable name>]
Displays one or more local variables along with their values. If no argument is passed, all local variables and their values are displayed. If a variable name argument is provided, the value of only the specified local variable is displayed.

Variables within objects can be specified using dot notation, as follows:

print obj.var1
print obj1.obj2.var1

If a class extends another class, the print command will show both the specified class’s fields and the super 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 foo of m2 will print as follows:

foo = <addr> <m2>
      a = 1
      b = 2
      c = 3
      m2::d = 4
      m2::e = 5
      m2::f = 6

Class static variables can be specified by prefixing the variable name with the class name, as follows:

print MyClass::StaticVar1

Array indices must be simple expressions. Thus, the following array indices are valid for use with the print command:

print arr[1]
print arr[i]
print arr1[arr2[1]]
print md[1][5][foo.a]

However, the following array indices cannot be used with the print command:

print arr[i + 1]
print arr[i + 2]
pro[cessenum]
Enumerates all managed processes and the application domains in each process.
q[uit]
See exit.
ref[reshsource] [<source file>]
Refreshes the source code for a given source file. The source file to be refreshed must be part of the currently executing program. After setting a source file path with the path command, the refreshsource command can be used to bring in missing source code.
regd[efault] [force]
Sets the default managed JIT debugger to cordbg. The command does nothing if another debugger is already registered. Use the force argument to overwrite the registered managed JIT debugger.
reg[isters]
Displays the registers.
rem[ove] [<breakpoint number>,…]
See delete.
resume [ [<tid>] | [~<tid>] ]
Resumes the thread specified by the tid argument when the debugger continues. If the ~ syntax is used, resumes all threads except the specified thread. If no argument is passed, the command has no effect.
r[un] [<executable> [<args>]]
Stops the current program (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the run command. If the executable argument is provided, the specified program is run using the optionally supplied args. If class load, module load, and thread start events are being ignored (as they are by default), then the program will stop on the first executable instruction of the main thread.
setip <line number>
Sets the next statement to be executed to the specified line number.
set <variable specifier> <value>
Sets the value of the specified variable to the specified value. The value can be a literal or another variable. Thus, 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_foo[obj1.m_bar] obj3.m_foo[2]
sh[ow] [<line count>]
Displays source code line(s). If no argument is passed, the five source code lines before and after the current source code line are displayed. If a line count argument is provided, the specified number of lines before and after the current line is displayed. The last line count specified becomes the default for the current session.
si [<count>]
See step.
so [<count>]
See next.
ss[ingle] [<count>]
Steps the program one or more instructions, stepping into function calls. If no argument is passed, only one instruction is stepped into. If a count argument is provided, the specified number of steps is performed.
s[tep] [<count>]
Steps the program, stepping into function calls. If no argument is passed, the program is stepped to the next line. If a count argument is provided, the specified number of lines will be stepped. You can use the si command or the in command the same way you use step.
stop [ [<file>:]<line number>] | [ [<class>::]<function>[:offset]]
See break.
suspend [ [<tid>] | [~<tid>] ]
Suspends the thread specified by the tid argument when the debugger continues. If the ~ syntax is used, suspends all threads except the specified thread. If no argument is passed, the command has no effect.
t[hreads] [<thread id>]
Displays a list of threads or sets the current thread. If no argument is passed, the list of all threads that are still alive and that have run managed code is displayed. If a thread id argument is provided, then the current thread is set to the specified thread.
up [<frame count>]
Moves the stack frame pointer up the stack toward frames that called the current stack frame. If no argument is passed, the stack frame pointer moves up one frame. If a frame count argument is provided, the stack frame pointer moves up the specified number of stack frames. If source level information is available, the source line for the frame is displayed.
w[here] [<frame count>]
Displays a stack trace for the current thread. If no argument is passed, a complete stack trace is displayed. If a frame count argument is provided, the specified number of stack frames is displayed.
wr[itememory] <address> <count> <byte>,…
Writes the specified bytes to the target process. The address argument, formatted as per wcstol, specifies the location to which the bytes should be written. The count argument specifies the number of bytes to be written. The byte arguments, formatted as per wcstol, specifies what is to be written to the process. If the number of bytes in the list is less than the count argument, the byte list will be wrapped and copied again. If the number of bytes in the list is more than the count argument, the extra bytes will be ignored.
wt
The command, starting from the current instruction, steps the application by native instructions printing the call tree as it goes. The number of native instructions executed in each function is printed with the call trace. Tracing stops when the return instruction is reached for the function that the command was originally executed in. At the end of the trace, the total number of instructions executed is printed. The command mimics the wt command found in NTSD, and can be used for basic performance analysis. Only managed code is counted for now.
? [<command>…]
See help.