Entering Debugger Commands in WinDbg

The Debugger Command window is the primary debugging information window in WinDbg. You can enter debugger commands and view the command output in this window.

NoteВ В This window displays «Command» in the title bar. However, this documentation always refers to this window as «the Debugger Command window» to avoid confusing it with the Command Prompt windows that are used to issue Microsoft MS-DOS commands.

Opening the Debugger Command Window

To open the Debugger Command window, choose Command from the View menu. (You can also press ALT+1 or select the Command button () on the toolbar. ALT+SHIFT+1 closes the Debugger Command window.)

The following screen shot shows an example of a Debugger Command window.

Using the Debugger Command Window

The Debugger Command window is split into two panes. You type commands in the smaller pane (the command entry pane) at the bottom of the window and view the output in the larger pane at the top of the window.

In the command entry pane, use the UP ARROW and DOWN ARROW keys to scroll through the command history. When a command appears, you can edit it or press ENTER to run the command.

The Debugger Command window contains a shortcut menu with additional commands. To access this menu, select and hold (or right-click) the title bar of the window or select the icon near the upper-right corner of the window (). The following list describes some of the menu commands:

Add to command output adds a comment to the command output, similar to the Edit | Add to Command Output command.

Clear command output deletes all of the text in the window.

Choose text color and recolor selection. opens a dialog box that enables you to choose the text color in which to display the text that is selected in the Debugger Command window.

Word wrap turns the word wrap status on and off. This command affects the whole window, not only commands that you use after this state is selected. Because many commands and extensions produce formatted displays, it is not recommended that you use word wrap.

Mark current location sets a marker at the current cursor location in the command window. The name of the mark is the contents of the line to the right of the cursor.

Go to mark causes the window to scroll so that the line that contains the chosen mark is positioned at the top of the window.

Always floating causes the window to remain undocked, even if it is dragged to a docking location.

Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see Positioning the Windows.

Debug Output Functions

The DirectShow Base Classes provide several macros for displaying debugging information.

Function	Description
DbgCheckModuleLevel	Checks whether logging is enabled for the given message types and level.
DbgDumpObjectRegister	Displays information about active objects.
DbgInitialise	Initializes the debug library.
DbgLog	Sends a string to the debug output location, if logging is enabled for the specified type and level.
DbgOutString	Sends a string to the debug output location.
DbgSetModuleLevel	Sets the logging level for one or more message types.
DbgTerminate	Cleans up the debug library.
DisplayType	Sends information about a media type to the debug output location.
DumpGraph	Sends information about a filter graph to the debug output location.
GuidNames	Global array that contains strings representing the GUIDs defined in Uuids.h.
NAME	Generates a debug-only string.
NOTE	Sends a string to the debug output location.
REMIND	Generates a reminder at compile time.

Registry Keys

The debug output function in DirectShow use a set of registry keys. The location of these registry keys depends on the version of Windows.

Prior to Windows Vista, the debugging keys are located under the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\Debug

In WindowsВ Vista or later, they are located under the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DirectShow\Debug

For third-party filters, the location depends on which version of the DirectShow Base Classes was used to build the filter. The version included in the Windows SDK for Windows Vista uses the newer path. Previous versions used the older path.

In the remarks that follow, the label is used to indicate these two paths. Substitute the correct path, depending on the version of Windows or the version of the base classes.

Debug Logging

DirectShow defines several message types, shown in the following table.

Value	Description
LOG_ERROR	Error notification.
LOG_LOCKING	Locking and unlocking of critical sections.
LOG_MEMORY	Memory allocation, and object creation and destruction.
LOG_TIMING	Timing and performance measurements.
LOG_TRACE	General call tracing.
CUSTOM1 through CUSTOM5	Available for custom debug messages

Each of the DirectShow debug logging functions specifies a message type and a log level. The debug message is displayed only when the current debugging level for that message type is equal to or greater than the level specified in the logging function. Otherwise, the message is ignored.

For example, the following code outputs the string «This is a debug message» if the LOG_TRACE level is 3 or higher:

Every module can set its own debugging level for each message type. (A module is a DLL or executable that can be loaded using the LoadLibrary function.) A module’s debugging levels appear in the registry under the following key:

HKEY_LOCAL_MACHINE\ \ \

where is the message type minus the initial «LOG_»; for example, LOCKING for LOG_LOCKING messages. When a module is loaded, the debug library finds the module’s logging levels in the registry. If the registry keys do not exist, the debug library creates them.

A module can also set its own levels at run time, using the DbgSetModuleLevel function. To send a message to the debug output, call the DbgLog macro. The following example creates a level 3 message of type LOG_TRACE:

You can also specify global logging levels, with the following registry key:

The debug library uses whichever level is greater, the global level or the module level.

Debug Output Location

The debug output location is determined by another registry key:

HKEY_LOCAL_MACHINE\ \ \LogToFile

If the value of this key is Console , the output goes to the console window. If the value is Deb , Debug , Debugger , or an empty string, the output goes to the debugger window. Otherwise, the output is written to a file specified by the registry key.

Before an executable uses the DirectShow debug library, it must call the DbgInitialise function. Afterward, it must call the DbgTerminate function. DLLs do not need to call these functions, because the DLL entry point (defined in the base class library) calls them automatically.

The Output window while debugging with Visual Studio

February 9th, 2015

The Output window is a veteran in the war against bugs and has been part of Visual Studio since its very first release. It is comprised of a collection of text panes that communicate information to the user:

The Output window can be extended by adding to its collection of text panes programmatically, but out of the box with a typical project most users will see the following:

• Build: Contains messages about builds and their status (e.g. compilation warnings)
• Build Order: Same as “Build”, only the output is logically ordered for readability (vs chronological order)
• Debug: Contains messages from the debugger plus any text the application output during execution.

On this post we will focus on the Debug pane and its capabilities.

The Debug text pane of the Output window

One of the most popular and commonly used text panes of the Output window is Debug. It contains the following type of messages:

• Exception Messages: Notification of first-chance exceptions (e.g. “A first chance exception of type ‘System.ArgumentException’ occurred in MyAssembly.dll”). When Just My Code is enabled you only see these for exceptions that occur in user code.
• Step Filtering Messages: Notifications of when the debugger’s Just My Code settings result in skipping non-user code while stepping (e.g. “Step into: Stepping over non-user code ‘System.Data.DataRow.this[int].get’”).
• Module Load/Unload Messages: Notification of modules (basically, .NET assemblies) being loaded or unloaded from the app domain, including notification if symbols were loaded along with them (e.g. “’ConsoleApp1.vshost.exe’ (CLR v4.0.30319: ConsoleApp1.vshost.exe): Loaded ‘C. \blah.dll’. Symbols loaded.”)
• Process Exit Messages: Notification of processes terminating (e.g. “The program ‘[11152] ConsoleApp1.vshost.exe’ has exited with code 0 (0x0).”)
• Thread Exit Messages: Notification of thread terminating (e.g. “The thread 0x2c8 has exited with code 259 (0x103).”)
• Program Output: Messages that the application is sending programmatically through APIs such as Debug.WriteLine. for managed code, OutputDebugString for native code and Debug.writeln for JavaScript.
• Runtime trace information: Depending on your settings (i.e. Debug > Options and Settings > Output Window > WPF Trace Settings) WPF and XAML will output trace information (e.g. binding errors).

You can filter in or out each category of messages using the Debug pane’s right click context menu. Unfortunately messages that were filtered out in the past will not appear after the filter has been changed, so choose your filter settings wisely by anticipating your needs:

The same filter is also available through Debug > Tools and Settings ****> Output Window:

Tip #1: **If you are seeing these type of messages in your Immediate window instead of your Output window, then you probably have the option “Redirect all Output Window text to the Immediate Window” checked under **Debug > Tools and Settings > General.

Tip #2: **You can always select text and copy & paste from any text pane of the Output window, but one handy feature that is somewhat hard to discover is the ability to save the entire contents to a file. If you set the focus to the Output window and you either use the Visual Studio menu item **File > Save Selected Items **or you use the shortcut **CTRL + S you will be asked to specify the file within which to store the contents.****

How the Output window can help with tough debugging problems

The Output window may look like a primitive debugging tool at first, especially compared to some of the other powerful debugging features of Visual Studio, but it can help you in some tough situations.

Hunting for a swallowed exception that is thrown often

Visual Studio offers you various features and options around exceptions, such as the Exception Assistant and the ability to break on first-chance exceptions. However, there are situations in which these features are a bigger hammer than what you need to pinpoint the root cause of the issue you are investigating.

A common scenario is looking for a swallowed exception that is thrown and caught so often that breaking on first-chance exceptions becomes too tedious. You can work around this by using the Debug pane of the Output window to view the exception messages without breaking for every one of them.

The Output window will contain a first chance exception message for every exception thrown (remember that when JMC is enabled these are limited to exceptions in user code only). That may not be enough, because you will not know which one is the one you are interested in. You can build context around and narrow down to the interesting one by generating program output messages (in .NET using Debug.WriteLine() or Trace.WriteLine()) and by enabling other interesting messages such as Thread Exit. For example:

> A first chance exception of type ‘System.NullReferenceException’ occurred in MyApp.exe
…
> A first chance exception of type ‘System. NullReferenceException’ occurred in MyApp.exe
…
> Starting comparison on a new thread
> Step 1: Calculating new hash
> Step 2: Retrieving historical hash
> Step 3: Comparing hashes
> A first chance exception of type ‘System. NullReferenceException’ occurred in MyApp.exe
> The thread 0x1ee8 has exited with code 259 (0x103).
…
> A first chance exception of type ‘System. NullReferenceException’ occurred in MyApp.exe
…

Looking at the above you can tell there are many first chance exceptions messages of type ‘System.NullReferenceException’, which is why I’d have to dismiss too many dialogs for the false positives if I had chosen to break on first-chance exceptions. However, using my program output messages I can tell that there is an issue with “Step 3: Comparing hashes” which results in an exception and the thread existing early before the comparison has been completed. To play around with this kind of Output, you can download my contrived Visual Studio project that resulted in the Output above (it’s a C# console application).

Debugging data binding and other XAML related issues

If you are building a WPF, Windows Store or Windows Phone application you are probably using data binding in your UI. Although data binding is a powerful and flexible mechanism using which you can build complex data-driven UIs very easily, it is still possible to get it wrong sometimes. The debugging experience when data binding fails is less than ideal. The failure is typically silent, without any exceptions being thrown and you only know because the UI hasn’t rendered as you expected or perhaps the data was not updated correctly in the database.

The Debug pane of the Output window can give you tracing information on binding failures, for example:

System.Windows.Data Error: 35 : BindingExpression path error: ‘Picture’ property not found on ‘object’ ”Car’ (HashCode=49535530)’. BindingExpression:Path=Picture; DataItem=’Car’ (HashCode=49535530); target element is ‘Image’ (Name=”); target property is ‘Source’ (type ‘ImageSource’)

The above is telling me that I’m trying to bind the property “Picture” of the object “Car”, but the property does not exist. Much better than simply not having the image show up.

Specifically for WPF you can additionally get tracing information for other XAML events such as Animation and Routed Events. You can change the level of tracing you get through **Debug > Options and Settings > Output Window **(or by changing the config, or programmatically):

Figuring out why your breakpoint is not getting hit

If the debugger can’t get access to symbols your breakpoint will not be hit:

Figuring out why symbols are not being loaded can be tricky. Symbols are loaded at the same time that the module is being loaded into the process. So it’s possible that the entire module you are setting a breakpoint in is not being loaded. Sometimes symbols simply do not exist because the module is being loaded from a location that doesn’t also contain the symbols.

If you use the Output window and look for the Module Load messages (e.g. “’ConsoleApp1.vshost.exe’ (CLR v4.0.30319: ConsoleApp1.vshost.exe): Loaded ‘C. \blah.dll’. Symbols loaded.”), you will be able to tell:

• Which modules are being loaded or unloaded and in what order
• Whether symbols were successfully loaded along with the module
• What location each module is being loaded from, so you can double check the symbols are in the same path

Note that you can get the same Module load information plus a lot more from the Modules window. However, the Modules window only offers a snapshot in time and not streaming information that can be interleaved with other messages in the Output window and hence help you build context. Also while the Modules window will show you the loaded modules, it will not offer insight about modules that have been unloaded.

To find out more about symbols and how Visual Studio uses them, check out our blog post on Understanding symbol files and Visual Studio’s symbol settings.

How is the Output window a hero to you?

Do you have other uses for the Output window that were not covered in this post? We would love to know how this old, trusty tool is helping you be more efficient or solve issues, so let us know. Have you extended the Output window to get more diagnostic information during your debugging? Now is the time for a shameless plug.

We are always looking for feedback and comments for our features. Please use Send-A-Smile, leave a comment or visit the MSDN Diagnostics forums.