Using the Debug Class

Using the Debug Class
During the testing of your application, you may find that when you are
stepping through code the application works fine, but when you run the
program straight through it does not work the way you expected. The reason
for this is that you can change the way your program runs by using the
debugger梩he fact that you're executing the code extremely slowly can
affect the behavior of the application! Instead of using the debugger to
test values, you may find it convenient to print those values to the
Immediate window.

You may print directly to the Output window (use the View, Other Windows,
Output menu item to display this window and select Debug from the drop-down
list at the top of the window) from within your application by executing
the Debug.Write or Debug.WriteLine method. The values placed into the
Immediate window using either of these methods will still be available in
Break or Design mode. It can be useful to see those values without having
to enter Break mode and thereby possibly change the execution of your
program. You'll most likely use the WriteLine method of the Debug object,
simply sending the method a string to display in the Output window, like
this:

Debug.WriteLine("Now executing btnStart_Click()")

TIP

The Output window can display both Build and Debug information. Make sure
you select Debug from the drop-down list at the top of the window in order
to see the Debug.WriteLine output.



To illustrate these points, make sure DebugForm.aspx is the start page for
the sample project, run the project, and select Debug Class on the Web
page. Clicking this button loads a Web Form named DebugEvents.aspx. This
form includes several calls to the Debug.WriteLine method in several
different event procedures. This page illustrates the use of the
Debug.WriteLine method and also gives you an idea of which events are fired
when a Web Form loads and unloads. Figure 9.23 shows some of the sample
output from these Debug.WriteLine method calls.

Figure 9.23. Sample output from DebugEvents Web Form.


NOTE

If you're a VB6 developer, you may be used to the output from the Debug
class going into the Immediate window. Look there all you like in Visual
Studio .NET, but you won't find what you're looking for. This content now
goes to the Output window instead.



Listing 9.1 shows part of the code that creates the output shown in Figure
9.23.

Listing 9.1 The Example Uses This Code to Help Demonstrate Debugging
Techniques
Private Sub Page_Load( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
Handles MyBase.Load
  'Put user code to initialize the page here

  Debug.WriteLine("Page_Load")

End Sub

Private Sub Page_PreRender( _
ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles MyBase.PreRender

  Debug.WriteLine("Page_PreRender")

End Sub

Private Sub Page_Unload( _
ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles MyBase.Unload



  Debug.WriteLine("Page_Unload")

End Sub

The Debug class has several methods you might find useful, in addition to
the WriteLine method. Table 9.4 describes some of the more common ones you
might use.

Table 9.4. Methods of the Debug Class Method  Description 
Assert  Stops the program if the condition you pass to this method does not
evaluate to True. This method only works in the design mode: All Debug
statements are removed from the final compiled program. 
Write  Writes a value to the output window without a CRLF. 
WriteLine  Writes a value to the output window with a CRLF. 
WriteIf  Writes a value to the output window without a CRLF, if a specified
condition is true. 
WriteLineIf  Writes a value to the output window with a CRLF, if a
specified condition is true. 


The Assert Method
The Debug.Assert method allows you to insert assertions in your code梩hat
is, debugging statements that display information into the Output window if
a specific condition isn't met. Debug.Assert is a powerful debugging tool
in that it allows you to ensure that you've passed correct parameters to a
procedure or that a variable always contains a specific value or range of
values. Some programmers insist that you shouldn't program an application
without using the Debug.Assert method scattered throughout your whole
application anytime you make any type of assumption about the current state
of parameters of variables. The following code shows how you might check to
see whether a number typed into a text box was typed in correctly:

Private Sub AssertSample()
  Dim intNum As Integer

  intNum = CInt(Val(txtNumber.Text))


  Debug.Assert(intNum >= 0 And intNum <= 5, _
    "Number must be between 0 and 5")
End Sub

If you run this code and enter 6 into the text box on sample form
(DebugClass.aspx), the assertion will return False. The .NET runtime will
display a message into the Output window like the one shown in Figure 9.24.

Figure 9.24. Debug.Assert displays information like this into the Output
window when the assertion fails.


TIP

Debug.Assert isn't normally used to validate input, as you've seen here.
The validation controls provided by ASP.NET do a better job at that. We've
purposefully selected a simple example here, just to demonstrate how you
might use Debug.Assert. Normally, you'd use Debug.Assert to verify that the
data sent to a procedure meets certain criteria that you just assume梖or
example, that a string isn't too long or that a value that shouldn't be
zero is, in fact, not equal to zero.



The WriteLineIf Method
If you only wish to write a line to the Output window when a specified
condition is true, you can use the WriteLineIf method of the Debug class.
For example, the sample page uses code like the following to check a
condition before writing information to the Output window:

Private Sub WriteLineIfSample()
  Dim intNum As Integer

  intNum = CInt(txtNumber.Text)
  Debug.WriteLineIf(intNum >= 0 And intNum <= 5, _
   "You input a correct number")
End Sub

TIP

If you want to dig a little deeper, you'll find that the Debug class (and
its cousin, the Trace class) are far more powerful than you've seen here.
Each of these classes relies on the concept of "listener" objects梩hat is,
objects that "listen" for output and collect the output for display. By
default, the only listener for the Debug class is the Output window.
Without too much effort, you can create listeners that write output to a
text file or to the Windows Event Log. Although doing this work is beyond
the scope of this material, you can check out the Debug class in the online
help for information on creating other listeners.