Section 17.8. Exception Class Methods and Properties

17.8 Exception Class Methods and Properties

So far you've been using the exception as a sentinel ”that is, the presence of the exception signals the errors ”but you haven't touched or examined the Exception object itself. The System.Exception class provides a number of useful methods and properties.

The Message property provides information about the exception, such as why it was thrown. The Message property is read-only; the code throwing the exception can pass in the message as an argument to the exception constructor, but the Message property cannot be modified by any method once set in the constructor.

The HelpLink property provides a link to a help file associated with the exception. This property is read/write. In Example 17-6, the Exception.HelpLink property is set and retrieved to provide information to the user about the DivideByZeroException. It is generally a good idea to provide a help file link for any exceptions you create, so that the user can learn how to correct the exceptional circumstance.

The read-only StackTrace property is set by the CLR. This property is used to provide a stack trace for the error statement. A stack trace is used to display the call stack : the series of method calls that lead to the method in which the exception was thrown.

Example 17-6. Inside the Exception class

 Option Strict On Imports System Namespace ExceptionHandling     Class Tester                 Public Sub Run( )             Try                 Console.WriteLine("Open file here")                 Dim a As Double = 5                 Dim b As Double = 0                 Console.WriteLine("{0} / {1} = {2}", a, b, DoDivide(a, b))                 Console.WriteLine("This line may or may not print")                 ' most derived exception type first             Catch e As System.DivideByZeroException                 Console.WriteLine( _                   "DivideByZeroException! Msg: {0}", e.Message)                 Console.WriteLine( _                    "Helplink: {0}", e.HelpLink)                 Console.WriteLine( _                     "Stack trace: {0}", e.StackTrace)             Catch                 Console.WriteLine("Unknown exception caught!")             Finally                 Console.WriteLine("Close file here.")             End Try         End Sub 'Run         ' do the division if legal         Public Function DoDivide( _             ByVal a As Double, ByVal b As Double) As Double             If b = 0 Then                 Dim e As New System.DivideByZeroException( )              e.HelpLink = "http://www.LibertyAssociates.com"                 Throw e             End If             If a = 0 Then                 Throw New System.ArithmeticException( )             End If             Return a / b         End Function 'DoDivide         Shared Sub Main( )             Console.WriteLine("Enter Main...")             Dim t As New Tester( )             t.Run( )             Console.WriteLine("Exit Main...")         End Sub 'Main     End Class 'Tester End Namespace 'ExceptionHandling 

  Output:  Enter Main... Open file here DivideByZeroException! Msg: Attempted to divide by zero. HelpLink: http://www.libertyassociates.com Here's a stack trace:       at ExceptionHandling.Tester.DoDivide(Double a, Double b) in ...Module1.vb:line 38    at ExceptionHandling.Tester.Run( ) in ...Module1.vb:line 10 Close file here. Exit Main... 

In the output of Example 17-6, the stack trace lists the methods in the reverse order in which they were called; by reviewing this order, you can infer that the error occurred in DoDivide( ), which was called by Run( ). When methods are deeply nested, the stack trace can help you understand the order of method calls and thus track down the point at which the exception occurred.

In this example, rather than simply throwing a DivideByZeroException, you create a new instance of the exception:

 Dim e As New System.DivideByZeroException( ) Throw e 

You do not pass in a custom message, and so the default message will be printed:

 DivideByZeroException! Msg:  Attempted to divide by zero.  

The designer of each Exception class has the option to provide a default message for that exception type. All of the standard exceptions will provide a default message, and it is a good idea to add a default message to your custom exceptions as well (see Section 17.9, later in this chapter).

If you want, you can modify this line of code to pass in a custom message:

 Dim e As New System.DivideByZeroException( _   "You tried to divide by zero which is not meaningful") 

In this case, the output message will reflect the custom message:

 DivideByZeroException! Msg:  You tried to divide by zero which is not  meaningful 

Before throwing the exception, you set the HelpLink property:

 e.HelpLink =  "http://www.libertyassociates.com" 

When this exception is caught, Console.WriteLine( ) prints both the message and the HelpLink:

 Catch e As System.DivideByZeroException     Console.WriteLine( _       "DivideByZeroException! Msg: {0}", e.Message)     Console.WriteLine( _        "Helplink: {0}", e.HelpLink) 

The Message and HelpLink properties allow you to provide useful information to the user. The exception handler also prints the StackTrace by getting the StackTrace property of the Exception object:

 Console.WriteLine( _     "Stack trace: {0}", e.StackTrace) 

The output of this call reflects a full StackTrace leading to the moment the exception was thrown. In this case, only two methods were executed before the exception, DoDivide( ) and Run ( ):

 Here's a stack trace:       at ExceptionHandling.Tester.DoDivide(Double a, Double b) in Module1.vb:line 38    at ExceptionHandling.Tester.Run( ) in Module1.vb:line 10 

Note that I've shortened the pathnames, so your printout might look a little different.