Write-Error

Referenz

Modul:: Microsoft.PowerShell.Utility

Schreibt ein Objekt in den Fehlerdatenstrom.

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>]

Beschreibung

Das Write-Error Cmdlet deklariert einen nicht terminierenden Fehler. Standardmäßig werden Fehler im Fehlerdatenstrom an das Hostprogramm gesendet und zusammen mit der Ausgabe angezeigt.

Um einen Fehler ohne Abbruch zu schreiben, geben Sie eine Fehlermeldungs-Zeichenfolge, ein ErrorRecord-Objekt oder ein Exception-Objekt ein. Verwenden Sie die anderen Parameter Write-Error , um den Fehlerdatensatz aufzufüllen.

Fehler ohne Abbruch schreiben einen Fehler in den Fehlerdatenstrom, ohne die Befehlsverarbeitung zu beenden. Wenn ein Fehler ohne Abbruch für ein einzelnes Element in einer Auflistung von Eingabeelementen deklariert wird, verarbeitet der Befehl weiterhin die anderen Elemente in der Auflistung.

Verwenden Sie zum Deklarieren eines Terminierungsfehlers das Throw Schlüsselwort. Weitere Informationen finden Sie unter about_Throw.

Beispiele

Beispiel 1: Schreiben eines Fehlers für registrierungskey-Objekt

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

Dieser Befehl deklariert einen nicht terminierenden Fehler, wenn das Get-ChildItem Cmdlet ein Microsoft.Win32.RegistryKey Objekt zurückgibt, z. B. die Objekte im HKCU:HKLM: PowerShell-Registrierungsanbieter.

Beispiel 2: Schreiben einer Fehlermeldung in die Konsole

Write-Error "Access denied."

Mit diesem Befehl wird ein Fehler ohne Abbruch deklariert und ein Fehler des Typs „Zugriff verweigert“ geschrieben. Der Befehl verwendet den Message-Parameter zur Angabe der Meldung, lässt jedoch den optionalen Message-Parameternamen aus.

Beispiel 3: Schreiben eines Fehlers in die Konsole und geben Sie die Kategorie an.

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

Mit diesem Befehl wird ein Fehler ohne Abbruch deklariert und eine Fehlerkategorie angegeben.

Beispiel 4: Schreiben eines Fehlers mithilfe eines Ausnahmeobjekts

$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."

Dieser Befehl verwendet ein Exception-Objekt, um einen Fehler ohne Abbruch zu deklarieren.

Der erste Befehl verwendet eine Hashtabelle zum Erstellen des System.Exception-Objekts. Es speichert das Ausnahmeobjekt in der $E Variable. Mithilfe einer Hashtabelle können Sie ein beliebiges Objekt eines Typs erstellen, der über einen NULL-Konstruktor verfügt.

Der zweite Befehl verwendet das Write-Error Cmdlet, um einen nicht terminierenden Fehler zu deklarieren. Der Wert des Ausnahmeparameters ist das Exception-Objekt in der $E Variable.

Parameter

-Category

Gibt die Kategorie des Fehlers an. Der Standardwert ist NotSpecified. Zulässige Werte für diesen Parameter:

NotSpecified
OpenError
CloseError
DeviceError
Deadlock Erkannt
InvalidArgument
InvalidData
InvalidOperation
InvalidResult
InvalidType
Metadatenfehler
NotImplemented
NotInstalled
ObjectNotFound
OperationStopped
OperationTimeout
SyntaxError
Parsererror
PermissionDenied
ResourceBusy
ResourceExists
ResourceUnavailable
ReadError
WriteError
FromStdErr
SecurityError
ProtocolError
ConnectionError
AuthenticationError
LimitsExceeded
QuotaExceeded
NotEnabled

Informationen zu den Fehlerkategorien finden Sie unter ErrorCategory-Aufzählung.

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

Gibt die Aktion an, die den Fehler verursacht hat.

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

-CategoryReason

Gibt an, wie oder warum die Aktivität den Fehler verursacht hat.

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

-CategoryTargetName

Gibt den Namen des Objekts an, das beim Auftreten des Fehlers verarbeitet wurde.

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

-CategoryTargetType

Gibt den Typ des Objekts an, das beim Auftreten des Fehlers verarbeitet wurde.

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

-ErrorId

Gibt eine ID-Zeichenfolge zum Identifizieren des Fehlers an. Die Zeichenfolge muss für den Fehler eindeutig sein.

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

-ErrorRecord

Gibt ein Fehlereintragsobjekt an, das den Fehler darstellt. Verwenden Sie die Eigenschaften des Objekts zur Beschreibung des Fehlers.

Um ein Fehlerdatensatzobjekt zu erstellen, verwenden Sie das New-Object Cmdlet oder rufen Sie ein Fehlerdatensatzobjekt aus dem Array in der $Error automatischen Variable ab.

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

-Exception

Gibt ein Ausnahmeobjekt an, das den Fehler darstellt. Verwenden Sie die Eigenschaften des Objekts zur Beschreibung des Fehlers.

Verwenden Sie zum Erstellen eines Ausnahmeobjekts New-Object eine Hashtabelle oder das Cmdlet.

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

-Message

Gibt den Meldungstext des Fehlers an. Wenn der Text Leerzeichen oder Sonderzeichen enthält, müssen Sie ihn in Anführungszeichen einschließen. Sie können auch eine Nachrichtenzeichenfolge an Write-Errorsenden.

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

-RecommendedAction

Gibt die Aktion an, die der Benutzer ergreifen sollte, um den Fehler zu beheben oder zu verhindern.

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

-TargetObject

Gibt das Objekt an, das beim Auftreten des Fehlers verarbeitet wurde. Geben Sie das Objekt, eine Variable ein, die das Objekt enthält, oder einen Befehl, der das Objekt abruft.

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

Eingaben

String

Sie können eine Zeichenfolge senden, die eine Fehlermeldung Write-Errorenthält.

Ausgaben

Error object

Write-Error schreibt nur auf den Fehlerdatenstrom. und gibt keine Objekte zurück.

Hinweise

Write-Error ändert den Wert der $? automatischen Variable nicht, daher signalisiert er keine Terminierungsfehlerbedingung. Um einen Terminierungsfehler zu signalisieren, verwenden Sie die $PSCmdlet.WriteError() -Methode.