ReportException Method (ILog)

In This Topic

Record an unexpected exception to the log and report it to the user if possible.

Syntax

Visual Basic
C#

'Declaration
 
Function ReportException( _
   ByVal exception As Exception, _
   ByVal category As String, _
   ByVal canContinue As Boolean, _
   ByVal waitForResponse As Boolean _
) As DialogResult

DialogResult ReportException( 
   Exception exception,
   string category,
   bool canContinue,
   bool waitForResponse
)

Parameters

exception: An Exception object to record as a log message. This call is ignored if null.
category: The application subsystem or logging category that the message will be associated with.
canContinue: True if the application can continue after this call, false if this is a fatal error and the application can not continue after this call.
waitForResponse: True to wait for the user to respond to the dialog box, false to return immediately. (Only waits if in a Windows application.)

Return Value

DialogResult.Abort: The user has elected to restart the application and it will exit imminently.
DialogResult.OK: The user has elected to continue execution of the application despite the error.

Remarks

This method provides an easy way to record an exception as a separate message which will be attributed to the code location which threw the exception rather than where this method was called from. The category will default to "Exception" if null, and the message will be formatted automatically based on the exception. The severity will be determined by the canContinue parameter: Critical for fatal errors (canContinue is false), Error for non-fatal errors (canContinue is true).

This method is intended for use with top-level exception catching for errors not anticipated in a specific operation, when the user should be alerted because the error impacts their work flow. For unanticipated errors which do not disrupt a user activity, see the RecordException method.

Only Windows applications can report to the user. If this method is used within another type of application, such as Services, console applications, and web applications, it will only record the exception (as with the RecordException method).

For localized exception catching (e.g. anticipating exceptions when opening a file) we recommend logging an appropriate, specific log message with the exception attached. (See Error, and Write and other such methods; the message need not be of Error severity.)

Example

Shows an example of both the record and report exception commands. Only one needs to be used for any single exception.

//this option records the exception but does not display any user interface.  
Log.RecordException(ex, "Exceptions", true);
 
//this option records the exception and displays a user interface, optionally waiting for the user 
//to decide to continue or exit before returning.
Log.ReportException(ex, "Exceptions", true, true);

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

ILog Interface
ILog Members

Send Feedback