15.3 Properties Reference

integer = HttpException.ErrorCode

Returns an integer representing the Win32 error code or HRESULT of the exception. This property is especially useful in situations when you are working with COM objects through COM Interop and need to return or evaluate the HRESULT returned from a COM object failure. When creating HttpException instances in your own code, you can use one of two overloaded constructors (shown earlier in Section 15.1) to set this property for HttpExceptions that you throw.

Parameter

integer

An integer that will receive the HRESULT or Win32 error code from the property.

Example

The code example uses the Page_Load event handler to throw an HttpException with a custom error message and error code, and then uses structured exception handling to catch the exception and display the error message and error code as the text of an ASP.NET Label control:

Sub Page_Load( )
   Try
      Throw New HttpException("Threw an error from Page_Load", 100)
   Catch HttpEx As HttpException
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Error Code: " & HttpEx.ErrorCode & "<br/>"
   End Try
End Sub

Notes

While the ErrorCode property is primarily useful when working with COM objects, this property is also set by the ASP.NET intrinsic objects when an exception is thrown.

string = HttpException.HelpLink
HttpException.HelpLink = string

Sets or returns a string containing the URN or URL to a help file containing information about the exception.

Parameter

string

A string that will set the HelpLink property or receive the help link from the property.

Example

The code example will display the help link associated with a custom HttpException:

Sub Page_Load( )
   Try
      Dim myHttpEx As _
         New HttpException("Threw an exception from Page_Load")
      myHttpEx.HelpLink = "file://C:/myHelpDir/myHelpFile.htm"
      Throw myHttpEx
   Catch HttpEx As HttpException
      Message.ForeColor = System.Drawing.Color.Red
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Error Code: " & HttpEx.ErrorCode & "<br/>"
      Message.Text &= "Help Link: " & HttpEx.HelpLink & "<br/>"
   End Try
End Sub

Notes

The HelpLink is not always set by exceptions thrown from the ASP.NET intrinsic objects. For example, if you attempt to access the Session intrinsic object when Session state is disabled, an HttpException will be thrown, but its HelpLink property will return an empty string.

Exception = HttpException.InnerException

Returns an Exception object containing the inner exception of the HttpException object.

Parameter

Exception

An Exception instance that will be populated by the property.

Example

The code example creates two exceptions, the second of which is created with an overloaded constructor that sets the InnerException property to the first exception. The code throws the second exception, which is caught by the Catch statement. The Catch block then displays the error messages of both the outer and inner exceptions:

Sub Page_Load( )
   Try
      Dim myHttpEx As _
         New HttpException("This is a nested exception")
      Throw New HttpException("Threw an exception from Page_Load", _
         myHttpEx)
   Catch HttpEx As HttpException
      Dim InnerHttpEx As HttpException
      InnerHttpEx = CType(HttpEx.InnerException, HttpException)
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Inner Exception Message: " & _
         InnerHttpEx.Message & "<br/>"
   End Try
End Sub

Notes

The InnerException property allows exceptions to be nested, which can allow developers to track down the root cause of an exception, even when multiple exceptions are thrown. Because the InnerException property is inherited from the Exception class, other types of exceptions can be nested within an HttpException, and HttpExceptions can be nested within other exception types. The InnerException property can only be set manually through one of the overloaded constructors of the HttpException class.

string = HttpException.Message

Returns a string representing the error message associated with the exception. The error message is the human-readable text description of the error.

Parameter

string

A string that will receive the error message value from the property.

Example

The code example creates and throws an exception, passing the desired error message into the HttpException constructor, and then displays the Message property of the exception as the Text property of an ASP.NET Label control:

Sub Page_Load( )
   Try
      Throw New HttpException("Threw an error from Page_Load")
   Catch HttpEx As HttpException
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
   End Try
End Sub

Notes

The ease with which the Message property can be accessed makes it tempting to simply display this property when an error occurs. A better approach to error handling, however, is to log this information either in the NT Event Log or in your own private application log and handle the error to the user transparently. This provides you with better information to troubleshoot your applications and gives your users a more satisfying (and less frustrating) experience.

string = HttpException.Source
HttpException.Source = string

Sets or returns a string representing the source of the exception. For custom exceptions that you create and throw, this code may be set to the name of the method and/or class from which the exception is thrown.

Parameter

string

A string that will receive the value from the property.

Example

The code example causes an exception by attempting to set a Session value on a page for which the enableSessionState attribute of the @ Page directive has been set to False. The example code then displays the resulting error message and source:

<%@ Page Language="vb" EnableSessionState="false" %>
  
...
  
Sub Page_Load( )
   Try
      Session("foo") = "Foo"
   Catch HttpEx As HttpException
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Source: " & HttpEx.Source & "<br/>"
   End Try
End Sub

Notes

In the example, the Source property returns the value System.Web as the source of the Exception, which is not very specific. When creating and throwing your own custom exceptions, be as specific as possible with error messages and source descriptions. Just remember that providing specific information about an exception you're throwing is no substitute for handling the exception condition within your code instead of throwing an exception. If you have sufficient information about what went wrong to correct the problem, doing so is almost always preferable to throwing an exception that will interrupt the flow of the application from your users' standpoint.

string = HttpException.StackTrace

Returns a string containing a list of the methods in the current call stack in which the exception occurred. The method in which the exception occurred is listed first, followed by any additional methods in the call stack (methods that called the method in which the exception occurred), up to the point at which the exception was handled.

Parameter

string

A string that will receive the stack trace value from the property.

Example

In the code example, the Page_Load event handler calls the ThrowMeAnException method, which throws an HttpException. The exception handler in Page_Load then displays the error message and stack trace:

Sub Page_Load( )
   Try
      ThrowMeAnException
   Catch HttpEx As HttpException
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Stack Trace: " & HttpEx.StackTrace & "<br/>"
   End Try
End Sub
Sub ThrowMeAnException( )
   Throw New HttpException("Threw an error from ThrowMeAnException")
End Sub

Notes

The stack trace for the example first lists the ThrowMeAnException method, including the local path to the .aspx file containing the method and the line number at which the exception was thrown, and then lists the Page_Load method, including the path and line number where the exception originated.

MethodBase = HttpException.TargetSite

Returns a MethodBase instance (the MethodBase class resides in the System.Reflection namespace) representing the method from which the exception was thrown. You can query the properties of MethodBase, such as the Name property, which returns the name of the method. You can also call ToString on the instance to return information about the method in a usable format.

Parameter

MethodBase

An instance of the MethodBase class representing the method from which the exception was thrown.

Example

The code example causes an exception by attempting to set a Session value on a page for which the EnableSessionState attribute of the @ Page directive has been set to False. The example code then displays the resulting error message and uses the Name property of the MethodBase instance returned by the TargetSite property to display the name of the method from which the exception was thrown:

<%@ Page Language="vb" EnableSessionState="false" %>
  
...
  
Sub Page_Load( )
   Try
      Session("foo") = "Foo"
   Catch HttpEx As HttpException
      Message.Text = "ERROR:<br/>"
      Message.Text &= "Message: " & HttpEx.Message & "<br/>"
      Message.Text &= "Target Site: " & HttpEx.TargetSite.Name & "<br/>"
   End Try
End Sub

Notes

In the example, we access the Name property of the MethodBase instance directly, without creating a separate local variable of type MethodBase. This direct access saves us the trouble of either adding an @ Import statement to import the System.Reflection namespace or explicitly declaring the local variable using syntax such as:

Dim myMethodBase As System.Reflection.MethodBase
myMethodBase = HttpEx.TargetSite

Accessing the Name property of MethodBase directly reduces the amount of code we need to write, but it does so at the expense of being less explicit about what we are actually doing. You should always keep such tradeoffs in mind when writing your code. Writing less code usually seems like a good idea, but if someone other than the original programmer needs to maintain the code, using such shortcuts can make it more difficult for the maintainer to understand what's going on in the code.