次の方法で共有


例外メッセージ ボックスをプログラムする方法

例外メッセージ ボックスをアプリケーションで使用すると、MessageBox クラスを使用した場合よりも高い柔軟性で、メッセージ エクスペリエンスを制御することができます。詳細については、「例外メッセージ ボックスのプログラミング」を参照してください。例外メッセージ ボックス .dll を取得および展開する方法の詳細については、「例外メッセージ ボックス アプリケーションの配置」を参照してください。

手順

例外メッセージ ボックスを使用して例外を処理するには

  1. Microsoft.ExceptionMessageBox.dll アセンブリへの参照をマネージ コード プロジェクトに追加します。

  2. (省略可) using (C#) または Imports (Microsoft Visual Basic .NET) ディレクティブを追加して、Microsoft.SqlServer.MessageBox 名前空間を使用するよう指定します。

  3. 予想される例外を処理する try-catch ブロックを作成します。

  4. catch ブロック内に、ExceptionMessageBox クラスのインスタンスを作成します。try-catch ブロックで処理される Exception オブジェクトを渡します。

  5. (省略可) ExceptionMessageBox に次のプロパティを 1 つ以上設定します。

  6. Show メソッドを呼び出します。例外メッセージ ボックスが属する親ウィンドウを渡します。

  7. (省略可) ユーザーがクリックしたボタンを判断する必要がある場合は、返された DialogResult 列挙値に注意します。

例外なしで例外メッセージ ボックスを表示するには

  1. Microsoft.ExceptionMessageBox.dll アセンブリへの参照をマネージ コード プロジェクトに追加します。

  2. (省略可) using (C#) または Imports (Visual Basic .NET) ディレクティブを追加して、Microsoft.SqlServer.MessageBox 名前空間を使用するよう指定します。

  3. ExceptionMessageBox クラスのインスタンスを作成します。String 値としてメッセージ テキストを渡します。

  4. (省略可) ExceptionMessageBox に次のプロパティを 1 つ以上設定します。

  5. Show メソッドを呼び出します。例外メッセージ ボックスが属する親ウィンドウを渡します。

  6. (省略可) ユーザーがクリックしたボタンを判断する必要がある場合は、返された DialogResult 列挙値に注意します。

カスタマイズされたボタンのある例外メッセージ ボックスを表示するには

  1. Microsoft.ExceptionMessageBox.dll アセンブリへの参照をマネージ コード プロジェクトに追加します。

  2. (省略可) using (C#) または Imports (Visual Basic .NET) ディレクティブを追加して、Microsoft.SqlServer.MessageBox 名前空間を使用するよう指定します。

  3. 次の 2 つのうち、いずれかの方法で ExceptionMessageBox クラスのインスタンスを作成します。

    • try-catch ブロックで処理される Exception オブジェクトを渡します。

    • String 値としてメッセージ テキストを渡します。

  4. Buttons に次のいずれかの値を設定します。

    • AbortRetryIgnore - [中止][再試行]、および [無視] ボタンを表示します。

    • Custom - カスタム ボタンを表示します。

    • OK - [OK] ボタンを表示します。

    • OKCancel - [OK] および [キャンセル] ボタンを表示します。

    • RetryCancel - [再試行] および [キャンセル] ボタンを表示します。

    • YesNo - [はい] および [いいえ] ボタンを表示します。

    • YesNoCancel - [はい][いいえ]、および [キャンセル] ボタンを表示します。

  5. (省略可) カスタム ボタンを使用する場合は、SetButtonText メソッドのオーバーロードの 1 つを呼び出し、最多で 5 つのカスタム ボタンのテキストを指定します。

  6. Show メソッドを呼び出します。例外メッセージ ボックスが属する親ウィンドウを渡します。

  7. (省略可) ユーザーがクリックしたボタンを判断する必要がある場合は、返された DialogResult 列挙値に注意します。カスタム ボタンを使用する場合に、ユーザーがクリックしたボタンを判断するには、CustomDialogResult プロパティの ExceptionMessageBoxDialogResult の値に注意します。

ユーザーが例外メッセージ ボックスを表示するかどうかを決定できるようにするには

  1. Microsoft.ExceptionMessageBox.dll アセンブリへの参照をマネージ コード プロジェクトに追加します。

  2. (省略可) using (C#) または Imports (Visual Basic .NET) ディレクティブを追加して、Microsoft.SqlServer.MessageBox 名前空間を使用するよう指定します。

  3. 次の 2 つのうち、いずれかの方法で ExceptionMessageBox クラスのインスタンスを作成します。

    • try-catch ブロックで処理される Exception オブジェクトを渡します。

    • String 値としてメッセージ テキストを渡します。

  4. ShowCheckbox()()()() プロパティを true に設定します。

  5. (省略可) 表示された例外メッセージ ボックスを再度表示するかどうかを確認するテキストを CheckboxText()()()() に指定します。既定のテキストは、"今後、このメッセージを表示しない" です。

  6. アプリケーションが実行されている間のみユーザーの指定を保持する場合は、IsCheckboxChecked()()()() の値をグローバルな Boolean 変数に設定します。例外メッセージ ボックスのインスタンスを作成する前に、この値を評価します。

  7. ユーザーの指定を永続的に保持する必要がある場合は、次の操作を行います。

    1. CreateSubKey(String) メソッドを呼び出して、アプリケーションが使用するカスタム レジストリ キーを開き、CheckboxRegistryKey()()()() に返された RegistryKey オブジェクトを設定します。

    2. CheckboxRegistryValue()()()() に使用するレジストリの名前を設定します。

    3. CheckboxRegistryMeansDoNotShowDialog()()()() に true を設定します。

    4. Show メソッドを呼び出します。指定したレジストリ キーが評価され、レジストリ キーに格納されているデータが 0 の場合にのみ、例外メッセージ ボックスが表示されます。ダイアログ ボックスが表示され、ユーザーがボタンをクリックする前にチェック ボックスをオンにした場合は、レジストリ キーのデータが 1 に設定されます。

使用例

次の例では、[OK] ボタンしかない例外メッセージ ボックスを使用し、処理された例外とアプリケーション固有の追加情報を含む、アプリケーション例外の情報を表示します。

          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