The Exception class has properties that contain useful information about the exception, as shown in the following table:

The two most important methods of the Exception class are as follows:

You will see these properties and methods used in the code examples shown later, after you have covered the syntax for detecting and handling exceptions.

Because an exception contains all of the information needed about an error, structured exception handling does not use error numbers and the Err object. The exception object contains all the relevant information about the error.

However, whereas there is only one global Err object in VB6, there are many types of exception objects in the .NET Framework. For example, if a divide by zero is done in code, then an OverflowException is generated. In addition to the dozens of exception types available in the .NET Framework, you can inherit from a class called ApplicationException and create your own exception classes (see Chapter 3 for a discussion of inheritance).

In .NET, all exceptions inherit from System.Exception. Special-purpose exception classes can be found in many namespaces. The following table lists four representative examples of the classes that extend Exception:

There are literally dozens of exception classes scattered throughout the .NET Framework namespaces. It is common for an exception class to reside in a namespace with the classes that typically generate the exception. For example, the DataException class is in System.Data, with the ADO.NET components that often generate a DataException instance.

Having many types of exceptions in VB 2008 enables different types of conditions to be trapped with different exception handlers. This is a major advance over VB6. The syntax to accomplish that is discussed next.

Here is an example showing some typical, simple structured exception-handling code in VB 2008. In this case, the most likely source of an error is the iItems argument. If it has a value of zero, then this would lead to dividing by zero, which would generate an exception.

First, create a Windows Application in Visual Basic 2008 and place a button on the default Form1 created in the project. In the button's click event, place the following two lines of code:

Dim sngAvg As Single
sngAvg = GetAverage(0, 100)

Then put the following function in the form's code:

Private Function GetAverage(iItems As Integer, iTotal As Integer) as Single
     ' Code that might throw an exception is wrapped in a Try block
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown if iItems = 0
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error
        MessageBox.Show("Calculation successful")
        Return sngAverage

    Catch excGeneric As Exception
        ' If the calculation failed, you get here
        MessageBox.Show("Calculation unsuccessful - exception caught")
        Return 0
    End Try
End Function

This code traps all the exceptions with a single generic exception type, and you don't have any Finally logic. Run the program and press the button. You will be able to follow the sequence better if you place a breakpoint at the top of the GetAverage function and step through the lines.

Here is a more complex example that traps the divide-by-zero exception explicitly. This second version of the GetAverage function (notice that the name is GetAverage2) also includes a Finally block:

Private Function GetAverage2(iItems As Integer, iTotal As Integer) as Single
     ' Code that might throw an exception is wrapped in a Try block
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error.
        MessageBox.Show("Calculation successful")
        Return sngAverage
     Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block
        MessageBox.Show("Calculation generated DivideByZero Exception")
        Return 0
    Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
        Return 0
    Finally
        ' Code in the Finally block will always run.
         MessageBox.Show("You always get here, with or without an error")
    End Try

End Function

This code contains two Catch blocks for different types of exceptions. If an exception is generated, then .NET will go down the Catch blocks looking for a matching exception type. That means the Catch blocks should be arranged with specific types first and more generic types after.

Place the code for GetAverage2 in the form, and place another button on Form1. In the Click event for the second button, place the following code:

Dim sngAvg As Single
sngAvg = GetAverage2(0, 100)

Run the program again and press the second button. As before, it's easier to follow if you set a breakpoint early in the code and then step through the code line by line.

Sometimes a Catch block is unable to handle an error. Some exceptions are so unexpected that they should be "sent back up the line" to the calling code, so that the problem can be promoted to code that can decide what to do with it. A Throw statement is used for that purpose.

A Throw statement ends execution of the exception handler — that is, no more code in the Catch block after the Throw statement is executed. However, Throw does not prevent code in the Finally block from running. That code still runs before the exception is kicked back to the calling routine.

You can see the Throw statement in action by changing the earlier code for GetAverage2 to look like this:

Private Function GetAverage3(iItems As Integer, iTotal as Integer) as Single
     ' Code that might throw an exception is wrapped in a Try block
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error.
        MessageBox.Show("Calculation successful")
        Return sngAverage

    Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block.
        MessageBox.Show("Calculation generated DivideByZero Exception")
         Throw excDivideByZero
        MessageBox.Show("More logic after the throw - never executed")

    Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
         Throw excGeneric
    Finally
        ' Code in the Finally block will always run, even if
        ' an exception was thrown in a Catch block.
        MessageBox.Show("You always get here, with or without an error")
    End Try
End Function

Here is some code to call GetAverage3. You can place this code in another button's click event to test it out:

Try
    Dim sngAvg As Single
    sngAvg = GetAverage3(0, 100)

Catch exc As Exception
    MessageBox.Show("Back in the click event after an error")
Finally
    MessageBox.Show("Finally block in click event")
End Try

Throw can also be used with exceptions that are created on-the-fly. For example, you might want your earlier function to generate an ArgumentException, as you can consider a value of iItems of zero to be an invalid value for that argument.

In such a case, a new exception must be instantiated. The constructor allows you to place your own custom message into the exception. To show how this is done, let's change the aforementioned example to throw your own exception instead of the one caught in the Catch block:

Private Function GetAverage4(iItems As Integer, iTotal as Integer) as Single

    If iItems = 0 Then
        Dim excOurOwnException As New _
             ArgumentException("Number of items cannot be zero")

         Throw excOurOwnException
    End If


 ' Code that might throw an exception is wrapped in a Try block.
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error.
        MessageBox.Show("Calculation successful")
        Return sngAverage

    Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block.
        MessageBox.Show("Calculation generated DivideByZero Exception")
        Throw excDivideByZero
        MessageBox.Show("More logic after the thrown - never executed")
    Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
         Throw excGeneric
    Finally
        ' Code in the Finally block will always run, even if
        ' an exception was thrown in a Catch block.
        MessageBox.Show("You always get here, with or without an error")

End Try
End Function

This code can be called from a button with similar code for calling GetAverage3. Just change the name of the function called to GetAverage4.

This technique is particularly well suited to dealing with problems detected in property procedures. Property Set procedures often do checking to ensure that the property is about to be assigned a valid value. If not, then throwing a new ArgumentException (instead of assigning the property value) is a good way to inform the calling code about the problem.

The Exit Try statement will, under a given circumstance, break out of the Try or Catch block and continue at the Finally block. In the following example, you exit a Catch block if the value of iItems is 0, because you know that your error was caused by that problem:

Private Function GetAverage5(iItems As Integer, iTotal as Integer) As Single
     ' Code that might throw an exception is wrapped in a Try block.
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error.
        MessageBox.Show("Calculation successful")
        Return sngAverage

    Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block.
         If iItems = 0 Then
             Return 0
             Exit Try
         Else
             MessageBox.Show("Error not caused by iItems")
         End If
        Throw excDivideByZero
        MessageBox.Show("More logic after the thrown - never executed")

    Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
        Throw excGeneric
    Finally
        ' Code in the Finally block will always run, even if
        ' an exception was thrown in a Catch block.
        MessageBox.Show("You always get here, with or without an error")
    End Try
End Sub

In your first Catch block, you have inserted an If block so that you can exit the block given a certain condition (in this case, if the overflow exception was caused because the value of intY was 0). The Exit Try goes immediately to the Finally block and completes the processing there:

If iItems = 0 Then
  Return 0
  Exit Try
Else
  MessageBox.Show("Error not caused by iItems")
End If

Now, if the overflow exception is caused by something other than division by zero, then you'll get a message box displaying "Error not caused by iItems."

Sometimes particular lines in a Try block may need special exception processing. Moreover, errors can occur within the Catch portion of the Try structures and cause further exceptions to be thrown. For both of these scenarios, nested Try structures are available. You can alter the example under the section "The Throw Keyword" to demonstrate the following code:

Private Function GetAverage6(iItems As Integer, iTotal as Integer) As Single

    ' Code that might throw an exception is wrapped in a Try block.
    Try
        Dim sngAverage As Single

         ' Do something for performance testing... .
         Try
             LogEvent("GetAverage")
         Catch exc As Exception
             MessageBox.Show("Logging function unavailable")
         End Try

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)

        ' This only executes if the line above generated no error.
        MessageBox.Show("Calculation successful")
        Return sngAverage

    Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block.
        MessageBox.Show("Error not divide by 0")
        Throw excDivideByZero
        MessageBox.Show("More logic after the thrown - never executed")
     Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
        Throw excGeneric

Finally
        ' Code in the Finally block will always run, even if
        ' an exception was thrown in a Catch block.
        MessageBox.Show("You always get here, with or without an error")
    End Try
End Function

In the preceding example, you are assuming that a function exists to log an event. This function would typically be in a common library, and might log the event in various ways. You will look at logging exceptions in detail later in the chapter, but a simple LogEvent function might look like this:

Public Sub LogEvent(ByVal sEvent As String)
     FileOpen(1, "logfile.txt", OpenMode.Append)
     Print(1, DateTime.Now & "-" & sEvent & vbCrLf)
     FileClose(1)

End Sub

In this case, you don't want a problem logging an event, such as a "disk full" error, to crash the routine. The code for the GetAverage function triggers a message box to indicate trouble with the logging function.

A Catch block can be empty. In that case, it has a similar effect as On Error Resume Next in VB6: the exception is ignored. However, execution does not pick up with the line after the line that generated the error, but instead picks up with either the Finally block or the line after the End Try if no Finally block exists.

The previous examples have displayed hard-coded messages in message boxes, which is obviously not a good technique for production applications. Instead, a message box or log entry describing an exception should provide as much information as possible concerning the problem. To do this, various properties of the exception can be used.

The most brutal way to get information about an exception is to use the ToString method of the exception. Suppose that you modify the earlier example of GetAverage2 to change the displayed information about the exception like this:

Private Function GetAverage2(ByVal iItems As Integer, ByVal iTotal As Integer) _
        As Single
    ' Code that might throw an exception is wrapped in a Try block.
    Try
        Dim sngAverage As Single

        ' This will cause an exception to be thrown.
        sngAverage = CSng(iTotal  iItems)
        ' This only executes if the line above generated no error.
         MessageBox.Show("Calculation successful")
        Return sngAverage

Catch excDivideByZero As DivideByZeroException
        ' You'll get here with an DivideByZeroException in the Try block.
         MessageBox.Show(excDivideByZero.ToString)
        Throw excDivideByZero
        MessageBox.Show("More logic after the thrown - never executed")

    Catch excGeneric As Exception
        ' You'll get here when any exception is thrown and not caught in
        ' a previous Catch block.
        MessageBox.Show("Calculation failed - generic exception caught")
        Throw excGeneric
    Finally
        ' Code in the Finally block will always run, even if
        ' an exception was thrown in a Catch block.
        MessageBox.Show("You always get here, with or without an error")
    End Try
End Function

When the function is accessed with iItems = 0, a message box similar to the one in Figure 8-1 will be displayed.

Figure 8.1. Figure 8-1

The message shown in Figure 8-1 is helpful to a developer because it contains a lot of information, but it's not something you would typically want users to see. Instead, a user normally needs to see a short description of the problem, and that is supplied by the Message property.

If the previous code is changed so that the Message property is used instead of ToString, then the message box will provide something like what is shown in Figure 8-2.

Figure 8.2. Figure 8-2

The InnerException property is used to store an exception trail. This comes in handy when multiple exceptions occur. It's quite common for an exception to occur that sets up circumstances whereby further exceptions are raised. As exceptions occur in a sequence, you can choose to stack them for later reference by use of the InnerException property of your Exception object. As each exception joins the stack, the previous Exception object becomes the inner exception in the stack.

For simplicity, you'll start a new code sample, with just a subroutine that generates its own exception. You'll include code to add a reference to an InnerException object to the exception you are generating with the Throw method.

This example also includes a message box to show what's stored in the exception's TargetSite property. As shown in the results, TargetSite will contain the name of the routine generating the exception — in this case, HandlerExample. Here's the code:

Sub HandlerExample()
  Dim intX As Integer
  Dim intY As Integer
  Dim intZ As Integer
  intY = 0
  intX = 5
  ' First Required Error Statement.
  Try
    ' Cause a "Divide by Zero"
    intZ = CType((intX  intY), Integer)
  ' Catch the error.
  Catch objA As System.DivideByZeroException
     Try
       Throw (New Exception("0 as divisor", objA))
     Catch objB As Exception
       Dim sError As String
       sError = "My Message: " & objB.Message & vbCrLf & vbCrLf
       sError &= "Inner Exception Message: " & _
           objB.InnerException.Message & vbCrLf & vbCrLf
       sError &= "Method Error Occurred: " & objB.TargetSite.Name
       MessageBox.Show(sError)
     End Try
  Catch
    Messagebox.Show("Caught any other errors")
  Finally
    Messagebox.Show(Str(intZ))
  End Try
End Sub

As before, you catch the divide-by-zero error in the first Catch block, and the exception is stored in objA so that you can reference its properties later.

You throw a new exception with a more general message ("0 as divisor") that is easier to interpret, and you build up your stack by appending objA as the InnerException object using an overloaded constructor for the Exception object:

Throw (New Exception("0 as divisor", objA))

You catch your newly thrown exception in another Catch statement. Note how it does not catch a specific type of error:

Catch objB As Exception

Then you construct an error message for the new exception and display it in a message box:

Dim sError As String
sError = "My Message: " & objB.Message & vbCrLf & vbCrLf
sError &= "Inner Exception Message: " & _
    objB.InnerException.Message & vbCrLf & vbCrLf
sError &= "Method Error Occurred: " & objB.TargetSite.Name
MessageBox.Show(sError)

The message box that is produced is shown in Figure 8-3.

Figure 8.3. Figure 8-3

First your own message is included, based on the new exception thrown by your own code. Then the InnerException gets the next exception in the stack, which is the divide-by-zero exception, and its message is included. Finally, the TargetSite property gives you the name of the method that threw the exception. TargetSite is particularly helpful in logs or error reports from users that are used by developers to track down unexpected problems.

After this message box, the Finally clause displays another message box that just shows the current value of intZ, which is zero because the divide failed. This second box also occurs in other examples that follow.

Source and StackTrace

The Source and StackTrace properties provide the user with information regarding where the error occurred. This supplemental information can be invaluable, as the user can pass it on to the troubleshooter in order to help resolve errors more quickly. The following example uses these two properties and shows the feedback when the error occurs:

Sub HandlerExample2()

 Dim intX As Integer
 Dim intY As Integer
 Dim intZ As Integer
 intY = 0
 intX = 5

' First Required Error Statement.
  Try
    ' Cause a "Divide by Zero"
    intZ = CType((intX  intY), Integer)
  ' Catch the error.
  Catch objA As System.DivideByZeroException
     objA.Source = "HandlerExample2"
     Messagebox.Show("Error Occurred at :" & _
         objA.Source & objA.StackTrace)
  Finally
    Messagebox.Show(Str(intZ))
  End Try
End Sub

The output from the Messagebox statement is very detailed, providing the entire path and line number where the error occurred, as shown in Figure 8-4.

Figure 8.4. Figure 8-4

Notice that this information is also included in the ToString method examined earlier (refer to Figure 8-1).

GetBaseException

The GetBaseException method comes in very handy when you are deep in a set of thrown exceptions. This method returns the originating exception, which makes debugging easier and helps keep the troubleshooting process on track by sorting through information that can be misleading:

Sub HandlerExample3()
  Dim intX As Integer
  Dim intY As Integer
  Dim intZ As Integer
  intY = 0
  intX = 5
  ' First Required Error Statement.
  Try
    ' Cause a "Divide by Zero"
    intZ = CType((intX  intY), Integer)
  ' Catch the error.
  Catch objA As System.DivideByZeroException

Try
       Throw (New Exception("0 as divisor", objA))
     Catch objB As Exception
       Try
         Throw (New Exception("New error", objB))
       Catch objC As Exception
         Messagebox.Show(objC.GetBaseException.Message)
       End Try
     End Try
  Finally
    Messagebox.Show(Str(intZ))
  End Try
End Sub

The InnerException property provides the information that the GetBaseException method needs, so as your example executes the Throw statements, it sets up the InnerException property. The purpose of the GetBaseException method is to provide the properties of the initial exception in the chain that was produced. Hence, objC.GetBaseException.Message returns the Message property of the original OverflowException message even though you've thrown multiple errors since the original error occurred:

Messagebox.Show(objC.GetBaseException.Message)

To put it another way, the code traverses back to the exception caught as objA and displays the same message as the objA.Message property would, as shown in Figure 8-5.

Figure 8.5. Figure 8-5

Dim exc As New ApplicationException("A short description of the problem")
exc.HelpLink = "http://mysite.com/somehtmlfile.htm"
Throw exc

Sub HandlerExample4()
Try

    Dim exc As New ApplicationException("A short description of the problem")
    exc.HelpLink = "http://mysite.com/somehtmlfile.htm"
    Throw exc


    ' Catch the error.
Catch objA As System.Exception
    Shell("explorer.exe " & objA.HelpLink)


End Try
End Sub

Three Event Logs are available: the System, Application, and Security Logs. Events in these logs can be viewed using the Event Viewer, which is accessed from the Control Panel. Access Administrative Tools and then select the Event Viewer subsection to view events. Typically, your applications would use the Application Event Log.

Event logging is available in your program through an EventLog component, which can both read and write to all of the available logs on a machine. The EventLog component is part of the System.Diagnostics namespace. This component allows adding and removing custom Event Logs, reading and writing to and from the standard Windows Event Logs, and creating customized Event Log entries.

Event Logs can become full, as they have a limited amount of space, so you only want to write critical information to your Event Logs. You can customize each of your system Event Log's properties by changing the log size and specifying how the system will handle events that occur when the log is full. You can configure the log to overwrite data when it is full or overwrite all events older than a given number of days. Remember that the Event Log that is written to is based on where the code is running from, so if there are many tiers, then you must locate the proper Event Log information to research the error further.

There are five types of Event Log entries you can make. These five types are divided into event type entries and audit type entries.

Event type entries are as follows:

Audit type entries usually go into the Security Log and can be either of the following:

If you don't specify the type of Event Log entry, an information type entry is generated.

Each entry in an Event Log has a Source property. This required property is a programmer-defined string that is assigned to an event to help categorize the events in a log. A new Source must be defined prior to being used in an entry in an Event Log. The SourceExists method is used to determine whether a particular source already exists on the given computer. Use a string that is relevant to where the error originated, such as the component's name. Packaged software often uses the software name as the Source in the Application Log. This helps group errors that occur by specific software package.

The EventLog component is in the System.Diagnostics namespace. To use it conveniently, include an Imports System.Diagnostics statement in the declarations section of your code.

The most common events, methods, and properties for the EventLog component are listed and described in the following tables.

The following table describes the relevant event:

The following table describes the relevant methods:

The following table describes the relevant properties:

The following example illustrates some of these methods and properties:

Sub LoggingExample1()
  Dim objLog As New EventLog()
  Dim objLogEntryType As EventLogEntryType
  Try
    Throw (New EntryPointNotFoundException())
  Catch objA As System.EntryPointNotFoundException
    If Not EventLog.SourceExists("Example") Then
      EventLog.CreateEventSource("Example", "System")
    End If
    objLog.Source = "Example"

objLog.Log = "System"
    objLogEntryType = EventLogEntryType.Information
    objLog.WriteEntry("Error: " & objA.Message, objLogEntryType)
  End Try
End Sub

The preceding code declares two variables: one to instantiate your log and one to hold your entry's type information. Note that you need to check for the existence of a source prior to creating it. The following two lines of code accomplish that:

If Not EventLog.SourceExists("Example") Then
  EventLog.CreateEventSource("Example", "System")

After you have verified or created your source, you can set the Source property of the EventLog object, the Log property to specify which log you want to write to, and EventLogEntryType to Information (other options are Warning, Error, SuccessAudit, and FailureAudit). If you attempt to write to a source that does not exist in a specific log, then you get an error. After you have set these three properties of the EventLog object, you can then write your entry. In this example, you concatenated the word Error with the actual exception's Message property to form the string to write to the log:

objLog.Source = "Example"
objLog.Log = "System"
objLogEntryType = EventLogEntryType.Information
objLog.WriteEntry("Error: " & objA.Message, objLogEntryType)

As an alternative to the Event Log, you can write your debugging and error information to trace files. A trace file is a text-based file that you generate in your program to track detailed information about an error condition. Trace files are also a good way to supplement your event logging if you want to track detailed information that would potentially fill the Event Log.

A more detailed explanation of the variety of trace tools and their uses in debugging follows in the section "Analyzing Problems and Measuring Performance via the Trace Class." This section covers some of the techniques for using the StreamWriter interface in your development of a trace file.

The concepts involved in writing to text files include setting up streamwriters and debug listeners. The StreamWriter interface is handled through the System.IO namespace. It enables you to interface with the files in the file system on a given machine. The Debug class interfaces with these output objects through listener objects. The job of any listener object is to collect, store, and send the stored output to text files, logs, and the Output window. In the example, you will use the TextWriterTraceListener interface.

As you will see, the StreamWriter object opens an output path to a text file, and by binding the StreamWriter object to a listener object you can direct debug output to a text file.

Trace listeners are output targets and can be a TextWriter or an EventLog, or can send output to the default Output window (which is DefaultTraceListener). The TextWriterTraceListener accommodates the WriteLine method of a Debug interface by providing an output object that stores information to be flushed to the output stream, which you set up by the StreamWriter interface.

The following table lists some of the commonly used methods from the StreamWriter object:

The following table lists some of the methods associated with the Debug object, which provides the output mechanism for the text file example to follow:

The following example shows how you can open an existing file (called mytext.txt) for output and assign it to the Listeners object of the Debug object so that it can catch your Debug.WriteLine statements:

Sub LoggingExample2()
  Dim objWriter As New _
      IO.StreamWriter("C:mytext.txt", True)
   Debug.Listeners.Add(New TextWriterTraceListener(objWriter))
  Try
    Throw (New EntryPointNotFoundException())
  Catch objA As System.EntryPointNotFoundException
    Debug.WriteLine(objA.Message)

objWriter.Flush()
    objWriter.Close()
    objWriter = Nothing
  End Try
End Sub

Looking in detail at this code, you first create a StreamWriter that is assigned to a file in your local file system:

Dim objWriter As New _
    IO.StreamWriter("C:mytext.txt", True)

You then assign your StreamWriter to a debug listener by using the Add method:

Debug.Listeners.Add(New TextWriterTraceListener (objWriter))

This example forces an exception and catches it, writing the Message property of the Exception object (which is Entry point was not found) to the debug buffer through the WriteLine method:

Debug.WriteLine(objA.Message)

Finally, you flush the listener buffer to the output file and free your resources:

objWriter.Flush()
objWriter.Close()
objWriter = Nothing