Section 6.3. Exception Message Box

6.3. Exception Message Box

The exception message box API is installed with the SQL Server 2005 graphical components. It is implemented in the ExceptionMessageBox class in the Microsoft.SqlServer.MessageBox namespace and enhances the standard message box implemented in the System.Windows.Forms.MessageBox class. The ExceptionMessageBox class includes the following enhanced functionality:

• You can display up to five custom buttons.

• You can display custom text and symbols in the message box.

• The user can copy all information from the message box to the clipboard.

• You can display underlying error information in a hierarchical tree view, which the user can navigate.

• The user can decide whether the message should be displayed for subsequent occurrences of the same exception.

• The user can access online help for the exception by using a help link associated with the exception.

The following example shows how to use the exception message box within a .NET application. The example executes a RAISERROR T-SQL statement as the source of the error.

1. From Visual Studio 2005 main menu, select File New Project and create a new Windows Application project. Name the project ExceptionMessageBoxProject.

2. Add a using directive for the exception message box namespace to Form1.cs:

        using Microsoft.SqlServer.MessageBox; 

   
   

3. Add a button named raiseExceptionButton to Form1. In the click event handler for the button, add code to raise a SQL server error using the RAISERROR T-SQL statement in a try block and code to display the exception message box in the catch block. The complete code for this example follows:

        using System;     using System.Collections.Generic;     using System.ComponentModel;     using System.Data;     using System.Drawing;     using System.Text;     using System.Windows.Forms;     using Microsoft.SqlServer.MessageBox;     using System.Data.SqlClient;     namespace ExceptionMesageBoxProject     {         public partial class Form1 : Form         {             public Form1(  )             {                 InitializeComponent(  );             }             private void raiseExceptionButton_Click(object sender, EventArgs e)             {                 SqlConnection conn = new SqlConnection("Data Source=(local);" +                     "Integrated Security=SSPI;Initial Catalog=AdventureWorks");                 conn.Open(  );                 SqlCommand cmd = new SqlCommand(                     "RAISEERROR('Test error', 15, 1)", conn);                 try                 {                     cmd.ExecuteNonQuery(  );                 }                 catch (Exception ex)                 {                     // create the exception message box and set some options                     ExceptionMessageBox emb = new ExceptionMessageBox(ex);                     emb.Buttons = ExceptionMessageBoxButtons.Custom;                     emb.SetButtonText("Custom Button 1", "Custom Button 2",                         "Custom Button 3");                     emb.DefaultButton = ExceptionMessageBoxDefaultButton.Button2;                     emb.Symbol = ExceptionMessageBoxSymbol.Question;                     emb.ShowCheckBox = true;                     emb.Show(this);                     // display the button that was clicked                     MessageBox.Show("You clicked " +                         emb.CustomDialogResult.ToString(  ));                 }                 finally                 {                     conn.Close(  );                 }             }         }     } 

   
   

4. Run the example. When you click the button, the exception message box is displayed, as shown in Figure 6-4.

Figure 6-4. Exception message box

The Show( ) method of the ExceptionMessageBox class takes the parent window (type IWin32Window) as its only argument. Passing this as the parent makes the exception message box a child of the active windowthis is usually the desired behavior.

You can specify up to five custom buttons using overloads of the ExceptionMessageBox constructor or using the overloaded SetButtonText( ) methodboth take the button text for up to five custom buttons as arguments. The CustomDialogResult property indicates which custom button was clicked.

This example displays the optional checkbox on the exception message box. The checkbox lets the user control whether the message box is displayed for subsequent occurrences of the same exception.

Clicking the Show Technical Details icon (rightmost icon in the toolbar at the bottom left of the message box) brings up the Advanced Information dialog box, containing a hierarchy of error information that the user can drill down through, as shown in Figure 6-5.

Figure 6-5. Advanced information for exception message box

An ExceptionMessageBox instance has public properties that let you control its appearance and functionality, as described in Table 6-11.

Table 6-11. ExceptionMessageBox instance properties

Property	Description
Beep	Gets or sets whether to play a sound when the message box is displayed.
Buttons	Gets or sets the buttons to display in the message box. A value from the ExceptionMessageBoxButtons enumeration.
Caption	Gets or sets the caption for the exception message box.
CheckBoxRegistryKey	Gets or sets the registry key that specifies the initial checkbox value if the ShowCheckBox property is TRue. This property is used together with the CheckBoxRegistryValue property.
CheckBoxRegistryMeansDoNotShowDialog	Gets or sets whether the registry value indicated by the CheckBoxRegistryKey and CheckBoxRegistryValue properties indicates that the user decided not to view the message.
CheckBoxRegistryValue	Gets or sets the registry value that specifies the initial checkbox value if the ShowCheckBox property is TRue. This property is used together with the CheckBoxRegistryKey property.
CheckBoxText	Gets or sets the text to display for the checkbox on the exception message box when the ShowCheckbox property is true.
CustomDialogResult	Gets the custom message box button that was clicked. This is a value from the ExceptionMessageBoxDialogResult enumeration. None is returned if the Buttons property is not set to ExceptionMessageBoxButtons.Custom.
CustomSymbol	Gets or sets a Bitmap to use as the symbol on the message box.
Data	Gets an IDictionary interface for help link and advanced information details associated with the top-level message.
DefaultButton	Gets or sets the default button in the message box when Buttons is ExceptionMessageBoxButtons.Custom. A value from the ExceptionMessageBoxDefaultButton enumeration.
DefaultDialogResult	Gets or sets the value as a member of the DialogResult enumeration returned by the Show( ) method when the user has specified not to show the dialog box for subsequent occurrences of the same message.
Font	Gets or sets the font used in the message box.
HelpLink	Gets or sets a link to a help file or web page as help as additional help to the top-level message.
InnerException	Gets or sets the inner exception of the message box as an Exception instance.
IsCheckBoxChecked	Gets or sets whether the checkbox on the exception message box is checked when the ShowCheckboxProperty is true.
Message	Gets or sets the exception (as an Exception instance) for the message box.
MessageLevelDefault	Gets or sets the number of message levels to display in the message box.
Options	Gets or sets display options for the message box using values in the ExceptionMessageBoxOptions enumeration.
ShowCheckBox	Gets or sets whether to show the checkbox on the exception message boxthe checkbox lets the user control whether the message box is displayed for subsequent occurrences of the same exception.
ShowToolbar	Gets or sets whether to display the toolbar with the help, copy, and show advanced information buttons.
Symbol	Gets or sets the symbol to display in the message box using a value from the ExceptionMessageBoxSymbol enumeration.
Text	Gets or sets the text to display in the message box.
UseOwnerFont	Gets or sets whether to retrieve and use the font of the parent window as the font for the message box.