Write-Error

Module:: Microsoft.PowerShell.Utility Module

Écrit un objet dans le flux d’erreurs.

Syntaxe

NoException (Par défaut)

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

WithException

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

ErrorRecord

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

Description

L’applet de commande Write-Error déclare une erreur sans fin. Par défaut, les erreurs sont envoyées dans le flux d’erreurs au programme hôte à afficher, ainsi que la sortie.

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

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

Pour déclarer une erreur de fin, utilisez le mot clé throw. 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 de non-fin lorsque l’applet de commande Get-ChildItem retourne un objet Microsoft.Win32.RegistryKey, tel que les objets dans le HKLM: ou les lecteurs HKCU: 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 et écrit une erreur « Accès refusé ». La commande utilise le paramètre Message pour spécifier le message, mais omettez le nom de paramètre facultatif Message.

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 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 doesn't contain any XML files."

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

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

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

Paramètres

-Category

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

Non spécifié
OuvrirErreur
FermerErreur
DeviceError
BlocageDétecté
InvalidArgument
Données non valides
Opération non valide
InvalidResult
Type invalide
MetadataError
Non implémenté
Non installé
ObjectNotFound
FonctionnementArrêté
OpérationDélai d’attente
SyntaxError
ParserError
PermissionDenied
RessourceOccupé
RessourceExiste
RessourceIndisponible
ReadError
Erreur d’écriture
FromStdErr
SecurityError
ProtocolError
ConnectionError
AuthenticationError
LimitesDépassées
QuotaExceeded
NotEnabled

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

Propriétés du paramètre

Type:	ErrorCategory
Valeur par défaut:	NotSpecified
Valeurs acceptées:	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
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NoException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

WithException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-CategoryActivity

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	Activité

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-CategoryReason

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	Motif

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-CategoryTargetName

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	TargetName

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-CategoryTargetType

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	TargetType

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-ErrorId

Spécifie une chaîne d’ID pour identifier l’erreur. La chaîne doit être unique à l’erreur.

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NoException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

WithException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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 de commande New-Object ou obtenez un objet d’enregistrement d’erreur à partir du tableau dans la variable automatique $Error.

Propriétés du paramètre

Type:	ErrorRecord
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

ErrorRecord

Position:	0
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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 commande New-Object.

Propriétés du paramètre

Type:	Exception
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

WithException

Position:	0
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-Message

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	Msg

Jeux de paramètres

NoException

Position:	0
Obligatoire:	True
Valeur du pipeline:	True
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

WithException

Position:	0
Obligatoire:	False
Valeur du pipeline:	True
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-RecommendedAction

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-TargetObject

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

Propriétés du paramètre

Type:	Object
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NoException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

WithException

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

CommonParameters

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

Entrées

String

Vous pouvez diriger une chaîne contenant un message d’erreur vers cette applet de commande.

Sorties

None

Cette applet de commande ne retourne aucune sortie. Il écrit uniquement dans le flux de messages d’erreur.

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().

Rétroaction

Cette page vous a-t-elle été utile ?

Partager via

Write-Error

Syntaxe

NoException (Par défaut)

WithException

ErrorRecord

Description

Exemples

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

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

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

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

Paramètres

-Category

Propriétés du paramètre

Jeux de paramètres

-CategoryActivity

Propriétés du paramètre

Jeux de paramètres

-CategoryReason

Propriétés du paramètre

Jeux de paramètres

-CategoryTargetName

Propriétés du paramètre

Jeux de paramètres

-CategoryTargetType

Propriétés du paramètre

Jeux de paramètres

-ErrorId

Propriétés du paramètre

Jeux de paramètres

-ErrorRecord

Propriétés du paramètre

Jeux de paramètres

-Exception

Propriétés du paramètre

Jeux de paramètres

-Message

Propriétés du paramètre

Jeux de paramètres

-RecommendedAction

Propriétés du paramètre

Jeux de paramètres

-TargetObject

Propriétés du paramètre

Jeux de paramètres

CommonParameters

Entrées

String

Sorties

None

Notes

Liens associés

Rétroaction