Share via

  • Article

Procédure : programmer une boîte de message d'exception

Vous pouvez utiliser la boîte de message d'exception dans vos applications pour fournir un contrôle nettement supérieur sur les messages que celui fourni par la classe MessageBox. Pour plus d'informations, consultez Programmation de boîte de message d'exception. Pour plus d'informations sur la façon d'obtenir et de déployer le fichier .dll de boîte de message d'exception, consultez Déploiement d'une application de boîte de message d'exception.

Procédure

Pour gérer une exception en utilisant la boîte de message d'exception

  1. Ajoutez une référence dans votre projet de code managé à l'assembly Microsoft.ExceptionMessageBox.dll.

  2. (Facultatif) Ajoutez une directive using (C#) ou Imports (Microsoft Visual Basic .NET) pour utiliser l'espace de noms Microsoft.SqlServer.MessageBox.

  3. Créez un bloc try-catch pour gérer l'exception anticipée.

  4. Au sein du bloc catch, créez une instance de la classe ExceptionMessageBox. Passez l'objet Exception géré par le bloc try-catch.

  5. (Facultatif) Définissez une ou plusieurs des propriétés suivantes sur ExceptionMessageBox :

  6. Appelez la méthode Show. Passez la fenêtre parente à laquelle la boîte de message d'exception appartient.

  7. (Facultatif) Notez la valeur de l'énumération DialogResult retournée si vous devez déterminer sur quel bouton l'utilisateur a cliqué.

Pour afficher la boîte de message d'exception sans exception

  1. Ajoutez une référence dans votre projet de code managé à l'assembly Microsoft.ExceptionMessageBox.dll.

  2. (Facultatif) Ajoutez une directive using (C#) ou Imports (Visual Basic .NET) pour utiliser l'espace de noms Microsoft.SqlServer.MessageBox.

  3. Créez une instance de la classe ExceptionMessageBox. Passez le texte du message comme une valeur String.

  4. (Facultatif) Définissez une ou plusieurs des propriétés suivantes sur ExceptionMessageBox :

  5. Appelez la méthode Show. Passez la fenêtre parente à laquelle la boîte de message d'exception appartient.

  6. (Facultatif) Notez la valeur de l'énumération DialogResult retournée si vous devez déterminer sur quel bouton l'utilisateur a cliqué.

Pour afficher la boîte de message d'exception avec des boutons personnalisés

  1. Ajoutez une référence dans votre projet de code managé à l'assembly Microsoft.ExceptionMessageBox.dll.

  2. (Facultatif) Ajoutez une directive using (C#) ou Imports (Visual Basic .NET) pour utiliser l'espace de noms Microsoft.SqlServer.MessageBox.

  3. Créez une instance de la classe ExceptionMessageBox en appliquant l'une des deux méthodes suivantes :

    • Passez l'objet Exception géré par un bloc try-catch.

    • Passez le texte du message comme une valeur String.

  4. Définissez l'une des valeurs suivantes pour Buttons :

    • AbortRetryIgnore - affiche les boutons Abandonner, Réessayer et Ignorer.

    • Custom - affiche les boutons personnalisés.

    • OK - affiche le bouton OK.

    • OKCancel - affiche les boutons OK et Annuler.

    • RetryCancel - affiche les boutons Réessayer et Annuler.

    • YesNo - affiche les boutons Oui et Non.

    • YesNoCancel - affiche les boutons Oui, Non et Annuler.

  5. (Facultatif) Si vous utilisez des boutons personnalisés, appelez l'une des surcharges de la méthode SetButtonText pour spécifier le texte de cinq boutons personnalisés au plus.

  6. Appelez la méthode Show. Passez la fenêtre parente à laquelle la boîte de message d'exception appartient.

  7. (Facultatif) Notez la valeur de l'énumération DialogResult retournée si vous devez déterminer sur quel bouton l'utilisateur a cliqué. Si vous utilisez des boutons personnalisés, notez la valeur de ExceptionMessageBoxDialogResult pour la propriété CustomDialogResult pour déterminer sur lequel des boutons personnalisés l'utilisateur a cliqué.

Pour permettre aux utilisateurs de décider d'afficher ou non la boîte de message d'exception

  1. Ajoutez une référence dans votre projet de code managé à l'assembly Microsoft.ExceptionMessageBox.dll.

  2. (Facultatif) Ajoutez une directive using (C#) ou Imports (Visual Basic .NET) pour utiliser l'espace de noms Microsoft.SqlServer.MessageBox.

  3. Créez une instance de la classe ExceptionMessageBox en appliquant l'une des deux méthodes suivantes :

    • Passez l'objet Exception géré par un bloc try-catch.

    • Passez le texte du message comme une valeur String.

  4. Attribuez à la propriété ShowCheckbox()()()() la valeur true.

  5. (Facultatif) Spécifiez le texte qui demande à l'utilisateur de décider d'afficher encore ou non la boîte de message d'exception pour CheckboxText()()()(). Le texte par défaut est "Ne plus afficher ce message".

  6. Si vous devez conserver la décision de l'utilisateur uniquement pour la durée de l'exécution de l'application, définissez la valeur de IsCheckboxChecked()()()() sur une variable Boolean globale. Évaluez cette valeur avant de créer une instance de la boîte de message d'exception.

  7. Si vous devez stocker définitivement la décision d'un utilisateur, procédez comme suit :

    1. Appelez la méthode CreateSubKey(String) pour ouvrir une clé de Registre personnalisée que votre application utilise et définissez CheckboxRegistryKey()()()() sur l'objet RegistryKey retourné.

    2. Attribuez à CheckboxRegistryValue()()()() le nom de la valeur de Registre utilisée.

    3. Attribuez à CheckboxRegistryMeansDoNotShowDialog()()()() la valeur true.

    4. Appelez la méthode Show. La clé de Registre spécifiée est évaluée et la boîte de message d'exception est affichée uniquement si les données stockées dans la clé de Registre sont définies sur 0. Si la boîte de dialogue est affichée et que l'utilisateur active la case à cocher avant de cliquer sur un bouton, les données dans la clé de Registre sont définies sur 1.

Exemple

Cet exemple utilise la boîte de message d'exception avec uniquement le bouton OK pour afficher des informations à partir d'une exception d'application qui inclut l'exception gérée avec d'autres informations spécifiques à l'application.

         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

Cet exemple utilise la boîte de message d'exception avec les boutons Oui et Non parmi lesquels l'utilisateur fera son choix.

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

Cet exemple utilise la boîte de message d'exception avec des boutons personnalisés.

            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

Cet exemple utilise la case à cocher pour déterminer s'il faut afficher la boîte de message d'exception.

           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

Cet exemple utilise la case à cocher et une clé du Registre pour déterminer s'il faut afficher la boîte de message d'exception.

            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

Cet exemple utilise la boîte de message d'exception pour afficher des informations supplémentaires utiles lors d'un dépannage ou d'un débogage.

           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