Freigeben über

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 beendeten Fehler. Standardmäßig werden Fehler im Fehlerdatenstrom an das Hostprogramm gesendet und zusammen mit der Ausgabe angezeigt.

Wenn Sie einen nicht beendeten Fehler schreiben möchten, geben Sie eine Fehlermeldungszeichenfolge, ein ErrorRecord-Objekt oder ein Exception-Objekt ein. Verwenden Sie die anderen Parameter zum Write-Error Auffüllen des Fehlerdatensatzes.

Nicht beendete Fehler schreiben einen Fehler in den Fehlerdatenstrom, beenden die Befehlsverarbeitung jedoch nicht. 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 das Throw Schlüsselwort, um einen Beendigungsfehler zu deklarieren. Weitere Informationen finden Sie unter about_Throw.

Beispiele

Beispiel 1: Schreiben eines Fehlers für das RegistryKey-Objekt

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

Mit diesem Befehl wird ein nicht beendeter Fehler deklariert, wenn das Get-ChildItem Cmdlet ein Microsoft.Win32.RegistryKey Objekt zurückgibt, z. B. die Objekte in den HKLM: Oder HKCU: Laufwerken des PowerShell-Registrierungsanbieters.

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 Parameter "Message ", um die Nachricht anzugeben, aber der optionale Name des Nachrichtenparameters wird weggelassen.

Beispiel 3: Schreiben eines Fehlers in die Konsole und Angeben der Kategorie

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 Exception-Objekts

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

Dieser Befehl verwendet ein Exception-Objekt , um einen nicht beendeten Fehler zu deklarieren.

Der erste Befehl verwendet eine Hashtabelle, um das System.Exception-Objekt zu erstellen. Das Ausnahmeobjekt wird in der $E Variablen gespeichert. 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 beendeten Fehler zu deklarieren. Der Wert des Exception-Parameters ist das Exception-Objekt in der $E Variablen.

Parameter

-Category

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

  • NotSpecified
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • InvalidType
  • MetadataError
  • NotImplemented
  • NotInstalled
  • ObjectNotFound
  • OperationStopped
  • OperationTimeout
  • SyntaxFehler
  • 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.

Typ:ErrorCategory
Zulässige Werte: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
Standardwert:NotSpecified
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CategoryActivity

Gibt die Aktion an, die den Fehler verursacht hat.

Typ:String
Aliase:Activity
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CategoryReason

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

Typ:String
Aliase:Reason
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CategoryTargetName

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

Typ:String
Aliase:TargetName
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CategoryTargetType

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

Typ:String
Aliase:TargetType
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ErrorId

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

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ErrorRecord

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

Verwenden Sie das New-Object Cmdlet, oder rufen Sie ein Fehlerdatensatzobjekt aus dem Array in der $Error automatischen Variablen ab, um ein Fehlerdatensatzobjekt zu erstellen.

Typ:ErrorRecord
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 eine Hashtabelle oder das New-Object Cmdlet.

Typ:Exception
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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-Error.

Typ:String
Aliase:Msg
Position:0
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-RecommendedAction

Gibt die Aktion an, die der Benutzer ausführen soll, um den Fehler zu beheben oder zu verhindern.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-TargetObject

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

Typ:Object
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

String

Sie können eine Zeichenfolge mit einer Fehlermeldung an dieses Cmdlet weiterleiten.

Ausgaben

None

Dieses Cmdlet gibt keine Ausgabe zurück. Er schreibt nur in den Fehlermeldungsstream.

Hinweise

Write-Error ändert nicht den Wert der $? automatischen Variablen, daher signalisiert sie keine Beendigungsfehlerbedingung. Verwenden Sie die $PSCmdlet.WriteError() -Methode, um einen Beendigungsfehler zu signalisieren.