如何：程式例外狀況訊息方塊
您可以在應用程式中使用例外狀況訊息方塊，此訊息方塊對訊息經驗所提供的控制要比 MessageBox 類別所提供的高出許多。如需詳細資訊，請參閱＜例外狀況訊息方塊程式設計＞。如需有關如何取得及部署例外狀況訊息方塊 .dll 的詳細資訊，請參閱＜部署例外狀況訊息方塊應用程式＞。
程序
使用例外狀況訊息方塊處理例外狀況
在 Managed 程式碼專案中加入 Microsoft.ExceptionMessageBox.dll 組件的參考。
(選擇性) 加入 using (C#) 或 Imports (Microsoft Visual Basic .NET) 指示詞，以使用 Microsoft.SqlServer.MessageBox 命名空間。
建立 try-catch 區塊來處理預期的例外狀況。
在 catch 區塊內建立 ExceptionMessageBox 類別的執行個體。傳遞由 try-catch 區塊所處理的 Exception 物件。
(選擇性) 在 ExceptionMessageBox 上設定下列其中一個或多個屬性：
Buttons - ExceptionMessageBoxButtons 列舉，指定要在例外狀況訊息方塊中顯示的按鈕。
DefaultButton - ExceptionMessageBoxDefaultButton 列舉，指定例外狀況訊息方塊的預設按鈕。
Options - ExceptionMessageBoxOptions 列舉，用於控制例外狀況訊息方塊的其他行為。
Symbol - ExceptionMessageBoxSymbol 列舉，指定要在例外狀況訊息方塊中顯示的符號。
呼叫 Show 方法。傳遞例外狀況訊息方塊所屬的父視窗。
(選擇性) 如需判斷使用者所按的按鈕，請注意傳回的 DialogResult 列舉值。
顯示沒有例外狀況的例外狀況訊息方塊
在 Managed 程式碼專案中加入 Microsoft.ExceptionMessageBox.dll 組件的參考。
(選擇性) 加入 using (C#) 或 Imports (Visual Basic .NET) 指示詞，以使用 Microsoft.SqlServer.MessageBox 命名空間。
建立 ExceptionMessageBox 類別的執行個體。將訊息文字當做 String 値傳遞。
(選擇性) 在 ExceptionMessageBox 上設定下列其中一個或多個屬性：
Buttons - ExceptionMessageBoxButtons 列舉，指定要在例外狀況訊息方塊中顯示的按鈕。
Caption - 例外狀況訊息方塊的對話方塊標題。
DefaultButton - ExceptionMessageBoxDefaultButton 列舉，為例外狀況訊息方塊的對話方塊指定預設按鈕。
Options - ExceptionMessageBoxOptions 列舉，用於控制例外狀況訊息方塊的其他行為。
Symbol - ExceptionMessageBoxSymbol 列舉，指定要在例外狀況訊息方塊中顯示的符號。
呼叫 Show 方法。傳遞例外狀況訊息方塊所屬的父視窗。
(選擇性) 如需判斷使用者所按的按鈕，請注意傳回的 DialogResult 列舉值。
顯示具有自訂按鈕的例外狀況訊息方塊
在 Managed 程式碼專案中加入 Microsoft.ExceptionMessageBox.dll 組件的參考。
(選擇性) 加入 using (C#) 或 Imports (Visual Basic .NET) 指示詞，以使用 Microsoft.SqlServer.MessageBox 命名空間。
以下列兩種方式中的一種來建立 ExceptionMessageBox 類別的執行個體：
針對 Buttons 設定下列其中一個値：
AbortRetryIgnore - 顯示 [中止]、[重試] 和 [忽略] 按紐。
Custom - 顯示自訂按鈕。
OK - 顯示 [確定] 按紐。
OKCancel - 顯示 [確定] 和 [取消] 按鈕。
RetryCancel - 顯示 [重試] 和 [取消] 按鈕。
YesNo - 顯示 [是] 和 [否] 按鈕。
YesNoCancel - 顯示 [是]、[否] 和 [取消] 按鈕。
(選擇性) 如果您使用自訂按鈕，請呼叫 SetButtonText 方法的其中一個多載來指定最多五個自訂按鈕的文字。
呼叫 Show 方法。傳遞例外狀況訊息方塊所屬的父視窗。
(選擇性) 如需判斷使用者所按的按鈕，請注意傳回的 DialogResult 列舉值。如果使用自訂按鈕，請注意 CustomDialogResult 屬性的 ExceptionMessageBoxDialogResult，以判斷使用者所按的自訂按鈕。
讓使用者決定是否顯示例外狀況訊息方塊
在 Managed 程式碼專案中加入 Microsoft.ExceptionMessageBox.dll 組件的參考。
(選擇性) 加入 using (C#) 或 Imports (Visual Basic .NET) 指示詞，以使用 Microsoft.SqlServer.MessageBox 命名空間。
以下列兩種方式中的一種來建立 ExceptionMessageBox 類別的執行個體：
將 ShowCheckbox()()()() 屬性設為 true。
(選擇性) 指定文字以要求使用者決定是否針對 CheckboxText()()()() 再次顯示例外狀況訊息方塊。預設的文字為「不要再顯示此訊息」。
如果只需在應用程式的執行期間保留使用者的決定，請將 IsCheckboxChecked()()()() 的値設定為全域的 Boolean 變數。在建立例外狀況訊息方塊的執行個體之前，請先評估此値。
如果需要永久儲存使用者的決定，請進行下列步驟：
呼叫 CreateSubKey(String) 方法來開啟應用程式所使用的自訂登錄機碼，然後將 CheckboxRegistryKey()()()() 設定為傳回的 RegistryKey 物件。
將 CheckboxRegistryValue()()()() 設定為所使用之登錄值的名稱。
將 CheckboxRegistryMeansDoNotShowDialog()()()() 設定為 true。
呼叫 Show 方法。系統會評估指定的登錄機碼，只有當登錄機碼所儲存的資料為 0 時，才會顯示例外狀況訊息方塊。如果對話方塊顯示，而且使用者在按按鈕之前先選取了這個核取方塊，則登錄機碼中的資料會設為 1。
範例
此範例所使用的例外狀況訊息方塊只具有 [確定] 按鈕，可顯示應用程式例外狀況的資訊，這些資訊包含處理的例外狀況以及其他的應用程式特定資訊。
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
此範例所使用的例外狀況訊息方塊具有 [是] 和 [否] 按鈕，使用者可從中進行選擇。
// 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
此範例所使用的例外狀況訊息方塊具有自訂按鈕。
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
此範例使用核取方塊來決定是否顯示例外狀況訊息方塊。
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
此範例使用核取方塊和登錄機碼來決定是否顯示例外狀況訊息方塊。
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
此範例使用例外狀況訊息方塊來顯示額外的資訊，這些資訊在進行疑難排解或偵錯時很有用。
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