Turning Debugger Canvas On and Off

When installed, Debugger Canvas is your default debug experience. However, you can turn it on or off easily.

• On the menus, select Debug:Debugger Canvas

When the item is highlighted Debugger Canvas is the default and will start the next time you start debugging. When not highlighted, the file based debugger is default.

Figure 1. Debugger Canvas turned on.

Figure 2. You can also use the Debugger Canvas toolbar button to turn Debugger Canvas on or off.

Turn Debugger Canvas on while debugging

Even when Debugger Canvas is off by default, it can be turned on in the middle of a debug session.

1. Start debugging in files, then hit a breakpoint.
2. Click on the Debugger Canvas button on the toolbar (or use the Debugger Canvas command on the Debug menu).

Now a canvas will show with a bubble for the current method, and you can continue debugging in the canvas. To see the rest of the call stack on the canvas, use the stack navigation buttons (see Navigating the Call Stack below)

Turn Debugger Canvas off while debugging

You can turn the canvas off while debugging, too. Just click the Debugger Canvas button. This will bring you back to the File tabs again.

You can turn Debugger Canvas on and off as many times as you want in any given debug session.

Turning Debugger Canvas on or off using the Options page

1. Go to Debug: Debugger Canvas: Settings and Options.
2. Uncheck the "Use Debugger Canvas as default debug experience" check box.

Now F5 will open file tabs as normal.    

Changing the option has the same effect as selecting the Debugger Canvas command while not debugging.

Navigating from a Bubble to the Corresponding File

Figure 3. You can navigate from the code in a bubble to the same code in a file by using the Navigate to File function.

Navigating the Call Stack

Often when hitting a breakpoint you may want to inspect the methods that preceded the current one in the call stack. You can do this in the canvas by using the stack navigation buttons:

Figure 4. Use the stack navigation buttons to go to other methods in the call stack

You can navigate up or down the stack. If the method you’re navigating to is not on the canvas, it will be added. You can also jump to the bottom of the stack. This will add all missing bubbles to the canvas.

Navigating the Call Stack with the Menus or Keyboard

The stack navigation commands can also be found on the Debug: Debugger Canvas sub menu, and they have shortcut keys assigned to them. These can be reassigned if they don't fit the profile that you’re currently using.

Turning Reuse of Bubbles On or Off

By default, Debugger Canvas will reuse bubbles when the content is the same. For example if a loop calls the same method multiple times, only one bubble will be shown on the canvas. This keeps the content of the canvas fairly compact. However, there are cases where it is better to see one bubble for each invocation of a method, such as those cases when you have recursive calls or parallel calls to the same method.

To turn off reuse, do the following:

1. Go to Debug: Debugger Canvas: Options and settings
2. Uncheck “Reuse Bubbles When Content is the Same”          

From now on, new bubbles will be created for each invocation of a method. This also means that new debug sessions in the same canvas will create new bubbles rather than reuse ones from previous sessions.

Debugging Recursive Code

To debug recursive code, you should first turn reuse of bubbles off. See Turning Reuse of bubbles on or off. Then all you need to do is start debugging, and your recursive calls will be shown in individual bubbles such as this:

Figure 5. When debugging recursive code, you can see each call in a separate bubble by turning off reuse of bubbles.

Debugging Multi-Threaded Code

Debugger Canvas supports multi-threaded debugging by color coding each thread. In addition, the last active frame of each thread is highlighted with a deeper shade of the thread color.

Figure 6. When debugging multi-threaded code, bubbles from each thread get a distinct color.

Inspecting a frame in a thread is as easy as clicking on it. This will activate the thread and the frame, just as using the Debug Location toolbar and the call stack window would do.

Enabling Editing

By default, editing is turned on in Debugger Canvas. You can turn it on or off here:

1. Go to Debug: Debugger canvas: Options and Settings.
2. Check the Enable editing check box.

Note that editing is not the main focus of this release, and it is not as well tested as the pure debugging features. We recommend using it for small edits within a method. If you're doing major refactoring, stay in file tabs.

Enabling Go to Definition and Find All References Within the Canvas

1. Go to Debug: Debugger canvas: Options and Settings.
2. Turn on the check box.

Now if you use Go to Definition or Find All References within code on the canvas, the code you're navigating to will also be put on the canvas.

Navigating to Code - what works and what doesn't.

Since the focus of this release is on debugging, we support only a handful of code navigation features.

What works:

1. Go to Definition (if turned on in Options).
2. Find all References (if turned on in Options).
3. Double click on an item in the Call stack.

All other code navigation features should be expected to go to a file tab.

Unique Code Navigation Features for Debugger Canvas

Figure 7. Click in the breadcrumb bar of a bubble to add a peer of the item to the canvas.

We currently do not recommend adding files or types to the canvas, so these are filtered out of the search results.

Figure 8. Code search: Right click on canvas and search to add a member to the canvas.

We currently do not recommend adding files or types to the canvas, so these are filtered out of the search results.

Adding a Note to the Canvas

Figure 9. To create a note bubble, right click on the canvas, and then click on the yellow button.

Dealing with Very Large Code Fragments - word wrap and scrolling

Are bubbles showing up too big on the canvas? Does your code have very large methods? The canvas will add scroll bars to bubbles with very large methods in them. Also, you can reduce the width of bubbles further by turning on word wrap.

Figure 10. Word wrap and scroll bars help keep bubble size under control.

Turn on Word Wrap:

1. Click the code in a bubble, so that the editor is active.
2. Do Edit: Advanced: Word wrap.

Now bubbles will  be set to a maximum width, and word wrap used to make the code fit. You can resize the bubble by dragging the sides of the bubble in or out

Adjust defaults for bubble size:

1. Go to Debug: Debugger canvas: Options and Settings.
2. Here you can set values for default widths and heights with and without word wrap turned on.

Inspecting Values in the Debugger

All the usual ways of inspecting values in the debugger, such as the debugger data tips and the Locals window work as normal. In addition, each bubble has its own locals window.

Figure 11. Each bubble has its own locals window, where you can inspect values and even take snapshots to compare values as execution progresses. You can either use it as a fly out like illustrated, or you can pin it to the canvas as a bubble using the push pin button.

Zooming and Panning the Canvas

• Zoom using Ctrl-Scroll wheel, or the zoom control at the bottom left of the canvas:

Figure 12. Zoom control.

Pan by using the mini map in the upper left corner or by clicking on the canvas and dragging the mouse. You can also pan by using the scroll wheel of the mouse.

Figure 13. Mini map lets you get an overview of your canvas and pan it.

Using Debugger Canvas with IntelliTrace

1. Enable IntelliTrace with the IntelliTrace events and call information option turned on.
2. Run your application.
3. Click Break all in the IntelliTrace window or the Debugger toolbar.
4. Open the IntelliTrace tool window, and switch to Calls view.
5. Create a new canvas using Debug: Debugger canvas:  Create new canvas.
6. Drag and drop a call from the IntelliTrace tool window onto the canvas.
7. The canvas will now be populated with all the methods called as part of this call.

Figure 14. Drag and drop from IntelliTrace calls view to canvas to visualize calls.

Tip: Start with a rather small call first.  We've seen performance problems and bugs when dragging very large call trees onto the canvas.

You can also navigate through the in the Debugger Canvas:

1. After the canvas is populated, go to the IntelliTrace tool window and double click on the call you just dragged out to the canvas. The call now gets selected in the canvas.
2. Go to the View menu and show the IntelliTrace toolbar.
3. Now you can use the toolbar to walk through the trace in the canvas.

Figure 15. You can use the IntelliTrace toolbar to walk through traces on the canvas.

Highlighting Code Paths

Figure 16. Click on a call link to highlight the paths above and below it.

To select the paths above and below a call:

• Click on any link. Now, the link and all preceding and subsequent calls are highlighted in red

Note that this is a fairly simplistic function currently. The highlighted path represents a static call graph between methods, filtered down to the methods and calls that are on the canvas.

Managing Bubbles

Figure 17. Click in the bubble header to select, move or close the bubble. You can also multi select bubbles using Ctrl-click.

How do the Canvases Work?

When you start the debugger, a canvas will be created for you if none exists. Later, the same canvas and the same bubbles will be reused when you start the debugger again.

If you want a new canvas, you can create one using the Debug: Debugger canvas: Create new canvas command.

If you have multiple canvases open, the active one will be used when you start the debugger. If none is active, the most recently created one will be used.

When you close the solution, the canvases will be discarded.

Saving the Canvas as an Image

The canvas cannot be saved for future use. However, it can be saved as an image. There is also a command to send as e-mail if your machine has Outlook installed.

Figure 18. The Canvas can be saved as an XPS image.

Debugger Canvas Quirks and Known Issues

Adding the Debugger Canvas to Visual Studio 2010 required us to make some tradeoffs and workarounds. Here are some that are good to be aware of.

Debugger Data Tool tips do not work with Visual Studio 2010 RTM

The ability to inspect values by hovering over them in the debugger only works with SP1.

WebSite projects

Debugger Canvas does not work with WebSite projects. However it works fine for code behind web applications such as TailSpin Toys.

ReSharper

Debugger Canvas is incompatible with ReSharper.

Visual Studio Ultimate 2010 SP1 required

Debugger Canvas requires Service Pack 1 of Visual Studio 2010. It works only partially on the RTM version.

Undo

If you turn on editing in the canvas, the undo function will be somewhat limited. The tool cannot preserve the undo stack between edits in the file tabs and the canvas. As long as you are editing in the canvas you have normal Undo, and as long as you are editing in file tabs the Undo stack is fine as well. But when you make some edits in canvas and some in files, the Undo stack will be flushed each time you switch domains.

Pinning data tool tips

Data tool tips in the debugger work as normally in Visual Studio, with one exception: If you try to pin the tool tip to the canvas, it will pin "to the glass", meaning that it will not move around with the canvas, but stay in the same spot on your screen.

Layout

The layout algorithms and line routing in this canvas are very simplistic. You will see lines crossing each other and through bubbles. Sometimes the way bubbles are laid out does not make sense. There are limits to how much the current layout engine can be improved without replacing it altogether, but please use the forums to point out where layout issues get in the way of the usefulness of the tool.

F1

In the editor in a bubble, F1 unfortunately does not work.

IntelliSense

If editing is turned on, IntelliSense  works, with one exception. In some cases you cannot use the mouse to select entries in the IntelliSense drop down. Please use the keyboard instead.

Saving canvas?

Canvases cannot be saved, and they are not preserved between sessions. You can use the Save as XPS feature to save an image of the current canvas.

Saving code

When editing in a canvas, File: Save will save the entire file that holds the fragment you're currently editing.

Immediate window

If you evaluate an expression in the immediate window, it causes VS to switch to the tabbed version of the currently executing method, even if a bubble was showing.

Editor indenting

When doing actions that add or remove lines in the editor, sometimes indenting will not update properly in bubbles.