How to: Program Exception Message Box

You can use the exception message box in your applications to provide significantly more control over the messaging experience than is provided by the MessageBox class. For more information, see Exception Message Box Programming. For information about how to obtain and deploy the exception message box .dll, see Deploying an Exception Message Box Application.

Procedure

To handle an exception by using the exception message box

1. Add a reference in your managed code project to the Microsoft.ExceptionMessageBox.dll assembly.

2. (Optional) Add a using (C#) or Imports (Microsoft Visual Basic .NET) directive to use the Microsoft.SqlServer.MessageBox namespace.

3. Create a try-catch block to handle the anticipated exception.

4. Within the catch block, create an instance of the ExceptionMessageBox class. Pass the Exception object handled by the try-catch block.

5. (Optional) Set one or more of the following properties on ExceptionMessageBox:

   • Buttons - ExceptionMessageBoxButtons enumeration that specifies the buttons to display in the exception message box.

   • DefaultButton - ExceptionMessageBoxDefaultButton enumeration that specifies the default button for the exception message box.

   • Options - ExceptionMessageBoxOptions enumeration that you use to control other behaviors of the exception message box.

   • Symbol - ExceptionMessageBoxSymbol enumeration that specifies the symbol to display in the exception message box.

6. Call the Show method. Pass the parent window to which the exception message box belongs.

7. (Optional) Note the value of returned DialogResult enumeration if you need to determine which button the user clicked.

To display the exception message box without an exception

1. Add a reference in your managed code project to the Microsoft.ExceptionMessageBox.dll assembly.

2. (Optional) Add a using (C#) or Imports (Visual Basic .NET) directive to use the Microsoft.SqlServer.MessageBox namespace.

3. Create an instance of the ExceptionMessageBox class. Pass the message text as a String value.

4. (Optional) Set one or more of the following properties on ExceptionMessageBox:

   • Buttons - ExceptionMessageBoxButtons enumeration that specifies the buttons to display in the exception message box.

   • Caption - Dialog box caption of the exception message box.

   • DefaultButton - ExceptionMessageBoxDefaultButton enumeration that specifies the default button for the dialog box of the exception message box.

   • Options - ExceptionMessageBoxOptions enumeration that you use to control other behaviors of the exception message box.

   • Symbol - ExceptionMessageBoxSymbol enumeration that specifies the symbol to display in the exception message box.

5. Call the Show method. Pass the parent window to which the exception message box belongs.

6. (Optional) Note the value of the returned DialogResult enumeration if you need to determine which button the user clicked.

To display the exception message box with customized buttons

1. Add a reference in your managed code project to the Microsoft.ExceptionMessageBox.dll assembly.

2. (Optional) Add a using (C#) or Imports (Visual Basic .NET) directive to use the Microsoft.SqlServer.MessageBox namespace.

3. Create an instance of the ExceptionMessageBox class in one of two ways:

   • Pass the Exception object handled by a try-catch block.

   • Pass the message text as a String value.

4. Set one of the following values for Buttons:

   • AbortRetryIgnore - displays the Abort, Retry, and Ignore buttons.

   • Custom - displays custom buttons.

   • OK - displays the OK button.

   • OKCancel - displays the OK and Cancel buttons.

   • RetryCancel - displays the Retry and Cancel buttons.

   • YesNo - displays Yes and No buttons.

   • YesNoCancel - displays Yes, No, and Cancel buttons.

5. (Optional) If you use custom buttons, call one of the overloads of the SetButtonText method to specify text for up to five custom buttons.

6. Call the Show method. Pass the parent window to which the exception message box belongs.

7. (Optional) Note the value of the returned DialogResult enumeration if you need to determine which button the user clicked. If you use custom buttons, note the value of ExceptionMessageBoxDialogResult for the CustomDialogResult property to determine which of the custom buttons the user clicked.

To allow users to decide whether to show the exception message box

1. Add a reference in your managed code project to the Microsoft.ExceptionMessageBox.dll assembly.

2. (Optional) Add a using (C#) or Imports (Visual Basic .NET) directive to use the Microsoft.SqlServer.MessageBox namespace.

3. Create an instance of the ExceptionMessageBox class in one of two ways:

   • Pass the Exception object handled by a try-catch block.

   • Pass the message text as a String value.

4. Set the ShowCheckbox() property to true.

5. (Optional) Specify the text that asks the user to decide whether to show the exception message box again for CheckboxText(). The default text is "Do not show this message again."

6. If you need to keep the user's decision only for the duration of the application's execution, set the value of IsCheckboxChecked() to a global Boolean variable. Evaluate this value before creating an instance of the exception message box.

7. If you need to store a user's decision permanently, do the following:

   1. Call the CreateSubKey(String) method to open a custom registry key that your application uses, and set CheckboxRegistryKey() to the returned RegistryKey object.

   2. Set CheckboxRegistryValue() to the name of the registry value that is used.

   3. Set CheckboxRegistryMeansDoNotShowDialog() to true.

   4. Call the Show method. The specified registry key is evaluated, and the exception message box is displayed only if the data stored in the registry key is 0. If the dialog box is displayed and the user selects the check box before clicking a button, the data in the registry key is set to 1.

Example

This example uses the exception message box with only the OK button to display information from an application exception that includes the handled exception along with additional application-specific information.

           try
            {
                // Do something that may generate an exception.
                throw new ApplicationException("An error has occured");
            }
            catch (ApplicationException ex)
            {
                // Define a new top-level error message.
                string str = "The action failed.";

                // Add the new top-level message to the handled exception.
                ApplicationException exTop = new ApplicationException(str, ex);
                exTop.Source = this.Text;

                // Show an exception message box with an OK button (the default).
                ExceptionMessageBox box = new ExceptionMessageBox(exTop);
                box.Show(this);
            }

Try
    ' Do something that may generate an exception.
    Throw New ApplicationException("An error has occured")
Catch ex As ApplicationException
    ' Define a new top-level error message.
    Dim str As String = "The action failed."

    ' Add the new top-level message to the handled exception.
    Dim exTop As ApplicationException = New ApplicationException(str, ex)
    exTop.Source = Me.Text

    ' Show an exception message box with an OK button (the default).
    Dim box As ExceptionMessageBox = New ExceptionMessageBox(exTop)
    box.Show(Me)
End Try

This example uses the exception message box with Yes and No buttons from which the user chooses.

          // Define the message and caption to display.
            string str = @"Are you sure you want to delete file 'c:\somefile.txt'?";
            string caption = "Confirm File Deletion";

            // Show the exception message box with Yes and No buttons.
            ExceptionMessageBox box = new ExceptionMessageBox(str,
                caption, ExceptionMessageBoxButtons.YesNo,
                ExceptionMessageBoxSymbol.Question,
                ExceptionMessageBoxDefaultButton.Button2);

            if (DialogResult.Yes == box.Show(this))
            {
                // Delete the file.
            }

' Define the message and caption to display.
Dim str As String = "Are you sure you want to delete file 'c:\somefile.txt'?"
Dim caption As String = "Confirm File Deletion"

' Show the exception message box with Yes and No buttons.
Dim box As ExceptionMessageBox = New ExceptionMessageBox(str, _
 caption, ExceptionMessageBoxButtons.YesNo, _
 ExceptionMessageBoxSymbol.Question, _
 ExceptionMessageBoxDefaultButton.Button2)

If Windows.Forms.DialogResult.Yes = box.Show(Me) Then
    ' Delete the file.
End If

This example uses the exception message box with custom buttons.

           try
            {
                // Do something that may cause an exception.
                throw new ApplicationException("An error has occured");
            }
            catch (ApplicationException ex)
            {
                string str = "Action failed. What do you want to do?";
                ApplicationException exTop = new ApplicationException(str, ex);
                exTop.Source = this.Text;

                // Show the exception message box with three custom buttons.
                ExceptionMessageBox box = new ExceptionMessageBox(exTop);

                // Set the names of the three custom buttons.
                box.SetButtonText("Skip", "Retry", "Stop Processing");

                // Set the Retry button as the default.
                box.DefaultButton = ExceptionMessageBoxDefaultButton.Button2;
                box.Symbol = ExceptionMessageBoxSymbol.Question;
                box.Buttons = ExceptionMessageBoxButtons.Custom;

                box.Show(this);

                // Do something, depending on the button that the user clicks.
                switch (box.CustomDialogResult)
                {
                    case ExceptionMessageBoxDialogResult.Button1:
                        // Skip action
                        break;
                    case ExceptionMessageBoxDialogResult.Button2:
                        // Retry action
                        break;
                    case ExceptionMessageBoxDialogResult.Button3:
                        // Stop processing action
                        break;
                }
            }

Try
    ' Do something that may cause an exception.
    Throw New ApplicationException("An error has occured")
Catch ex As ApplicationException
    Dim str As String = "Action failed. What do you want to do?"
    Dim exTop As ApplicationException = New ApplicationException(str, ex)
    exTop.Source = Me.Text

    ' Show the exception message box with three custom buttons.
    Dim box As ExceptionMessageBox = New ExceptionMessageBox(exTop)

    ' Set the names of the three custom buttons.
    box.SetButtonText("Skip", "Retry", "Stop Processing")

    ' Set the Retry button as the default.
    box.DefaultButton = ExceptionMessageBoxDefaultButton.Button2
    box.Symbol = ExceptionMessageBoxSymbol.Question
    box.Buttons = ExceptionMessageBoxButtons.Custom

    box.Show(Me)

    ' Do something, depending on the button that the user clicks.
    Select Case box.CustomDialogResult
        Case ExceptionMessageBoxDialogResult.Button1
            ' Skip action
        Case ExceptionMessageBoxDialogResult.Button2
            ' Retry action
        Case ExceptionMessageBoxDialogResult.Button3
            ' Stop processing action
    End Select
End Try

This example uses the check box to determine whether to show the exception message box.

            try
            {
                // Do something that may cause an exception.
                throw new ApplicationException("An error has occured.");
            }
            catch (ApplicationException ex)
            {
                string str = "The action failed.";
                ApplicationException exTop = new ApplicationException(str, ex);
                exTop.Source = this.Text;

                // Show a message box if the global variable is true.
                if (alwaysShow)
                {
                    ExceptionMessageBox box = new ExceptionMessageBox(exTop);
                    box.ShowCheckBox = true;
                    box.IsCheckBoxChecked = true;
                    box.CheckBoxText = "Always show this message";
                    box.Show(this);

                    // Set the global variable.
                    alwaysShow = box.IsCheckBoxChecked;
                }
            }

Try
    ' Do something that may cause an exception.
    Throw New ApplicationException("An error has occured.")
Catch ex As ApplicationException
    Dim str As String = "The action failed."
    Dim exTop As ApplicationException = New ApplicationException(str, ex)
    exTop.Source = Me.Text

    ' Show a message box if the global variable is true.
    If alwaysShow Then
        Dim box As ExceptionMessageBox = New ExceptionMessageBox(exTop)
        box.ShowCheckBox = True
        box.IsCheckBoxChecked = True
        box.CheckBoxText = "Always show this message"
        box.Show(Me)

        ' Set the global variable.
        alwaysShow = box.IsCheckBoxChecked
    End If
End Try

This example uses the check box and a registry key to determine whether to show the exception message box.

         try
            {
                // Do something that could generate an exception.
                throw new ApplicationException("An error has occured.");
            }
            catch (ApplicationException ex)
            {
                string str = "The action failed. Do you want to continue?";
                ApplicationException exTop = new ApplicationException(str, ex);
                exTop.Source = this.Text;

                // Show a message box with Yes and No buttons
                ExceptionMessageBox box = new ExceptionMessageBox(exTop,
                    ExceptionMessageBoxButtons.YesNo,
                    ExceptionMessageBoxSymbol.Question,
                    ExceptionMessageBoxDefaultButton.Button2);

                // Enable the check box.
                box.ShowCheckBox = true;

                // Define the registry key to use.
                box.CheckBoxRegistryKey =
                    Microsoft.Win32.Registry.CurrentUser.CreateSubKey(
                    @"Software\TestApp");
                box.CheckBoxRegistryValue = "DontShowActionFailedMessage";
                box.CheckBoxRegistryMeansDoNotShowDialog = true;
                box.DefaultDialogResult = DialogResult.Yes;

                // The message box won�t be displayed if the
                // "DontShowActionFailedMessage" value of the registry key 
                // contains a non-zero value.
                if (box.Show(this) == DialogResult.No)
                {
                    // Do something if the user clicks the No button.
                    this.Close();
                }
            }

Try
    ' Do something that could generate an exception.
    Throw New ApplicationException("An error has occured.")
Catch ex As ApplicationException
    Dim str As String = "The action failed. Do you want to continue?"
    Dim exTop As ApplicationException = New ApplicationException(str, ex)
    exTop.Source = Me.Text

    ' Show a message box with Yes and No buttons
    Dim box As ExceptionMessageBox = New ExceptionMessageBox(exTop, _
     ExceptionMessageBoxButtons.YesNo, _
     ExceptionMessageBoxSymbol.Question, _
     ExceptionMessageBoxDefaultButton.Button2)

    ' Enable the check box.
    box.ShowCheckBox = True

    ' Define the registry key to use.
    box.CheckBoxRegistryKey = _
    Microsoft.Win32.Registry.CurrentUser.CreateSubKey( _
     "Software\TestApp")
    box.CheckBoxRegistryValue = "DontShowActionFailedMessage"
    box.CheckBoxRegistryMeansDoNotShowDialog = True
    box.DefaultDialogResult = Windows.Forms.DialogResult.Yes

    ' The message box won�t be displayed if the
    ' "DontShowActionFailedMessage" value of the registry key 
    ' contains a non-zero value.
    If box.Show(Me) = Windows.Forms.DialogResult.No Then
        ' Do something if the user clicks the No button.
        Me.Close()
    End If
End Try

This example uses the exception message box to show additional information that is helpful when troubleshooting or debugging.

         try
            {
                // Do something that you don't expect to generate an exception.
                throw new ApplicationException("Failed to connect to the server.");
            }
            catch (ApplicationException ex)
            {
                string str = "An unexpected error occurred. Please call Helpdesk.";
                ApplicationException exTop = new ApplicationException(str, ex);
                exTop.Source = this.Text;

                // Information in the Data property of an exception that has a name
                // beginning with "HelpLink.Advanced" is shown when the user
                // clicks the Advanced Information button of the exception message
                // box dialog box.
                exTop.Data.Add("AdvancedInformation.FileName", "application.dll");
                exTop.Data.Add("AdvancedInformation.FilePosition", "line 355");
                exTop.Data.Add("AdvancedInformation.UserContext", "single user mode");

                // Show the exception message box with additional information that 
                // is helpful when a user calls technical support.
                ExceptionMessageBox box = new ExceptionMessageBox(exTop);

                box.Show(this);
            }

Try
    ' Do something that you don't expect to generate an exception.
    Throw New ApplicationException("Failed to connect to the server.")
Catch ex As ApplicationException
    Dim str As String = "An unexpected error occurred. Please call Helpdesk."
    Dim exTop As ApplicationException = New ApplicationException(str, ex)
    exTop.Source = Me.Text

    ' Information in the Data property of an exception that has a name
    ' beginning with "HelpLink.Advanced" is shown when the user
    ' clicks the Advanced Information button of the exception message
    ' box dialog box.
    exTop.Data.Add("AdvancedInformation.FileName", "application.dll")
    exTop.Data.Add("AdvancedInformation.FilePosition", "line 355")
    exTop.Data.Add("AdvancedInformation.UserContext", "single user mode")

    ' Show the exception message box with additional information that 
    ' is helpful when a user calls technical support.
    Dim box As ExceptionMessageBox = New ExceptionMessageBox(exTop)

    box.Show(Me)

End Try