Freigeben über

Write-Error

Modul:
Microsoft.PowerShell.Utility Module

Schreibt ein Objekt in den Fehlerdatenstrom.

Syntax

NoException (Standardwert) 

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

Beschreibung

Das cmdlet Write-Error deklariert einen nicht beendeten Fehler. Standardmäßig werden Fehler im Fehlerdatenstrom an das Hostprogramm gesendet, das angezeigt werden soll, zusammen mit der Ausgabe.

Um einen nicht beendeten Fehler zu schreiben, geben Sie eine Fehlermeldungszeichenfolge, ein ErrorRecord--Objekt oder ein Exception-Objekt ein. Verwenden Sie die anderen Parameter von Write-Error, um den Fehlerdatensatz aufzufüllen.

Nicht beendete Fehler schreiben einen Fehler in den Fehlerdatenstrom, beenden die Befehlsverarbeitung jedoch nicht. Wenn ein nicht beendeter Fehler für ein Element in einer Sammlung von Eingabeelementen deklariert wird, verarbeitet der Befehl weiterhin die anderen Elemente in der Auflistung.

Verwenden Sie das schlüsselwort throw, 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 cmdlet Get-ChildItem ein Microsoft.Win32.RegistryKey-Objekt zurückgibt, z. B. die Objekte im HKLM: oder HKCU: Laufwerken des PowerShell-Registrierungsanbieters.

Beispiel 2: Schreiben einer Fehlermeldung in die Konsole

Write-Error "Access denied."

Dieser Befehl deklariert einen nicht beendeten Fehler und schreibt einen Fehler "Zugriff verweigert". Der Befehl verwendet den parameter Message, um die Nachricht anzugeben, aber der optionale Message Parametername wird weggelassen.

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

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

Dieser Befehl deklariert einen nicht beendeten Fehler und gibt eine Fehlerkategorie an.

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. Es speichert das Ausnahmeobjekt in der $E Variablen. Sie können eine Hashtabelle verwenden, um ein beliebiges Objekt eines Typs zu erstellen, der über einen NULL-Konstruktor verfügt.

Der zweite Befehl verwendet das cmdlet Write-Error, um einen nicht beendeten Fehler zu deklarieren. Der Wert des parameters Exception ist das Exception-Objekt in der variablen $E.

Parameter

-Category

Gibt die Kategorie des Fehlers an. Der Standardwert ist NotSpecified. Die zulässigen Werte für diesen Parameter sind:

  • Nicht angegeben
  • Offener Fehler
  • SchließenFehler
  • GerätFehler
  • DeadlockErkannt
  • InvalidArgument
  • Ungültige Daten
  • Ungültige Operation
  • Ungültiges Ergebnis
  • InvalidType (Ungültiger Typ)
  • Metadaten-Fehler
  • Nicht implementiert
  • Nicht installiert
  • ObjektNicht gefunden
  • OperationGestoppt
  • OperationTimeout
  • SyntaxFehler
  • ParserFehler
  • BerechtigungVerweigert
  • RessourceBeschäftigt
  • RessourceExistiert
  • RessourceNicht verfügbar
  • ReadError (Lesen)
  • Schreibfehler
  • VonStdErr
  • Sicherheitsfehler
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • Grenzwerte überschritten
  • QuotaExceeded
  • NotEnabled

Informationen zu den Fehlerkategorien finden Sie unter ErrorCategory Enumeration.

Parametereigenschaften

Typ:ErrorCategory
Standardwert:NotSpecified
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
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

NoException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False
WithException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-CategoryActivity

Gibt die Aktion an, die den Fehler verursacht hat.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False
Aliase:Aktivität

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-CategoryReason

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

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False
Aliase:Ursache

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-CategoryTargetName

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

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False
Aliase:TargetName

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-CategoryTargetType

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

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False
Aliase:Zieltyp

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-ErrorId

Gibt eine ID-Zeichenfolge an, um den Fehler zu identifizieren. Die Zeichenfolge sollte für den Fehler eindeutig sein.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

NoException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False
WithException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-ErrorRecord

Gibt ein Fehlerdatensatzobjekt an, das den Fehler darstellt. Verwenden Sie die Eigenschaften des Objekts, um den Fehler zu beschreiben.

Verwenden Sie zum Erstellen eines Fehlerdatensatzobjekts das cmdlet New-Object oder rufen Sie ein Fehlerdatensatzobjekt aus dem Array in der $Error automatischen Variablen ab.

Parametereigenschaften

Typ:ErrorRecord
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

ErrorRecord
Position:0
Obligatorisch.:True
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Exception

Gibt ein Ausnahmeobjekt an, das den Fehler darstellt. Verwenden Sie die Eigenschaften des Objekts, um den Fehler zu beschreiben.

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

Parametereigenschaften

Typ:Exception
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

WithException
Position:0
Obligatorisch.:True
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Message

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

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False
Aliase:Msg

Parametersätze

NoException
Position:0
Obligatorisch.:True
Wert aus Pipeline:True
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False
WithException
Position:0
Obligatorisch.:False
Wert aus Pipeline:True
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-RecommendedAction

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

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten: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.

Parametereigenschaften

Typ:Object
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

NoException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False
WithException
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

CommonParameters

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

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 zum Signalisieren eines Beendigungsfehlers die $PSCmdlet.WriteError() Methode.