Write-Error

Référence

Module:: Microsoft.PowerShell.Utility

Écrit un objet dans le flux d'erreurs.

Syntax

Write-Error
     [-Message] <String>
     [-Category <ErrorCategory>]
     [-ErrorId <String>]
     [-TargetObject <Object>]
     [-RecommendedAction <String>]
     [-CategoryActivity <String>]
     [-CategoryReason <String>]
     [-CategoryTargetName <String>]
     [-CategoryTargetType <String>]
     [<CommonParameters>]

Write-Error
     -Exception <Exception>
     [-Message <String>]
     [-Category <ErrorCategory>]
     [-ErrorId <String>]
     [-TargetObject <Object>]
     [-RecommendedAction <String>]
     [-CategoryActivity <String>]
     [-CategoryReason <String>]
     [-CategoryTargetName <String>]
     [-CategoryTargetType <String>]
     [<CommonParameters>]

Write-Error
     -ErrorRecord <ErrorRecord>
     [-RecommendedAction <String>]
     [-CategoryActivity <String>]
     [-CategoryReason <String>]
     [-CategoryTargetName <String>]
     [-CategoryTargetType <String>]
     [<CommonParameters>]

Description

L’applet Write-Error de commande déclare une erreur sans fin. Par défaut, les erreurs sont envoyées dans le flux d'erreurs vers le programme hôte pour être affichées, avec la sortie.

Pour écrire une erreur sans fin d'exécution, entrez une chaîne de message d'erreur, un objet ErrorRecord ou un objet Exception. Utilisez les autres paramètres pour Write-Error remplir l’enregistrement d’erreur.

Les erreurs sans fin d'exécution écrivent une erreur dans le flux d'erreurs, mais elles n'arrêtent pas le traitement des commandes. Si une erreur sans fin d'exécution est déclarée sur un élément dans une collection d'éléments d'entrée, la commande continue de traiter les autres éléments dans la collection.

Pour déclarer une erreur de fin, utilisez le Throw mot clé. Pour plus d’informations, consultez about_Throw.

Exemples

Exemple 1 : Écrire une erreur pour l’objet RegistryKey

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

Cette commande déclare une erreur sans fin lorsque l’applet Get-ChildItem de commande retourne un Microsoft.Win32.RegistryKey objet, tel que les objets dans le ou HKCU: les HKLM: lecteurs du fournisseur de Registre PowerShell.

Exemple 2 : Écrire un message d’erreur dans la console

Write-Error "Access denied."

Cette commande déclare une erreur sans fin d'exécution et écrit une erreur « Accès refusé ». La commande utilise le paramètre Message pour spécifier le message, mais omet le nom du paramètre Message facultatif.

Exemple 3 : Écrire une erreur dans la console et spécifier la catégorie

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

Cette commande déclare une erreur sans fin d'exécution et spécifie une catégorie d'erreur.

Exemple 4 : Écrire une erreur à l’aide d’un objet Exception

$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location does not contain any XML files."

Cette commande utilise un objet Exception pour déclarer une erreur sans fin d'exécution.

La première commande utilise une table de hachage pour créer l'objet System.Exception. Il enregistre l’objet d’exception dans la $E variable. Vous pouvez utiliser une table de hachage pour créer n'importe quel objet d'un type qui a un constructeur de valeur null.

La deuxième commande utilise l’applet Write-Error de commande pour déclarer une erreur sans fin. La valeur du paramètre Exception est l’objet Exception dans la $E variable.

Paramètres

-Category

Spécifie la catégorie de l'erreur. La valeur par défaut est NotSpecified. Les valeurs valides pour ce paramètre sont :

NotSpecified
OpenError
CloseError
DeviceError
DeadlockDetected
InvalidArgument
InvalidData
InvalidOperation
InvalidResult
InvalidType
MetadataError
NotImplemented
Non installé
ObjectNotFound
OperationStopped
OperationTimeout
SyntaxError
Parsererror
PermissionDenied
ResourceBusy
ResourceExists
ResourceUnavailable
ReadError
WriteError
FromStdErr
SecurityError
ProtocolError
ConnectionError
AuthenticationError
LimitsExceededed
QuotaExceeded
NotEnabled

Pour plus d’informations sur les catégories d’erreurs, consultez l’énumération ErrorCategory.

Type:	ErrorCategory
Accepted values:	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, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled
Position:	Named
Default value:	NotSpecified
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryActivity

Spécifie l’action qui a provoqué l’erreur.

Type:	String
Aliases:	Activity
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryReason

Spécifie comment ou pourquoi l’activité a provoqué l’erreur.

Type:	String
Aliases:	Reason
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetName

Spécifie le nom de l'objet en cours de traitement quand l'erreur s'est produite.

Type:	String
Aliases:	TargetName
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CategoryTargetType

Spécifie le type de l'objet en cours de traitement quand l'erreur s'est produite.

Type:	String
Aliases:	TargetType
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorId

Spécifie une chaîne d'identification pour identifier l'erreur. La chaîne doit être propre à l'erreur.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ErrorRecord

Spécifie un objet d'enregistrement d'erreur qui représente l'erreur. Utilisez les propriétés de l'objet pour décrire l'erreur.

Pour créer un objet d’enregistrement d’erreur, utilisez l’applet New-Object de commande ou obtenez un objet d’enregistrement d’erreur à partir du tableau dans la $Error variable automatique.

Type:	ErrorRecord
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Exception

Spécifie un objet d'exception qui représente l'erreur. Utilisez les propriétés de l'objet pour décrire l'erreur.

Pour créer un objet d’exception, utilisez une table de hachage ou utilisez l’applet de New-Object commande.

Type:	Exception
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Message

Spécifie le texte du message de l'erreur. Si le texte comprend des espaces ou des caractères spéciaux, placez-le entre guillemets. Vous pouvez également diriger une chaîne de message vers Write-Error.

Type:	String
Aliases:	Msg
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-RecommendedAction

Spécifie l’action que l’utilisateur doit entreprendre pour résoudre ou empêcher l’erreur.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TargetObject

Spécifie l'objet en cours de traitement quand l'erreur s'est produite. Entrez l’objet, une variable qui contient l’objet ou une commande qui obtient l’objet.

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entrées

String

Vous pouvez diriger une chaîne contenant un message d’erreur vers Write-Error.

Sorties

Error object

Write-Error écrit uniquement dans le flux d’erreurs. Aucun objet n'est retourné.

Notes

Write-Error ne modifie pas la valeur de la $? variable automatique. Par conséquent, elle ne signale pas de condition d’erreur de fin. Pour signaler une erreur de fin, utilisez la méthode $PSCmdlet.WriteError().