Section 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:

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.

From Visual Studio 2005 main menu, select File New Project and create a new Windows Application project. Name the project ExceptionMessageBoxProject.
Add a reference to the Microsoft.ExceptionMessageBox.dll assembly. You might have to browse for itthe default installation directory is C:\Program Files\Microsoft SQL Server\90\SDK\Assemblies.
Add a using directive for the exception message box namespace to Form1.cs:
```
    using Microsoft.SqlServer.MessageBox;
```

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(  );
                }
            }
        }
    }

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

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.

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.

6.3. Exception Message Box

Figure 6-4. Exception message box

Figure 6-5. Advanced information for exception message box

Table 6-11. ExceptionMessageBox instance properties