.NET Framework Command-Line Debugger (MDbg.exe)
The NET Framework Command-Line Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime Debug API to provide debugging services. The source code for MDbg.exe is shipped as a sample application in the Windows Software Development Kit (SDK). Developers can examine the code to learn how to use the debugging services. Currently, you can use MDbg.exe to debug only managed code; there is no support for debugging unmanaged code.
MDbg [ProgramName[Program arguments]] [optional arguments ]
command [command arguments]
Commands
Command |
Description |
|---|---|
ap[rocess] [number] |
Switches to another debugged process or prints available processes. The numbers are not real PIDs, but a 0-indexed list. |
a[ttach] [pid] |
Attaches to a process or prints available processes. |
b[reak] [ClassName.Method | FileName:LineNo] |
Sets a breakpoint at the specified method. Modules are scanned sequentially. break FileName:LineNo sets a breakpoint at a location in the source. break ~number sets a breakpoint on a symbol recently displayed with the x command. break module!ClassName.Method+IlOffset sets a breakpoint on the fully qualified location. |
ca[tch] [exceptionType] |
Causes the debugger to break on all exceptions, not just the unhandled exceptions. |
conf[ig] [option value] |
Displays all configurable options and how the options are invoked without any optional values.. If the option is specified, sets value as the current option. Currently available options are: extpath: Sets the path where extensions are searched for when the load command is used. extpath+: Adds a path to the existing paths where extensions can be loaded from. |
del[ete] |
Deletes a breakpoint. |
de[tach] |
Detaches from a debugged process. |
d[own] [frames] |
Moves the active stack frame down. |
echo |
Echoes a message to the console. |
ex[it] [exitcode] |
Exits the MDbg.exe shell, optionally specifying the process exit code. |
fo[reach] [OtherCommand] |
Performs a command on all threads. OtherCommand is a valid command that operates on one thread; foreach OtherCommand performs the same command on all threads. |
f[unceval] [-ad Num] functionName [args ... ] |
Performs a function evaluation on the current active thread where the function to evaluate is functionName. The function name must be fully qualified, including namespaces. The -ad option specifies the application domain to use to resolve the function. If the -ad option is not specified, the application domain for resolution defaults to the application domain where the thread that is used for function evaluation is located. If the function that is being evaluated is not static, the first parameter passed in should be a this pointer. All application domains are searched for arguments to the function evaluation.. To request a value from an application domain, prefix the variable with the module and application domain name. For example, funceval -ad 0 System.Object.ToString hello.exe#0!MyClass.g_rootRef. This command evaluates the function System.Object.ToString in the application domain 0. Because the ToString method is an instance function, the first parameter must be a this pointer. |
g[o] |
Causes the program to continue until it encounters a breakpoint, the program exits, or an event causes the program to stop (for example, an unhandled exception). |
h[elp] [command] or ? [command] |
Displays a description of all commands or a detailed description of a specified command. |
ig[nore] [event] |
Causes the debugger to stop on unhandled exceptions only. |
int[ercept] FrameNumber |
Rolls the debugger back to a specified frame number. If the debugger encounters an exception, use this command to roll the debugger back to the specified frame number. You can change the program state using the set command and continue using the go command. |
k[ill] |
Stops the active process. |
l[ist] [modules|appdomains|assemblies] |
Displays the loaded modules, application domains, or assemblies. |
lo[ad] assemblyName |
Loads an extension in the following manner: the specified assembly is loaded and an attempt is then made to run the static method LoadExtension from the Microsoft.Tools.Mdbg.Extension.Extension type. |
mo[de] [option on/off] |
Sets different debugger options. The option parameter should be a two-letter pair. |
newo[bj] typeName [arguments...] |
Creates a new object of type typeName. |
n[ext] |
Runs code and moves to the next line (even if the next line includes many function calls). |
o[ut] |
Moves to the end of the current function. |
pa[th] [pathName] |
Searches the specified path for the source files if the location in the binaries is not available. |
p[rint] [var] | [-d] |
Prints all variables in scope (print), prints the specified variable (print var), or prints the debugger variables (print -d). |
pro[cessenum] |
Displays the active processes. |
q[uit] [exitcode] |
Quits the MDbg.exe shell, optionally specifying the process exit code. |
re[sume] [*|[~]threadNumber] |
Resumes the current thread or the thread specified by the threadNumber parameter. If the threadNumber parameter is specified as * or if the thread number starts with ~, the command applies to all threads except the one specified by threadNumber. Resuming a non-suspended thread has no effect. |
r[un] [-d(ebug) | -o(ptimize) | -enc] [[path_to_exe] [args_to_exe]] |
Stops the current process (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 arguments. If class load, module load, and thread start events are ignored (as they are by default), the program stops on the first executable instruction of the main thread. You can force the debugger to just-in-time (JIT) compile the code using any of the three valid flags: -d(ebug) is the default for MDbg.exe and disables optimizations. -o(ptimize) is the default for use outside the debugger. It forces the code to run more like it does outside of the debugger, but also makes the debugging experience more difficult. -enc enables the Edit and Continue feature but incurs a performance hit. |
Set variable=value |
Changes the value of any in-scope variable. You can also create your own debugger variables and assign reference values to them from within your application. These values act as handles to the original value, even the original value is out of scope. All debugger variables must begin with $ (for example, $var). Clear these handles by setting them to nothing using the following command: set $var= |
Setip [-il] number |
Sets the current Instruction Pointer (IP) in the file to the specified position. If the -il option is specified, the number represents an Intermediate Language offset in the method. Otherwise the number represents a source line number. |
sh[ow] [lines] |
Specifies the number of lines to show.. |
s[tep] |
Moves execution into the next function on the current line, or moves to the next line if there is no function to step into. |
su[spend] [*|[~]threadNumber] |
Suspends the current thread or the thread specified by the threadNumber parameter. If threadNumber is specified as *, the command applies to all threads. If the thread number starts with ~, the command applies to all threads except the one specified by threadNumber. Suspended threads are excluded from running when the process is run by either the go or step command. If there are no non-suspended threads in the process and you issue the go command, the process will not continue. In that case, issue the CTRL-C command to break into the process. |
sy[mbol] commandName [commandValue] |
Specifies one of the following commands: symbol path ["value"] - Displays or sets the current symbol path. symbol addpath "value" - Adds to your current symbol path. symbol reload ["module"]- Reloads either all symbols or the symbols for the specified module. symbol list [module] - Shows the currently loaded symbols for either all modules or the specified module. |
t[hread] [newThread][-nick name] |
Assigns name as the nickname to the currently active thread. The nickname can be used instead of the thread name. Nicknames cannot be numbers. If the current thread already has an assigned nickname, the old nickname is replaced with the new one. If the new nickname is "", the nickname for the current thread is deleted and no new nickname is assigned to the thread. thread newThread - Sets the active thread to newThread. newThread can be either a nickname for the thread or a thread number. thread - Displays all managed threads in the current process. Threads are usually identified by their thread number; however, if the thread has an assigned nickname, the nickname is displayed instead. |
u[p] |
Moves the active stack frame up. |
uwgc[handle] [var] | [address] |
Prints the variable tracked by a handle. The handle can be specified by name or address. |
when |
Displays the currently active when statements. when delete all |num[num[num…]] - Deletes the when statement specified by the number, or all when statements if all is specified. when stopReason[specific_condition] do cmd[cmd[cmd…] ] - The stopReason parameter can be: StepComplete,ProcessExited,ThreadCreated,BreakpointHit,ModuleLoaded,ClassLoaded,AssemblyLoaded,AssemblyUnloaded,ControlCTrapped,ExceptionThrown,UnhandledExceptionThrown,AsyncStop,AttachComplete, UserBreak, EvalComplete,EvalException,RemapOpportunityReached,NativeStop. specific_condition can be: number - For ThreadCreated and BreakpointHit, triggers action only when stopped by a thread ID/breakpoint number with same value. [!]name - For ModuleLoaded, ClassLoaded, AssemblyLoaded, AssemblyUnloaded, ExceptionThrown, and UnhandledExceptionThrown, triggers action only when the name matches the name of the stopReason. specific_condition must be empty for other values of stopReason. |
w[here] [-v] [-c depth] [threadID] |
Displays debug information about stack frames. The -v option provides verbose information about each displayed stack frame. Specifying a number for depth limits how many frames are displayed. Use the all command to display all frames. The default is 100. If you specify the threadID parameter, you can control which thread is associated with the stack. The default is the current thread only. Use the all command to get all threads. |
x [-c numSymbols] [module[!pattern]] |
Displays functions matching the pattern for a module. If numSymbols is specified, the output is limited to the specified number. If !regex is not specified, all functions are displayed. If module is not provided, all loaded modules are displayed. Symbols (~#) can be used to set breakpoints using the break command. |
Note
MDbg.exe commands are case-sensitive.
Remarks
Compile the application to be debugged using compiler-specific flags, which causes 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 MDbg at the command prompt to start a debugging session, as shown in the following example:
C:\Program Files\Microsoft Visual Studio 8\VC>mdbg
MDbg (Managed debugger) v2.0.50727.42 (RTM.050727-4200) started.
Copyright (C) Microsoft Corporation. All rights reserved.
For information about commands type "help";
to exit program type "quit".
mdbg>
The mdbg 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.