• Artículo

Cómo programar el cuadro de mensajes de excepción

Puede usar el cuadro de mensajes de excepción en sus aplicaciones para proporcionar un control considerablemente mayor sobre la experiencia de mensajería que el que se proporciona con la clase MessageBox. Para obtener más información, vea Programación de cuadros de mensajes de excepción. Para obtener información sobre la forma de obtener e implementar el archivo .dll del cuadro de mensajes de excepción, vea Implementar una aplicación del cuadro de mensaje de excepción.

Procedimiento

Para controlar una excepción mediante el cuadro de mensajes de excepción

  1. Agregue una referencia al ensamblado Microsoft.ExceptionMessageBox.dll en el proyecto de código administrado.

  2. (Opcional) Agregue una directiva using (C#) o Imports (Microsoft Visual Basic .NET) para usar el espacio de nombres Microsoft.SqlServer.MessageBox.

  3. Cree un bloque try-catch para controlar la excepción anticipada.

  4. Dentro del bloque catch, cree una instancia de la clase ExceptionMessageBox. Pase el objeto Exception controlado por el bloque try-catch.

  5. (Opcional) Establezca una o varias de las siguientes propiedades en ExceptionMessageBox:

  6. Llame al método Show. Pase la ventana primaria a la que pertenece el cuadro de mensajes de excepción.

  7. (Opcional) Tenga en cuenta el valor de la enumeración DialogResult devuelta si necesita determinar en qué botón ha hecho clic el usuario.

Para mostrar el cuadro de mensajes de excepción sin una excepción

  1. Agregue una referencia al ensamblado Microsoft.ExceptionMessageBox.dll en el proyecto de código administrado.

  2. (Opcional) Agregue una directiva using (C#) o Imports (Visual Basic .NET) para usar el espacio de nombres Microsoft.SqlServer.MessageBox.

  3. Cree una instancia de la clase ExceptionMessageBox. Pase el texto del mensaje como un valor String.

  4. (Opcional) Establezca una o varias de las siguientes propiedades en ExceptionMessageBox:

  5. Llame al método Show. Pase la ventana primaria a la que pertenece el cuadro de mensajes de excepción.

  6. (Opcional) Tenga en cuenta el valor de la enumeración DialogResult devuelta si necesita determinar en qué botón ha hecho clic el usuario.

Para mostrar el cuadro de mensajes de excepción con botones personalizados

  1. Agregue una referencia al ensamblado Microsoft.ExceptionMessageBox.dll en el proyecto de código administrado.

  2. (Opcional) Agregue una directiva using (C#) o Imports (Visual Basic .NET) para usar el espacio de nombres Microsoft.SqlServer.MessageBox.

  3. Cree una instancia de la clase ExceptionMessageBox de una de estas dos formas:

    • Pase el objeto Exception controlado por un bloque try-catch.

    • Pase el texto del mensaje como un valor String.

  4. Establezca uno de los siguientes valores para Buttons:

    • AbortRetryIgnore: muestra los botones Anular, Reintentar y Omitir.

    • Custom: muestra los botones personalizados.

    • OK: muestra el botón Aceptar.

    • OKCancel: muestra los botones Aceptar y Cancelar.

    • RetryCancel: muestra los botones Reintentar y Cancelar.

    • YesNo: muestra los botones Sí y No.

    • YesNoCancel: muestra los botones Sí, No y Cancelar.

  5. (Opcional) Si usa botones personalizados, llame a una de las sobrecargas del método SetButtonText para especificar el texto para un máximo de cinco botones personalizados.

  6. Llame al método Show. Pase la ventana primaria a la que pertenece el cuadro de mensajes de excepción.

  7. (Opcional) Tenga en cuenta el valor de la enumeración DialogResult devuelta si necesita determinar en qué botón ha hecho clic el usuario. Si usa botones personalizados, tenga en cuenta el valor de ExceptionMessageBoxDialogResult para que la propiedad CustomDialogResult determine en cuál de los botones personalizados ha hecho clic el usuario.

Para permitir que los usuarios decidan si desean mostrar el cuadro de mensajes de excepción

  1. Agregue una referencia al ensamblado Microsoft.ExceptionMessageBox.dll en su proyecto de código administrado.

  2. (Opcional) Agregue una directiva using (C#) o Imports (Visual Basic .NET) para usar el espacio de nombres Microsoft.SqlServer.MessageBox.

  3. Cree una instancia de la clase ExceptionMessageBox de una de estas dos formas:

    • Pase el objeto Exception controlado por un bloque try-catch.

    • Pase el texto del mensaje como un valor String.

  4. Establezca la propiedad ShowCheckbox()()()() en true.

  5. (Opcional) Especifique el texto donde se solicita al usuario que decida si desea que se muestre de nuevo el cuadro de mensajes de excepción para CheckboxText()()()(). El texto predeterminado es "No volver a mostrar este mensaje".

  6. Si necesita mantener la decisión del usuario sólo durante la ejecución de la aplicación, establezca el valor de IsCheckboxChecked()()()() en una variable Boolean global. Evalúe este valor antes de crear una instancia del cuadro de mensajes de excepción.

  7. Si necesita almacenar la decisión de un usuario de manera permanente, haga lo siguiente:

    1. Llame al método CreateSubKey(String) para abrir una clave del Registro personalizada utilizada por la aplicación y establezca CheckboxRegistryKey()()()() en el objeto RegistryKey devuelto.

    2. Establezca CheckboxRegistryValue()()()() en el nombre del valor del Registro utilizado.

    3. Establezca CheckboxRegistryMeansDoNotShowDialog()()()() en true.

    4. Llame al método Show. Se evalúa la clave del Registro especificada y sólo se muestra el cuadro de mensajes de excepción si los datos almacenados en la clave del Registro son iguales a 0. Si se muestra el cuadro de diálogo y el usuario activa la casilla antes de hacer clic en un botón, los datos de la clave del Registro se establecen en 1.

Ejemplo

En este ejemplo, el cuadro de mensajes de excepción se usa sólo con el botón Aceptar para mostrar información de una excepción de la aplicación que incluye la excepción controlada junto con información adicional específica de la aplicación.

           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

En este ejemplo se usa el cuadro de mensajes de excepción con los botones Sí y No entre los que debe elegir el usuario.

           // 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

En este ejemplo se usa el cuadro de mensajes de excepción con botones personalizados.

          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

En este ejemplo se usa la casilla para determinar si debe mostrarse el cuadro de mensajes de excepción.

            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

En este ejemplo se usa la casilla y una clave del Registro para determinar si debe mostrarse el cuadro de mensajes de excepción.

           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

En este ejemplo se usa el cuadro de mensajes de excepción para mostrar información adicional que puede resultar de utilidad para la depuración o solución de problemas.

           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