SyndicationThe ExceptionMessageBox
Ever seen this in your application?
Yes? Then this article is for you. If not, you might know what this entry’s going to cover, but perhaps you’ll learn something new.
In tools I’ve been building, I’ve always been dissatisfied with this sort of “error reporting” (outside of logging, of course), but none of us have had the time to build something really spectacular to handle exceptions. And I have to say–thank goodness we didn’t! Yesterday I read about the ExceptionMessageBox class, and this is the sort of thing I’ve been waiting for! (Except it’s been out for well over a year…but that’s another story).
Since pictures speak better than words, the same exception from the first image is thrown again and is handled with the ExceptionMessageBox under default settings:
Much cleaner, huh? Not only does it give you the original exception, but it gives you all of the inner exception detail as well. When you click on the “Show Technical Details” icon in the toolbar (the button on the right) you’ll see a much appreciated stack trace for each of the exceptions in your chain.
All of this is accomplished with two lines of code:
/// <summary>
/// Handles and logs the specified <see cref=”Exception”/>.
/// </summary>
/// <param name=”exception”>The <see cref=”Exception”/> to handle.</param>
private static void HandleException(Exception exception)
{
ExceptionMessageBox mbox = new ExceptionMessageBox(exception);
mbox.Show(null);
}
Very simple, indeed. The ExceptionMessageBox class is in the Microsoft.SqlServer.MessageBox namespace in the Microsoft.ExceptionMessageBox assembly. That assembly is available for download on this page. (Search for “Exception Message Box.”)
In addition, the ExceptionMessageBox supports a fair number of properties that should be touched on. We’ll cover the highlights here:
Properties
- Beep (Boolean) - Specifies whether the ExceptionMessageBox beeps when it is launched (similar to a normal MessageBox).
- Buttons (ExceptionMessageBoxButtons) - Specifies the type of buttons used by the ExceptionMessageBox. You can also use Custom buttons, a nice touch on top of the original MessageBoxButtons enumeration.
- Caption (String) - The caption/title of the ExceptionMessageBox form.
- CustomDialogResult (ExceptionMessageBoxDialogResult) - Specifies the button that was clicked when using custom buttons.
- CustomSymbol (Bitmap) - Specifies a custom image to display instead of the normal Asterisk, Error, Warning, Information, etc.
- DefaultDialogResult (DialogResult) - Specifies the result of user action on the dialog when not using custom buttons.
- IsCheckBoxChecked (Boolean) - Specifies whether a check box for “Do not show this dialog again” was checked.
- Message (Exception) - The original exception passed into the ExceptionMessageBox constructor.
- MessageLevelDefault (Int32) - Specifies the maximum number of exceptions shown in the dialog. For example, if an exception is thrown that has two inner exceptions, and the MessageLevelDefault property is set to 2, then only the top-level exception and the first inner exception will be shown in the dialog.
- Options (ExceptionMessageBoxOptions) - Enables various options like right-to-left reading or right alignment.
- ShowCheckBox (Boolean) - Specifies whether to show the checkbox which enables developers to hook into users’ preferences on whether they want to show the dialog again.
- ShowToolBar (Boolean) - Specifies whether to show the toolbar (which allows copying text from the message and showing technical details).
- Symbol (ExceptionMessageBoxSymbol) - The symbol to show in the message box, like Asterisk, Error, Warning, and so on.
- Text (String) - If the message box is being used for custom text instead of an exception, then this property will be populated with that text.
- UseOwnerFont (String) - If you want to keep a consistent look across your application, you can tell the ExceptionMessageBox to use its owner window’s font instead of the default.
Methods
- SetButtonText - There are a couple of overloads for this method. It’s used to set the text of one to five buttons on the dialog. This only applies if the Buttons property is ExceptionMessageBoxButtons.Custom.
- Show - Where the magic happens. The basic version of this method requires an IWin32Window as an owner window. The nice thing is that you can pass in null. This would be appropriate if the executing code is inside of an event handler for AppDomain.UnhandledException, for example.
Event
- OnCopyToClipboard -This is a pretty interesting event. It’s raised when the user clicks on the copy to clipboard button in the toolbar or presses Ctrl+C. The event supplies a CopyToClipboardEventArgs instance that has two properties: ClipboardText and EventHandled. When the event is raised, the text hasn’t been copied to the clipboard yet. Instead, you get the chance to handle the event separately. If you want to do your own custom processing and not copy the text to the clipboard, then set the EventHandled property to true on the event arguments and the clipboard data will not be changed. I thought this would be useful for doing something extra, like emailing developers with exception information. However, there’s no easy way to change the text on the toolbar button…
So that’s a brief look at the ExceptionMessageBox. One thing I didn’t cover was how to use the multifarious CheckBox-related properties to stop showing the message box to end users. Here are some links that can help you further:
How To: Program The ExceptionMessageBox
Download Page For ExceptionMessageBox (Search for “Exception Message Box”)
Leave a Reply