Conditional breakpoints in WinDbg and other Windows debuggers

Conditional breakpoints in WinDbg and other Windows debuggers are useful when you need to break in only if a specific condition is satisfied.

A conditional breakpoint is created with the "/w" parameter to the bp (Set Breakpoint) or other breakpoint command. The basic syntax of the command is:

0:000> bp /w "(Condition)" Address

The breakpoint will only cause a break into the debugger when the specified condition is true. The "w" is an abbreviation for "when". The condition expression can be anything that can be used with the dx (Display Debugger Object Model Expression) command. This includes most C++ style expressions including comparisons, arithmetic, pointer operations, and others. For instance, a basic conditional breakpoint that only breaks in when a variable is more than 20 could be written as:

0:000> bp /w "MyVar > 20" `mysource.cpp:143`

Since the condition is evaluated using the debugger object model, you can also take advantage of things like NatVis support. For instance, assuming myVec is a std::vector<int>, you could create a condition such as:

0:000> bp /w "myVec.Count() == 4" `mysource.cpp:143`

This will break in when line 143 of mysource.cpp is executed while the myVec variable has 4 elements.

Beyond natvis, you can also invoke a JavaScript function. If you load a script using the WinDbg script window or the .scriptload (Load Script) command which contains a function called "myFunc", you could set a breakpoint like this:

0:000> bp /w "@$scriptContents.myFunc()" `mysource.cpp:143`

For more information about writing JavaScript functions and extensions in the debugger, see JavaScript Debugger Scripting

While higher level expressions are typically the most useful, it's also possible to evaluate registers using these expressions. For instance, you could create a breakpoint that only triggers when the stack pointer reaches some threshold:

0:000> bp /w "@esp < 0x6ff9f8" `mysource.cpp:143`

Legacy conditional breakpoint syntax

Before the availability of the "/w" parameter to the breakpoint commands, the recommended way to set conditional breakpoints was to use the j (Execute If - Else) command or the .if token, followed by the gc (Go from Conditional Breakpoint) command. While these methods of setting conditional breakpoints are no longer recommended, they do still function and you may see this syntax referenced in other sources.

The basic syntax for a conditional breakpoint using the j command is as follows:

0:000> bp Address "j (Condition) 'OptionalCommands'; 'gc' "

The basic syntax for a conditional breakpoint using the .if token is as follows:

0:000> bp Address ".if (Condition) {OptionalCommands} .else {gc}"