Écrit un objet dans le flux d'erreurs.
Syntaxe
Write-Error -ErrorRecord <ErrorRecord> [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error [-Message] <string> [-Category {<NotSpecified> | <OpenError> | <CloseError> | <DeviceError> | <DeadlockDetected> | <InvalidArgument> | <InvalidData> | <InvalidOperation> | <InvalidResult> | <InvalidType> | <MetadataError> | <NotImplemented> | <NotInstalled> | <ObjectNotFound> | <OperationStopped> | <OperationTimeout> | <SyntaxError> | <ParserError> | <PermissionDenied> | <ResourceBusy> | <ResourceExists> | <ResourceUnavailable> | <ReadError> | <WriteError> | <FromStdErr> | <SecurityError>}] [-ErrorId <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Write-Error -Exception <Exception> [-Category {<NotSpecified> | <OpenError> | <CloseError> | <DeviceError> | <DeadlockDetected> | <InvalidArgument> | <InvalidData> | <InvalidOperation> | <InvalidResult> | <InvalidType> | <MetadataError> | <NotImplemented> | <NotInstalled> | <ObjectNotFound> | <OperationStopped> | <OperationTimeout> | <SyntaxError> | <ParserError> | <PermissionDenied> | <ResourceBusy> | <ResourceExists> | <ResourceUnavailable> | <ReadError> | <WriteError> | <FromStdErr> | <SecurityError>}] [-ErrorId <string>] [-Message <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]
Description
L'applet de commande Write-Error écrit une erreur dans le flux d'erreurs Windows PowerShell. Par défaut, les erreurs sont envoyées au programme hôte à afficher, avec la sortie.
Vous pouvez écrire une erreur en envoyant une chaîne de message d'erreur, un objet ErrorRecord ou un objet Exception. Utilisez les autres paramètres de Write-Error pour remplir l'enregistrement d'erreur.
Paramètres
-Category <ErrorCategory>
Spécifie la catégorie de l'erreur. La valeur par défaut est NotSpecified.
Pour plus d'informations sur les catégories d'erreur, consultez « Énumération ErrorCategory » (page éventuellement en anglais) dans MSDN Library, à l'adresse https://go.microsoft.com/fwlink/?LinkId=143600.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
NotSpecified |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-CategoryActivity <string>
Décrit l'action qui a provoqué l'erreur.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-CategoryReason <string>
Explique comment ou pourquoi l'activité a provoqué l'erreur.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-CategoryTargetName <string>
Spécifie le nom de l'objet traité lorsque l'erreur s'est produite.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-CategoryTargetType <string>
Spécifie le type .NET de l'objet traité lorsque l'erreur s'est produite.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-ErrorId <string>
Spécifie une chaîne d'ID pour identifier l'erreur. Cette chaîne doit être unique pour cette erreur.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-ErrorRecord <ErrorRecord>
Spécifie un objet enregistrement d'erreur qui inclut des propriétés décrivant l'erreur.
Pour obtenir un objet enregistrement d'erreur, utilisez l'applet de commande New-Object ou récupérez un objet enregistrement d'erreur dans le tableau de la variable automatique $Error.
|
Obligatoire ? |
true |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Exception <Exception>
Spécifie une exception qui représente l'erreur.
Vous pouvez utiliser une exception au lieu de spécifier un texte de message ou un enregistrement d'exception.
|
Obligatoire ? |
true |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-Message <string>
Spécifie le texte du message de l'erreur. Si le texte contient des espaces ou des caractères spéciaux, mettez-le entre guillemets. Vous pouvez également diriger une chaîne de message vers Write-Error.
|
Obligatoire ? |
true |
|
Position ? |
1 |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
true (ByValue) |
|
Accepter les caractères génériques ? |
false |
-RecommendedAction <string>
Décrit l'action que l'utilisateur doit entreprendre pour résoudre ou empêcher l'erreur.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
-TargetObject <Object>
Spécifie l'objet traité lorsque l'erreur s'est produite. Entrez l'objet (tel qu'une chaîne), une variable contenant l'objet ou une commande permettant d'obtenir cet objet.
|
Obligatoire ? |
false |
|
Position ? |
named |
|
Valeur par défaut |
aucun |
|
Accepter l'entrée de pipeline ? |
false |
|
Accepter les caractères génériques ? |
false |
<CommonParameters>
Cette applet de commande prend en charge les paramètres courants : -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer et -OutVariable. Pour plus d'informations, consultez about_Commonparameters.
Entrées et sorties
Le type d'entrée est le type des objets que vous pouvez diriger vers l'applet de commande. Le type de retour est le type des objets que l'applet de commande retourne.
|
Entrées |
System.String Vous pouvez diriger une chaîne contenant un message d'erreur vers Write-Error. |
|
Sorties |
Objet erreur Write-Error écrit uniquement dans le flux d'erreurs. Elle ne retourne aucun objet. |
Exemple 1
C:\PS>get-childitem | foreach-object { if ($_.gettype().tostring() -eq "Microsoft.Win32.RegistryKey") {write-error "Out-of-band object" -errorID B1 -targetobject $_ } else {$_ } }
Description
-----------
Cette commande écrit une erreur lorsque l'applet de commande Get-ChildItem retourne un objet Microsoft.Win32.RegistryKey, tel que les objets des lecteurs HKLM: ou HKCU du fournisseur Registry de Windows PowerShell.
Exemple 2
C:\PS>write-error "Access denied." Description ----------- Cette commande écrit une erreur « Accès refusé ». Elle utilise le paramètre Message pour spécifier le message, mais omet le nom de paramètre Message facultatif.
Exemple 3
C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument Description ----------- Cette commande écrit une erreur et spécifie une catégorie d'erreur.
Voir aussi