Erreur avec fin d’exécution

Cette rubrique décrit la méthode utilisée pour signaler les erreurs de fin. Il explique également comment appeler la méthode à partir de l’applet de commande et décrit les exceptions qui peuvent être retournées par le runtime Windows PowerShell lorsque la méthode est appelée.

Lorsqu’une erreur de fin se produit, l’applet de commande doit signaler l’erreur en appelant la méthode System.Management.Automation.Cmdlet.ThrowTerminatingError*. Cette méthode permet à l’applet de commande d’envoyer un enregistrement d’erreur qui décrit la condition qui a provoqué l’erreur de fin. Pour plus d’informations sur les enregistrements d’erreurs, consultez enregistrements d’erreurs Windows PowerShell.

Lorsque la méthode System.Management.Automation.Cmdlet.ThrowTerminatingError* est appelée, le runtime Windows PowerShell arrête définitivement l’exécution du pipeline et lève une exception System.Management.Automation.PipelineStoppedException. Toutes les tentatives suivantes d’appel System.Management.Automation.Cmdlet.WriteObject, System.Management.Automation.Cmdlet.WriteError, ou plusieurs autres API entraînent la levée d’une exception System.Management.Automation.PipelineStoppedException.

La System.Management.Automation.PipelineStoppedException exception peut également se produire si une autre applet de commande du pipeline signale une erreur de fin, si l’utilisateur a demandé d’arrêter le pipeline ou si le pipeline a été arrêté avant l’achèvement pour une raison quelconque. L’applet de commande n’a pas besoin d’intercepter la System.Management.Automation.PipelineStoppedException exception, sauf si elle doit nettoyer les ressources ouvertes ou son état interne.

Les applets de commande peuvent écrire n’importe quel nombre d’objets de sortie ou d’erreurs sans fin avant de signaler une erreur de fin. Toutefois, l’erreur de fin arrête définitivement le pipeline et aucune autre sortie, erreurs de fin ou erreurs de fin peut être signalée.

Les applets de commande peuvent appeler System.Management.Automation.Cmdlet.ThrowTerminatingError* uniquement à partir du thread qui a appelé le System.Management.Automation.Cmdlet.BeginProcessing, System.Management.Automation.Cmdlet.ProcessRecordou System.Management.Automation.Cmdlet.EndProcessing méthode de traitement d’entrée. N’essayez pas d’appeler System.Management.Automation.Cmdlet.ThrowTerminatingError* ou System.Management.Automation.Cmdlet.WriteError à partir d’un autre thread. Au lieu de cela, les erreurs doivent être renvoyées au thread principal.

Il est possible qu’une applet de commande lève une exception dans son implémentation de l'System.Management.Automation.Cmdlet.BeginProcessing, System.Management.Automation.Cmdlet.ProcessRecordou Méthode System.Management.Automation.Cmdlet.EndProcessing. Toute exception levée à partir de ces méthodes (à l’exception de quelques conditions d’erreur graves qui arrêtent l’hôte Windows PowerShell) est interprétée comme une erreur de fin qui arrête le pipeline, mais pas Windows PowerShell dans son ensemble. (Cela s’applique uniquement au thread d’applet de commande principal. Exceptions non interceptées dans les threads générés par l’applet de commande, en général, arrêter l’hôte Windows PowerShell.) Nous vous recommandons d’utiliser System.Management.Automation.Cmdlet.ThrowTerminatingError* plutôt que de lever une exception, car l’enregistrement d’erreur fournit des informations supplémentaires sur la condition d’erreur, qui est utile à l’utilisateur final. Les applets de commande doivent respecter les instructions de code managé pour intercepter et gérer toutes les exceptions (catch (Exception e)). Convertissez uniquement les exceptions des types connus et attendus en enregistrements d’erreurs.

Voir aussi

System.Management.Automation.Cmdlet.BeginProcessing

System.Management.Automation.Cmdlet.EndProcessing

System.Management.Automation.Cmdlet.ProcessRecord

System.Management.Automation.PipelineStoppedException

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.Cmdlet.WriteError

enregistrements d’erreurs Windows PowerShell

écriture d’une applet de commande Windows PowerShell