VS 2005

Breakpoints and Tracepoints in Visual Studio

When debugging program code it is important to be able to pause the code at a specific location. Using Visual Studio breakpoints and tracepoints, the code can be halted at a desired line or can output trace information when conditions are met.

What are Breakpoints?

A breakpoint is a special marker in your code that is active when executing the program whilst using the Visual Studio debugger. When the marker is reached it causes the program to pause, changing the execution mode to break mode. You can then step through the code line-by-line using the Visual Studio debugging tools, whilst monitoring the contents of local and watched variables.

NB: Breakpoints are only active when using the Visual Studio debugger. When executing a program that has been compiled in release mode, or when the debugger is not active, breakpoints are unavailable.

Setting and Clearing Breakpoints

Breakpoints can be added to functional areas of a program or class library. A functional area is generally a line of code that will be executed when a program runs. Visual Studio will prevent the creation of breakpoints on non-functional lines, such as comments, blank lines or class declarations.

To demonstrate the use of breakpoints we will use a simple console application that calculates and displays multiplication tables. Create a new console application and add the following code to the Main method:

for (int i = 1; i <= 12; i++)
{
    Console.WriteLine("Multiplication table {0}.\n", i);
    for (int j = 1; j <= 12; j++)
    {
        Console.WriteLine("{0} x {1} = {2}", j, i, i * j);
    }
    Console.WriteLine("\n");
}

Setting a Breakpoint

There are several ways in which to set breakpoints. The first manner that we will explore is with the use of the Visual Studio menus. Using this method, a breakpoint is added by positioning the cursor on the desired line before selecting "Toggle Breakpoint" from the Debug menu. You can also press the F9 key for the same result.

To test this, position the cursor in the first line of code containing a Console.WriteLine statement. Press F9 to set the breakpoint. The line should change colour and you will see a circular icon appear in the grey margin area to the left of the code. This icon is called a breakpoint glyph. The filled circle glyph indicates an active, normal breakpoint.

The code can now be executed by pressing F5. When the breakpoint location is hit, the program enters break mode, allowing you to step through the code using the debugging tools. If after breaking you continue execution using the menu option, toolbar button or by pressing F5, you will see that the code pauses each time the breakpoint is hit.

A second way to add a breakpoint is to click within the grey margin where breakpoint glyphs are displayed. Click the position to the left of the line on which a breakpoint is to be set to add it. If a glyph does not appear, adjust the position of the point, ensuring that it lies to the left of a functional area of code.

Removing a Breakpoint

If you no longer require a breakpoint, it can be removed using the same actions used to create it. You can select the marked line of code and choose the "Toggle Breakpoint" command or press F9. Alternatively, simply click the breakpoint glyph. When you successfully remove a breakpoint the glyph disappears.

When debugging large programs it is common to set many breakpoints, possibly in several different files. Once the debugging operation is complete, you can remove all of the breakpoints in a project by selecting the "Delete All Breakpoints" option from the Debug menu.

Disabling Breakpoints

Sometimes you will want to prevent a breakpoint from halting execution without deleting it completely. You can disable all of the breakpoints in the project by selecting the "Disable All Breakpoints" command from the Debug menu. To disable a single breakpoint, right-click its glyph and choose "Disable Breakpoint" from the context-sensitive menu that appears. A disabled breakpoint's glyph is shown without shading, as in the image below:

File Breakpoint Dialog

In addition to the simple breakpoints that can be created using the above methods, Visual Studio allows fine control over the break action using a series of advanced settings. The first set of these is accessed using the File Breakpoint dialog box. To view these settings, right-click an active breakpoint and choose "Location..." from the context-sensitive menu.

The File Breakpoint dialog box provides more control over the position of a breakpoint using three settings. Firstly, the filename of the code file in which to place the breakpoint can be specified. The line number and character position can also be provided. This allows a breakpoint to skip the first statement if you have placed more than one command on a single line.

Usually when debugging in break mode, the source code file must perfectly match the file that was used when the program was compiled. Sometimes you will have made minor modifications to the code but will still want the breakpoint to be used. In these situations you can place a tick in the checkbox to "Allow the source code to be different from the original version".

Conditional Breakpoints

A conditional breakpoint only halts execution when a condition is met. The condition can be specified using the Breakpoint Condition dialog box. This dialog box is displayed when you right-click a breakpoint and select "Condition..."

To enable a condition, the Condition checkbox must be ticked. A condition expression may then be entered into the textbox. Two types of condition are permitted. An "Is true" condition specifies that the expression in the textbox must be met in order for execution to be paused. If, when the code reaches the breakpoint, the condition does not evaluate as "true", the code will continue as normal.

A second type of condition is the "Has changed" expression. In this case, when the breakpoint is hit, the value of the expression in the textbox is compared with the value of the expression on the previous occasion that the breakpoint was encountered. Only if the value has changed is execution paused.

To demonstrate conditional breakpoints, change the condition of the previously set breakpoint to "i==10" and use the "Is true" option. On returning to the code, the breakpoint glyph will have changed to indicate that a condition is present. When you run the program you will see that the code enters break mode only once, just before outputting the multiplication table for the number ten.

NB: Be careful when using an equality test to use two equals signs (==), not one (=). As the expression in the breakpoint is executed, using the latter will change the value of i for each run, causing an infinite loop.

Setting a Hit Count

All breakpoints maintain a hit count during execution in debug mode. This count starts at zero and is incremented each time the breakpoint is encountered. In some situations, it is useful to prevent the breakpoint from pausing the program every time it is hit. By using the Breakpoint Hit Count dialog box, you can modify the behaviour of the breakpoint according to the current hit count. To show this dialog box, select "Hit Count..." from the breakpoint's context-sensitive menu.

Four options are available:

• break always. The default setting causes the breakpoint to pause the code every time it is hit.
• break when the hit count is equal to. Using this option, you can specify that the breakpoint will activate only once, when the hit count reaches the value you specify in the textbox.
• break when the hit count is a multiple of. If you wish the breakpoint to be activated periodically, you can use this option. In the figure below, the breakpoint is set to halt execution on every fifth hit.
• break when the hit count is greater than or equal to. The final option indicates that the breakpoint will be ignored until the hit count reaches a specified value. Once this number has been reached, the breakpoint will halt execution on every subsequent hit.

NB: If you specify both hit count and condition options, both conditions must be met simultaneously for the breakpoint to be active.

Breakpoint Filters

Filters provide an additional level of control over breakpoints. With a filter applied, you can specify that a breakpoint is only active for a specific machine, process or thread. This is particularly useful if you are executing your program several times simultaneously, each with a different process ID, and you wish to debug only one instance.

The Breakpoint Filter dialog box is accessed by selecting "Filter..." from the breakpoint's context-sensitive menu. The filter is specified in the textbox as a series of equality comparisons, joined using AND and OR operators.

NB: Unlike with conditions, the expression uses a single equals sign (=) for an equality test.

Creating Tracepoints

The final breakpoint modification to be considered in this article is the conversion from breakpoint to tracepoint. A tracepoint is similar to a breakpoint except that it outputs messages or executes macros when the tracepoint is hit. In addition, the halting of execution of a program is optional when using a tracepoint.

To change a breakpoint to a tracepoint, right-click the breakpoint and select "When Hit..." from the menu that appears. The When Breakpoint Is Hit dialog box will appear, as pictured below:

To convert the breakpoint to a tracepoint, you set a message to be printed or a macro to be executed, or both, when the tracepoint is encountered. To output a message, tick the appropriate checkbox and type the message to be printed. The message can include current variable values by surrounding the variable name with braces {}. You can also include keywords to output information about the current function, process or thread. The available keywords are listed in the dialog box.

The example shown above outputs a message to indicate that a new multiplication table has been started and the number that is being multiplied. Each time the tracepoint is encountered, this information is added to the output window in Visual Studio.

The second option in the dialog box is to specify a macro to execute when the tracepoint is hit. You may select a standard macro from the set provided by Visual Studio or you can create and use your own. Creating macros is beyond the scope of this article.

Finally, the "Continue execution" checkbox allows you to specify whether the tracepoint should also act as a breakpoint. If ticked, the message and / or macro are processed and execution continues as normal. If cleared, the tracepoint also switches the code into break mode.

The Breakpoint Window

Visual Studio provides the Breakpoint window to show the details of breakpoints and tracepoints in the current project. You can view the window by clicking the Debug menu and selecting "Windows" followed by "Breakpoints".

The breakpoint window lists all of the current breakpoints and tracepoints, including the location of the marker and any conditions set. Each breakpoint has an associated checkbox, which may be cleared to temporarily disable it. If you right-click a breakpoint, you are given access to the context-sensitive menu that permits access to the advanced settings. You can also use the various tools to delete one or all breakpoints, disable all breakpoints or view the source code at a breakpoint's location.