Partager via

Enregistrements d’erreurs Windows PowerShell

Les applets de commande doivent passer un objet System.Management.Automation.ErrorRecord qui identifie la condition d’erreur pour la fin et la non-fin des erreurs.

L’objet System.Management.Automation.ErrorRecord contient les informations suivantes :

  • Exception qui décrit l’erreur. Souvent, il s’agit d’une exception que l’applet de commande a interceptée et convertie en enregistrement d’erreur. Chaque enregistrement d’erreur doit contenir une exception.

Si l’applet de commande n’a pas intercepté d’exception, elle doit créer une exception et choisir la classe d’exception qui décrit le mieux la condition d’erreur. Toutefois, vous n’avez pas besoin de lever l’exception, car elle est accessible via la propriété System.Management.Automation.ErrorRecord.Exception de l’objet System.Management.Automation.ErrorRecord.

  • Identificateur d’erreur qui fournit un indicateur ciblé qui peut être utilisé à des fins de diagnostic et par les scripts Windows PowerShell pour gérer des conditions d’erreur spécifiques avec des gestionnaires d’erreurs spécifiques. Chaque enregistrement d’erreur doit contenir un identificateur d’erreur (voir Identificateur d’erreur).

  • Catégorie d’erreur qui fournit un indicateur général qui peut être utilisé à des fins de diagnostic. Chaque enregistrement d’erreur doit spécifier une catégorie d’erreur (voir Catégorie d’erreur).

  • Message d’erreur de remplacement facultatif et action recommandée (voir Message d’erreur de remplacement).

  • Informations d’appel facultatives sur l’applet de commande qui a levé l’erreur. Ces informations sont spécifiées par Windows PowerShell (voir Message d’appel).

  • Objet cible en cours de traitement lorsque l’erreur s’est produite. Il peut s’agir de l’objet d’entrée ou d’un autre objet que votre applet de commande a traité. Par exemple, pour la commande Remove-Item -Recurse C:\somedirectory, l’erreur peut être une instance d’un objet FileInfo pour « C :\somedirectory\lockedfile ». Les informations relatives à l’objet cible sont facultatives.

Identificateur d’erreur

Lorsque vous créez un enregistrement d’erreur, spécifiez un identificateur qui désigne la condition d’erreur dans votre applet de commande. Windows PowerShell combine l’identificateur ciblé avec le nom de votre applet de commande pour créer un identificateur d’erreur complet. L’identificateur d’erreur complet est accessible via la propriété System.Management.Automation.ErrorRecord.FullyQualifiedErrorId de l’objet System.Management.Automation.ErrorRecord. L’identificateur d’erreur n’est pas disponible par lui-même. Il est disponible uniquement dans le cadre de l’identificateur d’erreur complet.

Utilisez les instructions suivantes pour générer des identificateurs d’erreur lorsque vous créez des enregistrements d’erreur :

  • Effectuez des identificateurs d’erreur spécifiques à une condition d’erreur. Ciblez les identificateurs d’erreur à des fins de diagnostic et pour les scripts qui gèrent des conditions d’erreur spécifiques avec des gestionnaires d’erreurs spécifiques. Un utilisateur doit pouvoir utiliser l’identificateur d’erreur pour identifier l’erreur et sa source. Les identificateurs d’erreur activent également la création de rapports pour des conditions d’erreur spécifiques à partir d’exceptions existantes afin que les nouvelles sous-classes d’exception ne soient pas requises.

  • En général, affectez différents identificateurs d’erreur à différents chemins de code. L’utilisateur final bénéficie d’identificateurs spécifiques. Souvent, chaque chemin de code qui appelle System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTerminatingError* possède son propre identificateur. En règle générale, définissez un nouvel identificateur lorsque vous définissez une nouvelle chaîne de modèle pour le message d’erreur, et vice versa. N’utilisez pas le message d’erreur comme identificateur.

  • Lorsque vous publiez du code à l’aide d’un identificateur d’erreur particulier, vous établissez la sémantique des erreurs avec cet identificateur pour votre cycle de vie complet de support produit. Ne la réutilisez pas dans un contexte qui diffère sémantiquement du contexte d’origine. Si la sémantique de cette erreur change, créez et utilisez un nouvel identificateur.

  • Vous devez généralement utiliser un identificateur d’erreur particulier uniquement pour les exceptions d’un type CLR particulier. Si le type de l’exception ou le type de l’objet cible change, créez et utilisez un nouvel identificateur.

  • Choisissez du texte pour votre identificateur d’erreur qui correspond de manière concise à l’erreur que vous signalez. Utilisez des conventions de nommage et de mise en majuscules .NET Framework standard. N’utilisez pas d’espace blanc ou de ponctuation. Ne localisez pas les identificateurs d’erreur.

  • Ne générez pas dynamiquement d’identificateurs d’erreur de manière non reproductible. Par exemple, n’incorporez pas d’informations d’erreur telles qu’un ID de processus. Les identificateurs d’erreur sont utiles uniquement s’ils correspondent aux identificateurs d’erreur vus par d’autres utilisateurs qui rencontrent la même condition d’erreur.

Catégorie d’erreur

Lorsque vous créez un enregistrement d’erreur, spécifiez la catégorie de l’erreur à l’aide de l’une des constantes définies par l’énumération System.Management.Automation.ErrorCategor y. Windows PowerShell utilise la catégorie d’erreur pour afficher les informations d’erreur lorsque les utilisateurs définissent la variable $ErrorView sur "CategoryView".

Évitez d’utiliser la constante system.Management.Automation.ErrorCategoryNotSpecified. Si vous avez des informations sur l’erreur ou sur l’opération qui a provoqué l’erreur, choisissez la catégorie qui décrit le mieux l’erreur ou l’opération, même si la catégorie n’est pas une correspondance parfaite.

Les informations affichées par Windows PowerShell sont appelées chaîne d’affichage de catégorie et sont générées à partir des propriétés de la classe System.Management.Automation.ErrorCategoryInfo. (Cette classe est accessible via l’erreur System.Management.Automation.ErrorRecord.CategoryInfo propriété.)

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

La liste suivante décrit les informations affichées :

  • Catégorie : constante System.Management.Automation.ErrorCategor y définie par Windows PowerShell.

  • TargetName : par défaut, le nom de l’objet que l’applet de commande a traité lorsque l’erreur s’est produite. Ou une autre chaîne définie par l’applet de commande.

  • TargetType : par défaut, type de l’objet cible. Ou une autre chaîne définie par l’applet de commande.

  • Activité : par défaut, le nom de l’applet de commande qui a créé l’enregistrement d’erreur. Ou une autre chaîne définie par l’applet de commande.

  • Raison : par défaut, le type d’exception. Ou une autre chaîne définie par l’applet de commande.

Message d’erreur de remplacement

Lorsque vous développez un enregistrement d’erreur pour une applet de commande, le message d’erreur par défaut de l’erreur provient du texte du message par défaut dans la propriété System.Exception.Message. Il s’agit d’une propriété en lecture seule dont le texte du message est destiné uniquement à des fins de débogage (conformément aux instructions du .NET Framework). Nous vous recommandons de créer un message d’erreur qui remplace ou augmente le texte du message par défaut. Rendre le message plus convivial et plus spécifique à l’applet de commande.

Le message de remplacement est fourni par un objet System.Management.Automation.ErrorDetails. Utilisez l’un des constructeurs suivants de cet objet, car ils fournissent des informations de localisation supplémentaires qui peuvent être utilisées par Windows PowerShell.

Le message de remplacement doit être conforme aux instructions de conception du .NET Framework pour l’écriture de messages d’exception avec une petite différence. Les instructions indiquent que les messages d’exception doivent être écrits pour les développeurs. Ces messages de remplacement doivent être écrits pour l’utilisateur de l’applet de commande.

Le message d’erreur de remplacement doit être ajouté avant l'System.Management.Automation.Cmdlet.WriteError ou méthodes System.Management.Automation.Cmdlet.ThrowTerminatingError* sont appelées. Pour ajouter un message de remplacement, définissez la propriété System.Management.Automation.ErrorRecord.ErrorDetails de l’enregistrement d’erreur. Lorsque cette propriété est définie, Windows PowerShell affiche la propriété System.Management.Automation.ErrorDetails.Message* au lieu du texte du message par défaut.

L’objet System.Management.Automation.ErrorDetails peut également fournir des informations sur les actions recommandées lorsque l’erreur se produit.

Informations d’appel

Lorsqu’une applet de commande utilise System.Management.Automation.Cmdlet.WriteError ou System.Management.Automation.Cmdlet.ThrowTerminatingError* pour signaler un enregistrement d’erreur, Windows PowerShell ajoute automatiquement des informations qui décrivent la commande appelée lors de l’erreur. Ces informations sont fournies par un objet System.Management.Automation.InvocationInfo qui contient le nom de l’applet de commande appelée par la commande, la commande elle-même et des informations sur le pipeline ou le script. Cette propriété est en lecture seule.

Voir aussi

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.ErrorCategory

System.Management.Automation.ErrorCategoryInfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.InvocationInfo

rapport d’erreurs Windows PowerShell

écriture d’une applet de commande Windows PowerShell

  • Last updated on