Vorgehensweise: Programmieren eines Ausnahmemeldungsfelds

Mit dem Ausnahmemeldungsfeld können Sie in Ihren Anwendungen das Verhalten von Meldungen erheblich besser bestimmen als mit der MessageBox-Klasse. Weitere Informationen finden Sie unter Programmierung eines Ausnahmemeldungsfelds. Weitere Informationen zum Abrufen und Bereitstellen der DLL-Assembly für das Ausnahmemeldungsfeld finden Sie unter Bereitstellen einer Ausnahmemeldungsfeld-Anwendung.

Vorgehensweise

So behandeln Sie eine Ausnahme mit dem Ausnahmemeldungsfeld

  1. Fügen Sie einen Verweis auf die Microsoft.ExceptionMessageBox.dll-Assembly in das Projekt mit verwaltetem Code ein.

  2. (Optional) Fügen Sie eine using-Direktive (C#) oder Imports-Direktive (Microsoft Visual Basic .NET) hinzu, um den Microsoft.SqlServer.MessageBox-Namespace zu verwenden.

  3. Erstellen Sie einen try/catch-Block, um die erwartete Ausnahme zu behandeln.

  4. Erstellen Sie innerhalb des catch-Blocks eine Instanz der ExceptionMessageBox-Klasse. Übergeben Sie das vom try-catch-Block behandelte Exception-Objekt.

  5. (Optional) Legen Sie eine oder mehrere der folgenden Eigenschaften für ExceptionMessageBox fest:

  6. Rufen Sie die Show-Methode auf. Übergeben Sie das übergeordnete Fenster, zu dem das Ausnahmemeldungsfeld gehört.

  7. (Optional) Notieren Sie den Wert der zurückgegebenen DialogResult-Enumeration, wenn Sie bestimmen müssen, auf welche Schaltfläche der Benutzer geklickt hat.

So zeigen Sie das Ausnahmemeldungsfeld ohne Ausnahme an

  1. Fügen Sie einen Verweis auf die Microsoft.ExceptionMessageBox.dll-Assembly in das Projekt mit verwaltetem Code ein.

  2. (Optional) Fügen Sie eine using-Direktive (C#) oder eine Imports-Direktive (Visual Basic .NET) hinzu, um den Microsoft.SqlServer.MessageBox-Namespace zu verwenden.

  3. Erstellen sie eine Instanz der ExceptionMessageBox-Klasse. Übergeben Sie den Meldungstext als String-Wert.

  4. (Optional) Legen Sie eine oder mehrere der folgenden Eigenschaften für ExceptionMessageBox fest:

  5. Rufen Sie die Show-Methode auf. Übergeben Sie das übergeordnete Fenster, zu dem das Ausnahmemeldungsfeld gehört.

  6. (Optional) Notieren Sie den Wert der zurückgegebenen DialogResult-Enumeration, wenn Sie bestimmen müssen, auf welche Schaltfläche der Benutzer geklickt hat.

So zeigen Sie das Ausnahmemeldungsfeld mit benutzerdefinierten Schaltflächen an

  1. Fügen Sie einen Verweis auf die Microsoft.ExceptionMessageBox.dll-Assembly in das Projekt mit verwaltetem Code ein.

  2. (Optional) Fügen Sie eine using-Direktive (C#) oder eine Imports-Direktive (Visual Basic .NET) hinzu, um den Microsoft.SqlServer.MessageBox-Namespace zu verwenden.

  3. Erstellen Sie eine Instanz der ExceptionMessageBox-Klasse. Hierzu haben Sie zwei Möglichkeiten:

    • Übergeben Sie das von einem try-catch-Block behandelte Exception-Objekt.

    • Übergeben Sie den Meldungstext als String-Wert.

  4. Legen Sie für Buttons einen der folgenden Werte fest:

    • AbortRetryIgnore - zeigt die Schaltflächen Abbrechen, Wiederholen und Ignorieren an.

    • Custom - zeigt benutzerdefinierte Schaltflächen an.

    • OK - zeigt die Schaltfläche OK an.

    • OKCancel - zeigt die Schaltflächen OK und Abbrechen an.

    • RetryCancel - zeigt die Schaltflächen Wiederholen und Abbrechen an.

    • YesNo - zeigt die Schaltflächen Ja und Nein an.

    • YesNoCancel - zeigt die Schaltflächen Ja, Nein und Abbrechen an.

  5. (Optional) Wenn Sie benutzerdefinierte Schaltflächen verwenden, rufen Sie eine der Überladungen der SetButtonText-Methode auf, um Text für bis zu fünf benutzerdefinierte Schaltflächen anzugeben.

  6. Rufen Sie die Show-Methode auf. Übergeben Sie das übergeordnete Fenster, zu dem das Ausnahmemeldungsfeld gehört.

  7. (Optional) Notieren Sie den Wert der zurückgegebenen DialogResult-Enumeration, wenn Sie bestimmen müssen, auf welche Schaltfläche der Benutzer geklickt hat. Wenn Sie benutzerdefinierte Schaltflächen verwenden, notieren Sie den Wert von ExceptionMessageBoxDialogResult für die CustomDialogResult-Eigenschaft, um zu ermitteln, auf welche benutzerdefinierte Schaltfläche der Benutzer geklickt hat.

So ermöglichen Sie Benutzern die Entscheidung darüber, ob das Ausnahmemeldungsfeld angezeigt werden soll

  1. Fügen Sie einen Verweis auf die Microsoft.ExceptionMessageBox.dll-Assembly in das Projekt mit verwaltetem Code ein.

  2. (Optional) Fügen Sie eine using-Direktive (C#) oder eine Imports-Direktive (Visual Basic .NET) hinzu, um den Microsoft.SqlServer.MessageBox-Namespace zu verwenden.

  3. Erstellen Sie eine Instanz der ExceptionMessageBox-Klasse. Hierzu haben Sie zwei Möglichkeiten:

    • Übergeben Sie das von einem try-catch-Block behandelte Exception-Objekt.

    • Übergeben Sie den Meldungstext als String-Wert.

  4. Legen Sie die ShowCheckbox()()()()-Eigenschaft auf true fest.

  5. (Optional) Geben Sie den Text an, mit dem der Benutzer aufgefordert wird, zu entscheiden, ob das Ausnahmemeldungsfeld für CheckboxText()()()() erneut angezeigt werden soll. Der Standardtext lautet: "Diese Meldung nicht mehr anzeigen."

  6. Wenn die Entscheidung des Benutzers nur für die Dauer der Anwendungsausführung gültig sein soll, legen Sie den Wert von IsCheckboxChecked()()()() auf eine globale Boolean-Variable fest. Werten Sie diesen Wert aus, bevor Sie eine Instanz des Ausnahmemeldungsfelds erstellen.

  7. Wenn Sie die Entscheidung eines Benutzers dauerhaft speichern müssen, gehen Sie wie folgt vor:

    1. Rufen Sie die CreateSubKey(String)-Methode auf, um einen von Ihrer Anwendung verwendeten, benutzerdefinierten Registrierungsschlüssel zu öffnen, und legen Sie CheckboxRegistryKey()()()() auf das zurückgegebene RegistryKey-Objekt fest.

    2. Legen Sie CheckboxRegistryValue()()()() auf den Namen des verwendeten Registrierungswerts fest.

    3. Legen Sie CheckboxRegistryMeansDoNotShowDialog()()()() auf true fest.

    4. Rufen Sie die Show-Methode auf. Der angegebene Registrierungsschlüssel wird ausgewertet, und das Ausnahmemeldungsfeld wird nur angezeigt, wenn die im Registrierungsschlüssel gespeicherten Daten 0 sind. Wenn das Dialogfeld angezeigt wird und der Benutzer das Kontrollkästchen aktiviert, bevor er auf eine Schaltfläche klickt, werden die Daten im Registrierungsschlüssel auf 1 gesetzt.

Beispiel

In diesem Beispiel wird das Ausnahmemeldungsfeld nur mit der Schaltfläche OK verwendet, um Informationen von einer Anwendungsausnahme anzuzeigen, die die behandelte Ausnahme sowie weitere anwendungsspezifische Informationen enthält.

          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

In diesem Beispiel wird das Ausnahmemeldungsfeld mit den Schaltflächen Ja und Nein verwendet, von denen der Benutzer eine auswählen kann.

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

In diesem Beispiel wird das Ausnahmemeldungsfeld mit benutzerdefinierten Schaltflächen verwendet.

          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

In diesem Beispiel wird das Kontrollkästchen verwendet, um zu bestimmen, ob das Ausnahmemeldungsfeld angezeigt werden soll.

            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

In diesem Beispiel werden das Kontrollkästchen und ein Registrierungsschlüssel verwendet, um zu bestimmen, ob das Ausnahmemeldungsfeld angezeigt werden soll.

          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

In diesem Beispiel wird das Ausnahmemeldungsfeld verwendet, um weitere Informationen anzuzeigen, die bei der Problembehandlung oder beim Debuggen hilfreich sein können.

          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