Breakpoints: Use Hit Counts, Call Stack Functions, and Conditions to Break When and Where You Want in the Visual Studio Debugger

Article
03/22/2013

Set breakpoints for source lines, assembly instructions, and call stack function. Specify conditions, hit counts, and execution location. Print with tracepoints. Save and import breakpoints.

Create breakpoints that break when you want

Set a breakpoint at a source line, assembly instruction, or call stack function

Access the advanced functionality of breakpoints

Specify when a breakpoint breaks by hit count, expression evaluation, execution location, or data change

Print to the Output window with tracepoints

Manage breakpoints in the Breakpoints window

Troubleshoot breakpoints

Breakpoint Glyphs Reference

Create breakpoints that break when you want

Standard breakpoints, which break the debugger execution each time a source file location is hit, are one of most important debugging techniques in a developer's toolbox. Visual Studio helps you go beyond standard breakpoints to create fine-grained control over when and where a breakpoint executes.

You can set run-time breakpoints that halt execution when your program returns to a function on the call stack and avoid a long series of Step Out commands.
If you suspect that a loop in your code starts misbehaving after a certain number of iterations, you can set a breakpoint to stop execution after a specified number of hits to the to the associated line of code, rather than being forced to repeatedly press F5 (Debug, Continue) to reach the iteration level.
By using using code expressions, you can specify the exact conditions at which a breakpoint breaks.

You can use the Breakpoints window to manage the state and behavior of a large number of breakpoints. If you have carefully constructed a sequence of breakpoints to diagnose a common or particularly complex issue, you can save or share those breakpoints by using Breakpoints window import and export commands.

Warning

Avoid setting breakpoints on system components when you are debugging mixed-mode (native and managed) code. Setting a breakpoint on a system component during mixed-mode debugging can cause the common language runtime to break and the debugger to stop responding.

Set a breakpoint at a source line, assembly instruction, or call stack function

Set a breakpoint in a source file • Set a breakpoint at a function return in the Call Stack window • Set a breakpoint at an assembly instruction in the Disassembly window

Set a breakpoint in a source file

Here are two techniques to set a standard breakpoint in a source window:

Double-click in the gutter of the window at the line that you want to break at.

-or-
Select the line and choose F9.

Breakpoint in Call Stack window

The breakpoint icon appears in the gutter.

To visually trace breakpoints during code execution, see Visualize and Debug Code Execution with Call Stacks in Visual Studio.

Set a breakpoint at a function return in the Call Stack window

You can break execution at the instruction or line that a calling function returns to by setting a breakpoint in the Call Stack window. The debugger must be in break mode.

Open the Call Stack window (shortcut key: Ctrl + Alt + C), and select the calling function to break at.
Choose Breakpoint, Insert Breakpoint on the context menu, or just use the shortcut key: F9.

A breakpoint symbol appears in the left margin next to the function call name.

Breakpoint in Call Stack window

If you open the Breakpoints window (shortcut key: Ctrl + Alt + B) the breakpoint appears as an address breakpoint with a memory location that corresponds to the next executable instruction in the function. The debugger breaks execution at the instruction.

Call Stack breakpoint in Breakpoints window

To visually trace breakpoints during code execution, see Visualize and Debug Code Execution with Call Stacks in Visual Studio.

Set a breakpoint at an assembly instruction in the Disassembly window

To set a breakpoint at an assembly instruction, the debugger must be in break mode.

Open the Disassembly window (shortcut key: Ctrl + Alt + D).
Do one of the following:
1. Double-click in the gutter of the window at the line that you want to break at.
  
  -or-
2. Select the line and choose F9.

Access the advanced functionality of breakpoints

In a source window, the Call Stack window, or the Disasssembly window, open the context menu for the breakpoint and choose the property.

In the Breakpoints window, select a breakpoint row and open the context menu. You can also set some conditions directly in the condition column.

Specify when a breakpoint breaks by hit count, expression evaluation, execution location, or data change

Specify a hit count at which the breakpoint executes • Specify a breakpoint condition using a code expression • Specify the devices, processes, or threads that a breakpoint executes on • Set a data change breakpoint (native C++ only)

Specify a hit count at which the breakpoint executes

A hit count keeps track of how many times a breakpoint is hit. You set a value and a condition so that the breakpoint executes when the hit count equals the value, equals a multiple of a specified value, or is greater than or equal to the value. To specify the hit count and condition:

Open the the Hit Count Breakpoint dialog box.
1. In a source, Disassembly, or Call Stack , select a line that contains a breakpoint, and then choose Breakpoints, Hit Count on the context menu.
  
  -or-
2. In the Breakpoints window, select a breakpoint row, and then choose Hit Count on the context menu.
Select the condition and enter the hit count.

Hit count conditions are useful when you want to break into a loop at a certain number of iterations. You can also specify a very large number if you want to count the number of times a breakpoint is hit, but you don’t want to break execution.

The specified hit count is retained only for the debugging session. When the debugging session ends, the hit count is reset to zero.

Specify a breakpoint condition using a code expression

A breakpoint condition is an expression that the debugger evaluates when a breakpoint is reached. If the condition is satisfied, the debugger breaks execution.

The condition can be any valid expression that is recognized by the debugger. In a banking program, for example, you could set a breakpoint condition such as balance < 0. For more information about valid expressions, see Expressions in the Debugger.

To specify a breakpoint condition

Open the context menu for the breakpoint and choose Condition.
In the Breakpoint Condition dialog box, enter a valid expression in the Condition box.
Choose Is true if you want to break when the expression is satisfied, or choose Has changed if you want to break when the value of the expression has changed.

The debugger doesn't evaluate the expression until the first time the breakpoint is reached. If you choose Has changed for native code, the debugger doesn't consider the first evaluation of the condition to be a change, so the breakpoint won't be hit on the first evaluation. If you choose Has changed for managed code, he breakpoint is hit on the first evaluation after Has changed is selected.

If you set a breakpoint condition with invalid syntax, a warning message appears immediately. If you specify a breakpoint condition with valid syntax but invalid semantics, a warning message appears the first time the breakpoint is hit. In either case, the debugger breaks execution when the invalid breakpoint is hit. The breakpoint is skipped only if the condition is valid and evaluates to false.

Specify the devices, processes, or threads that a breakpoint executes on

Open the context menu for a breakpoint and choose Filter.
Specify the filter criteria according to the dialog box directions.

Set a data change breakpoint (native C++ only)

Data breakpoints break execution when a value that is stored at a specified memory location is written. If the value is read but not written, execution doesn't break. To set data breakpoints, the debugger must be in break mode.

On the Debug menu, choose New Breakpoint, New Data Breakpoint.

-or-

In the Breakpoints window menu, choose New, New Data Breakpoint.
In the Address box, type a memory address or expression that evaluates to a memory address.

For example, type &avar to break when the contents of variable avar change.
In the Byte Count box, type the number of bytes you want the debugger to watch.

For example, if you type 4, the debugger will watch the four bytes starting at &myFunction and break if any of those bytes change value.

To set data breakpoints, the debugger must be in break mode.

Data breakpoints don't work under these conditions:

If a process that is not being debugged writes to the memory location
If the memory location is shared between two or more processes.
If the memory location is updated within the kernel. For example, if memory is passed to the 32-bit Windows ReadFile function, the memory will be updated from kernel mode and the debugger doesn't break on the memory write.

Addresses of variables change from one debugging session to the next. For this reason, data breakpoints are automatically disabled at the end of each debugging session.

If you set a data breakpoint on a local variable, the data breakpoint remains enabled when the function ends. However, the memory address it is set on no longer has the same meaning. Therefore, the results of such a breakpoint are unpredictable. If you set a data breakpoint on a local variable, the best practice is to remove or disable the breakpoint before the function ends.

Visual Studio supports a maximum of four data breakpoints per solution.

Print to the Output window with tracepoints

Tracepoints are another way to use breakpoints. A tracepoint is a breakpoint that prints a message to the Output window. A tracepoint can act like a temporary trace statement in the programming language.

To print a message at an existing breakpoint, open the context menu for the breakpoint and choose When Hit.

You specify the message to print in the When Breakpoint Is Hit dialog box.

When Breakpoint Is Hit dialog box

Specify the message

You can include programmatic information in the message by using DebuggerDisplayAttribute syntax (see DebuggerDisplayAttribute). Here are a couple of examples:

In function '{$FUNC}', on thread '{$TID}'
Used variable: {varName}, function name: {functionName($FUNC)}

You can use any of the keywords that are described on the When Breakpoint Is Hit dialog box. In addition, you can use two other keywords that aren't shown in the dialog box: $TICK inserts the current CPU tick count, while $FILEPOS inserts the current file position.

Specify the tracepoint behavior

To break execution when the tracepoint is hit, clear the Continue Execution check box. When Continue Execution is checked, execution is not halted. In both cases, the message is printed.

Disable the tracepoint

To temporarily disable the tracepoint, clear the Print a Message check box.

Manage breakpoints in the Breakpoints window

Export and import breakpoints • Label breakpoints

Almost all the functionality to set, configure, and manage breakpoints of the Breakpoints window is available at the individual breakpoint locations in the source windows, the Call Stack window, and the Disassembly window. But the Breakpoints window does give you a central place to manage all your breakpoints, which can be especially helpful in a large solution or a complex debugging scenario where breakpoints are critical. If you need to save or share the state and location of a set of breakpoints, you can save and import breakpoint files only from the Breakpoints window.

Label breakpoints

Breakpoint labels are used only in the Breakpoints window to sort and filter the list of breakpoints. To add a label to a breakpoint, choose the breakpoint row and then choose Label on the context menu.

Troubleshoot breakpoints

The debugger can't determine the source file for a breakpoint • The debugger can't locate the correct version of the source file for a breakpoint • Breakpoints don't work in a DLL

The debugger can't determine the source file for a breakpoint

If two or more source files in the project have the same name, the debugger might have trouble determining which file the breakpoint is set in. This often occurs if you create a module with the same name as a component of the Debug library you are linking to.

To fix this problem, select the breakpoint in a source window and choose Location on the context menu.

File Breakpoint dialog box

Enter the full path to the correct file in the File box

The debugger can't locate the correct version of the source file for a breakpoint

If a source file has changed and the source no longer matches the code you are debugging, the debugger might locate the source file that corresponds to a breakpoint, even though the source file exists.

If you want Visual Studio to display source code that doesn't match the version you are debugging, choose Debug, Options and Settings. On the Debugging/General page, clear the Only use source code that exactly matches the original version option.
You can also bind the breakpoint to the source file. Select the breakpoint and choose Location on the context menu. Check Allow the source code to be different from the original version in the File Breakpoint dialog box.

Breakpoints don't work in a DLL

You cannot set a breakpoint in a source file when the debugger hasn't loaded the debug information for the module where the code is located. Symptoms may include messages, such as the breakpoint cannot be set. The Warning breakpoint glyph appears at the breakpoint location. However, these Warning breakpoints become actual breakpoints when the code is loaded.

Breakpoint Glyphs Reference

The source windows and the Disassembly window show breakpoint locations by displaying symbols called glyphs in the left margin. The following table describes these glyphs.

If you rest the mouse on a breakpoint glyph, a breakpoint tip appears with more information. This information is especially useful for error and warning breakpoints.

Glyph	Description
	Normal breakpoint. The solid glyph indicates that the breakpoint is enabled. The hollow glyph indicates that it is disabled.
	Advanced breakpoint. Active/disabled. The + sign indicates that the breakpoint has at least one advanced feature (such as condition, hit count, or filter) attached to it.
	Mapped breakpoint. Active/disabled. The breakpoint is set in ASP/ASP.NET code and mapped to a breakpoint in the corresponding HTML page, or set in a server-side script file and mapped to the corresponding client-side script file.
	Tracepoint. Active/disabled. Hitting this point performs a specified action but doesn't break program execution.
	Advanced tracepoint. Active/disabled. The + sign indicates that the tracepoint has at least one advanced feature (such as condition, hit count, or filter) attached to it.
	Mapped tracepoint. Active/disabled. The tracepoint is set in ASP/ASP.NET code and mapped to a tracepoint in the corresponding HTML page.
	Breakpoint or tracepoint error. The X indicates that the breakpoint or tracepoint couldn't be set because of an error condition.
	Breakpoint or tracepoint warning. The exclamation mark indicates that a breakpoint or tracepoint couldn't be set because of a temporary condition. Usually, this means that the code at the breakpoint or tracepoint location hasn't been loaded. It can also be seen if you attach to a process and the symbols for that process aren't loaded. When the code or symbols are loaded, the breakpoint will be enabled and the glyph will change.