Write-Error
É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 de non-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 de Write-Error
pour 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 de non-fin lorsque l’applet Get-ChildItem
de commande retourne un Microsoft.Win32.RegistryKey
objet, tel que les objets dans les HKLM:
lecteurs ou HKCU:
du fournisseur powerShell Registry.
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
- SyntaxeError
- Parsererror
- PermissionDenied
- ResourceBusy
- ResourceExists
- ResourceUnavailable
- ReadError
- WriteError
- FromStdErr
- SecurityError
- ProtocolError
- ConnectionError
- AuthenticationError
- LimitesExceededed
- QuotaExceeded
- NotEnabled
Pour plus d’informations sur les catégories d’erreurs, consultez ErrorCategory, énumération.
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 et 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
Vous pouvez diriger une chaîne qui contient 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, il ne signale pas une condition d’erreur de fin. Pour signaler une erreur de fin, utilisez la méthode $PSCmdlet.WriteError().