This documentation is archived and is not being maintained.

Debugging Windows Forms Controls Created with Visual Basic .NET or Visual C# .NET

Visual Studio .NET 2003

Matthew A. Stoecker
Visual Studio Team
Microsoft Corporation

February 2002

Summary: This paper shows the basics of how to debug your user controls, by creating a host application for them to run in. Stepping through code and setting breakpoints will also be discussed. (6 printed pages)


Creating Your User Control
Creating the Test project
Debugging the Project


The Visual Studio® .NET integrated development environment (IDE) provides numerous tools to help you monitor program execution and locate bugs in your user controls and custom controls. You can use the debugging tools to step through your code line-by-line, to add breakpoints in your code, and use the various debugging windows to monitor execution conditions at run time. Because controls are not stand-alone projects, you must provide a host for your control while debugging. In this article, you will create a simple user control, and then use various debugging techniques. Although this article uses a user control, these techniques are applicable to custom controls and inherited controls as well. See Control Authoring for Windows Forms for more infromation on creating different types of controls.


To get the most out of this paper, you should understand how to create a simple user control. For a walkthrough, see Walkthrough: Authoring a User Control with Visual Basic .NET or Walkthrough: Authoring a User Control with Visual C#. You should also have a basic understanding of structured exception handling. For more information, see Introduction to Exception Handling in Visual Basic .NET.

Creating Your User Control

You will begin your exploration of control debugging by creating a simple user control: a control with a single button that displays a message box when clicked.

To create your user control

  1. Create a new Windows Control Library project and name it ControlDemo.
  2. From the Windows Forms tab of the Toolbox, add a Button to the design surface of your control.
  3. In the designer, double-click Button1 (button1 in C#) to open the click event handler for this button and add the following code, which will provide the code for your user control as well as add code that throws an exception at run time.
    ' Visual Basic
    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As _
       System.EventArgs) Handles Button1.Click
       Dim myInteger as Integer
       myInteger = 42
       ' Throw an exception at run time.
       Throw New ApplicationException("There is an unspecified error")
    End Sub
    // C#
    private void button1_Click(object sender, System.EventArgs e)
       int myInteger;
       myInteger = 42;
       // Throw an exception at run time. 
       throw new ApplicationException("There is an unspecified error");
  4. From the Build menu, choose Build ControlDemo to build your project.

Creating the Test Project

In order to debug your control, it must reside in a host project at run time. In this section, you will add a form to your project and create an instance of your user control on the form.

To create the test form

  1. From the File menu, select Add Project and choose Add New Project.

    The Add New Project dialog box opens.

  2. Choose Windows Application and name it TestProject, then click OK to add the project to your solution.
  3. In Solution Explorer, right-click TestProject and select Set As StartUp Project from the shortcut menu.
  4. In the Windows Forms tab of the Toolbox, double-click UserControl1.

    The user control you created earlier is added to the form. You might have to scroll to locate it.

  5. From the File menu, choose Save All.

Debugging the Project

Your have now created a user control. Although this very simple example does not require much in the way of debugging, a complex user control might encapsulate thousands of lines of code. Ensuring that logical errors are not incorporated into your control is very important, and debugging allows you to eliminate logical errors that have been incorporated into your control.

Using your test control as a guide, you will now explore some of the features of the Visual Studio debugger.

Breaking on Exceptions

If an exception is thrown when debugging a control, the code execution will break on the line that causes the exception. This will occur at the deepest point in the call stack — that is, if an error occurs in a control method that was called from the host application, execution will break on the line in the control method.

The user control you have created contains the following line of code:

' Visual Basic
Throw New ApplicationException("There is an unspecified error")

// C#
throw new ApplicationException("There is an unspecified error");

This line throws an exception during execution. When running in debug mode, an exception will cause program execution to break at the line that throws the exception.

To locate lines that throw exceptions

  1. Press F5 to build and start the application with debugging.

    The application starts and the startup form appears with the user control on it.

  2. Click Button1.

    Application execution halts and returns to Code view, and an error message about the unhandled exception appears.

  3. Click Break to enter break mode.

    The line that threw the exception is highlighted. You can now examine the line to determine the cause of the error.

Stepping Through Code

At times, you might want to examine execution of your application line by line. Visual Studio .NET allows you to monitor program execution by stepping through each line of code as it executes, by choosing a line of code to break on during execution, or by setting breakpoints in the code that halt execution when a particular line is reached.

Breakpoints are useful when you suspect that a block of code causes an error, but are uncertain which line actually contains the flaw. You can set a breakpoint that halts program execution before entering the block of code, then step through each line while examining the application variables. Additionally, if you suspect errors in multiple code blocks, you can set several breakpoints and step through them sequentially.

In this section, you will learn how to set a breakpoint in your code and step through subsequent lines.

To set a breakpoint and step through code

  1. Open the Code Editor for UserControl1.
  2. In the Button1.Click event, locate the following line:
    ' Visual Basic
    myInteger = 42
    // C#
    myInteger = 42;
  3. Set a breakpoint on this line by clicking the Margin Indicator bar to the left of this line, or by setting the cursor position to the line and selecting New Breakpoint from the Debug menu.

    A breakpoint is inserted at the line indicated, which is now highlighted and has a dot in the left margin.

  4. Press F5 to begin debugging.
  5. Click Button1.

    Program execution breaks at the breakpoint you inserted.

  6. Press F11 or choose Step Over from the Debug menu to step through your code line by line until the line that throws the exception is executed.
    Note   When stepping through code, the line that is about to be executed is highlighted.
  7. From the Debug menu, choose Stop Debugging to make the code editor writable.
  8. Fix the "error" by commenting out the line that is throwing the exception. An example is shown below:
    ' Visual Basic
    ' Throw New ApplicationException("There is an unspecified error")
    // C#
    // throw new ApplicationException("There is an unspecified error");
  9. Right-click your breakpoint and select Remove Breakpoint from the shortcut menu to clear the breakpoint.
  10. From the Debug menu, choose Start to restart the application.
  11. Press Button1.

    The control now functions normally.

Stepping Line by Line

You can step through each line of code from the beginning of your application by pressing the F11 key or choosing Step Into from the Debug menu key. Every line that is executed will be shown sequentially, except for methods that are marked with the System.Diagnostics.DebuggerStepThrough attribute, which are stepped over.

Stepping Over Code

Additionally, you can use F10 or Step Over from the Debug menu to step over code. When you choose this option, you step over any lines that are executed outside of the current method. This can be useful if your method makes a call to a long or recursive method that you do not need to monitor execution of, for example.


In this paper you have learned how to use the Visual Studio .NET debugging tools to debug your user controls. After a control is built and hosted in a host application, you can debug your control as you would debug any other part of your application. The techniques that you have learned are also applicable to custom controls and inherited controls, as well as components in general.