• Artigo

Como programar a caixa de mensagem de exceção

Você pode usar a caixa de mensagem de exceção nos aplicativos para proporcionar um controle mais significativo da experiência em mensagens do que o oferecido pela classe MessageBox. Para obter mais informações, consulte Programação da caixa de mensagem de exceção. Para obter mais informações sobre como obter e implantar o .dll da caixa de mensagem de exceção, consulte Implantando um aplicativo de caixa de mensagem de exceção.

Procedimento

Para tratar de uma exceção usando a caixa de mensagem de exceção

  1. Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.

  2. (Opcional) Adicione uma diretiva using (C#) ou Imports (Microsoft Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.

  3. Crie um bloco try-catch para tratar da exceção antecipada.

  4. Dentro do bloco catch, crie uma instância da classe ExceptionMessageBox. Passe o objeto Exception tratado pelo bloco try-catch.

  5. (Opcional) Defina uma ou mais das propriedades de segurança a seguir em ExceptionMessageBox:

  6. Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.

  7. (Opcional) Observe o valor da enumeração DialogResult retornada se precisar determinar em qual botão o usuário clicou.

Para exibir a caixa de mensagem de exceção sem uma exceção

  1. Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.

  2. (Opcional) Adicione uma diretiva using (C#) ou Imports (Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.

  3. Crie uma instância da classe ExceptionMessageBox. Passe o texto da mensagem como um valor String.

  4. (Opcional) Defina uma ou mais das propriedades de segurança a seguir em ExceptionMessageBox:

  5. Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.

  6. (Opcional) Observe o valor da enumeração DialogResult retornada se precisar determinar em qual botão o usuário clicou.

Para exibir a caixa de mensagem de exceção com botões personalizados

  1. Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.

  2. (Opcional) Adicione uma diretiva using (C#) ou Imports (Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.

  3. Crie uma instância da classe ExceptionMessageBox de uma destas duas maneiras:

    • Passe o objeto Exception tratado por um bloco try-catch.

    • Passe o texto da mensagem como um valor String.

  4. Defina um dos valores a seguir para Buttons:

    • AbortRetryIgnore- exibe os botões Anular, Repetir e Ignorar.

    • Custom- exibe botões personalizados.

    • OK- exibe o botão OK.

    • OKCancel- exibe os botões OK e Cancelar.

    • RetryCancel - exibe os botões Repetir e Cancelar.

    • YesNo- exibe os botões Sim e Não.

    • YesNoCancel - exibe os botões Sim, Não e Cancelar.

  5. (Opcional) Se você usar botões personalizados, chame uma das sobrecargas do método SetButtonText para especificar o texto para até cinco botões personalizados.

  6. Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.

  7. (Opcional) Observe o valor da enumeração DialogResult retornada se precisar determinar em qual botão o usuário clicou. Se você usar botões personalizados, observe o valor de ExceptionMessageBoxDialogResult para a propriedade CustomDialogResult para determinar em qual dos botões personalizados o usuário clicou.

Para permitir que os usuários decidam se mostrarão a caixa de mensagem de exceção

  1. Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.

  2. (Opcional) Adicione uma diretiva using (C#) ou Imports para usar o namespace Microsoft.SqlServer.MessageBox.

  3. Crie uma instância da classe ExceptionMessageBox de uma destas duas maneiras:

    • Passe o objeto Exception tratado por um bloco try-catch.

    • Passe o texto da mensagem como um valor String.

  4. Defina a propriedade ShowCheckbox()()()() como true.

  5. (Opcional) Especifique o texto que solicita ao usuário que decida se mostrará a caixa de mensagem de exceção novamente para CheckboxText()()()(). O texto padrão é "Não exibir esta mensagem novamente".

  6. Se precisar manter a decisão do usuário somente durante a execução do aplicativo, defina o valor de IsCheckboxChecked()()()() como uma variável Boolean global. Avalie esse valor antes de criar uma instância da caixa de mensagem de exceção.

  7. Se você precisar armazenar a decisão de um usuário permanentemente, siga este procedimento:

    1. Chame o método CreateSubKey(String) para abrir uma chave do Registro personalizada usada pelo aplicativo e defina CheckboxRegistryKey()()()() como o objeto RegistryKey retornado.

    2. Defina CheckboxRegistryValue()()()() como o nome do valor do Registro que é usado.

    3. Defina CheckboxRegistryMeansDoNotShowDialog()()()() como true.

    4. Chame o método Show. A chave do Registro especificada é avaliada, e a caixa de mensagem de exceção só será exibida se os dados armazenados na chave do Registro forem 0. Se a caixa de diálogo for exibida e o usuário marcar a caixa de seleção antes de clicar em um botão, os dados da chave do Registro serão definidos como 1.

Exemplo

Esse exemplo usa a caixa de mensagem de exceção apenas com o botão OK para exibir as informações de uma exceção de aplicativo que inclui a exceção tratada juntamente com outras informações específicas de aplicativo.

           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

Esse exemplo usa a caixa de mensagem de exceção com os botões Sim e Não escolhidos pelo usuário.

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

Esse exemplo usa a caixa de mensagem de exceção com botões 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

Esse exemplo usa a caixa de seleção para determinar se a caixa de mensagem de exceção será exibida.

            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

Esse exemplo usa a caixa de seleção e uma chave do Registro para determinar se a caixa de mensagem de exceção será exibida.

            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

Esse exemplo usa a caixa de mensagem de exceção para mostrar informações adicionais úteis ao solucionar problemas ou depurar.

         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