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
Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.
(Opcional) Adicione uma diretiva using (C#) ou Imports (Microsoft Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.
Crie um bloco try-catch para tratar da exceção antecipada.
Dentro do bloco catch, crie uma instância da classe ExceptionMessageBox. Passe o objeto Exception tratado pelo bloco try-catch.
(Opcional) Defina uma ou mais das propriedades de segurança a seguir em ExceptionMessageBox:
Buttons - enumeração ExceptionMessageBoxButtons que especifica os botões que serão exibidos na caixa de mensagem de exceção.
DefaultButton - enumeração ExceptionMessageBoxDefaultButton que especifica o botão padrão para a caixa de mensagem de exceção.
Options - enumeração ExceptionMessageBoxOptions usada para controlar outros comportamentos da caixa de mensagem de exceção.
Symbol - enumeração ExceptionMessageBoxSymbol que especifica o símbolo que será exibido na caixa de mensagem de exceção.
Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.
(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
Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.
(Opcional) Adicione uma diretiva using (C#) ou Imports (Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.
Crie uma instância da classe ExceptionMessageBox. Passe o texto da mensagem como um valor String.
(Opcional) Defina uma ou mais das propriedades de segurança a seguir em ExceptionMessageBox:
Buttons - enumeração ExceptionMessageBoxButtons que especifica os botões que serão exibidos na caixa de mensagem de exceção.
Caption- legenda da caixa de diálogo da caixa de mensagem de exceção.
DefaultButton - enumeração ExceptionMessageBoxDefaultButton que especifica o botão padrão para a caixa de diálogo da caixa de mensagem de exceção.
Options - enumeração ExceptionMessageBoxOptions usada para controlar outros comportamentos da caixa de mensagem de exceção.
Symbol - enumeração ExceptionMessageBoxSymbol que especifica o símbolo que será exibido na caixa de mensagem de exceção.
Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.
(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
Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.
(Opcional) Adicione uma diretiva using (C#) ou Imports (Visual Basic .NET) para usar o namespace Microsoft.SqlServer.MessageBox.
Crie uma instância da classe ExceptionMessageBox de uma destas duas maneiras:
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.
(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.
Chame o método Show. Passe a janela pai à qual pertence a caixa de mensagem de exceção.
(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
Adicione uma referência de seu projeto de código gerenciado ao assembly Microsoft.ExceptionMessageBox.dll.
(Opcional) Adicione uma diretiva using (C#) ou Imports para usar o namespace Microsoft.SqlServer.MessageBox.
Crie uma instância da classe ExceptionMessageBox de uma destas duas maneiras:
Defina a propriedade ShowCheckbox()()()() como true.
(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".
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.
Se você precisar armazenar a decisão de um usuário permanentemente, siga este procedimento:
Chame o método CreateSubKey(String) para abrir uma chave do Registro personalizada usada pelo aplicativo e defina CheckboxRegistryKey()()()() como o objeto RegistryKey retornado.
Defina CheckboxRegistryValue()()()() como o nome do valor do Registro que é usado.
Defina CheckboxRegistryMeansDoNotShowDialog()()()() como true.
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