Write-Error

Schreibt ein Objekt in den Fehlerstream.

Syntax

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

Write-Error [-Message] <string> [-Category {<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>}] [-ErrorId <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]

Write-Error -Exception <Exception> [-Category {<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>}] [-ErrorId <string>] [-Message <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]

Beschreibung

Das Cmdlet "Write-Error" schreibt einen Fehler in den Windows PowerShell-Fehlerstream. Standardmäßig werden Fehler zusammen mit der Ausgabe zur Anzeige an das Hostprogramm gesendet.

Sie können einen Fehler schreiben, indem Sie eine Fehlermeldungszeichenfolge, ein ErrorRecord-Objekt oder ein Ausnahmeobjekt senden. Verwenden Sie die anderen Parameter von Write-Error, um den Fehlerdatensatz aufzufüllen.

Parameter

-Category <ErrorCategory>

Gibt die Kategorie des Fehlers an. Der Standardwert ist "NotSpecified".

Weitere Informationen zu Fehlerkategorien finden Sie unter "ErrorCategory-Enumeration" in der MSDN Library (Microsoft Developer Network) unter "https://go.microsoft.com/fwlink/?LinkId=143600" (möglicherweise auf Englisch).

Erforderlich?	false
Position?	named
Standardwert	NotSpecified
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-CategoryActivity <string>

Beschreibt die Aktion, die den Fehler verursacht hat.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-CategoryReason <string>

Erläutert, wie oder warum die Aktivität den Fehler verursacht hat.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-CategoryTargetName <string>

Gibt den Namen des Objekts an, das verarbeitet wurde, als der Fehler aufgetreten ist.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-CategoryTargetType <string>

Gibt den .NET-Typ des Objekts an, das verarbeitet wurde, als der Fehler aufgetreten ist.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ErrorId <string>

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

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ErrorRecord <ErrorRecord>

Gibt ein Fehlerdatensatzobjekt an, das Eigenschaften enthält, die den Fehler beschreiben.

Verwenden Sie zum Abrufen eines Fehlerdatensatzobjekts das Cmdlet "New-Object", oder verwenden Sie ein Fehlerdatensatzobjekt aus dem Array in der automatischen Variablen "$Error".

Erforderlich?	true
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Exception <Exception>

Gibt eine Ausnahme an, die den Fehler darstellt.

Sie können eine Ausnahme verwenden, statt Meldungstext oder einen Ausnahmedatensatz anzugeben.

Erforderlich?	true
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Message <string>

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

Erforderlich?	true
Position?	1
Standardwert	Keiner
Pipelineeingaben akzeptieren?	true (ByValue)
Platzhalterzeichen akzeptieren?	false

-RecommendedAction <string>

Beschreibt die Aktion, die der Benutzer ausführen sollte, um den Fehler zu beheben oder zu verhindern.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-TargetObject <Object>

Gibt das Objekt an, das verarbeitet wurde, als der Fehler aufgetreten ist. Geben Sie das Objekt (z. B. eine Zeichenfolge), eine Variable, die das Objekt enthält, oder einen Befehl ein, mit dem das Objekt abgerufen wird.

Erforderlich?	false
Position?	named
Standardwert	Keiner
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

<CommonParameters>

Dieses Cmdlet unterstützt die folgenden allgemeinen Parameter: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer und -OutVariable. Weitere Informationen finden Sie unter about_Commonparameters.

Eingaben und Ausgaben

Der Eingabetyp ist der Typ der Objekte, die über die Pipeline an das Cmdlet übergeben werden können. Der Rückgabetyp ist der Typ der Objekte, die das Cmdlet zurückgibt.

Eingaben	System.String Sie können über die Pipeline eine Zeichenfolge, die eine Fehlermeldung enthält, an Write-Error übergeben.
Ausgaben	Error-Objekt Write-Error schreibt nur in den Fehlerstream. Es werden keine Objekte zurückgegeben.

Beispiel 1

C:\PS>get-childitem | foreach-object { if ($_.gettype().tostring() -eq "Microsoft.Win32.RegistryKey") {write-error "Out-of-band object" -errorID B1 -targetobject $_ } else {$_ } }

Beschreibung
-----------
Dieser Befehl schreibt einen Fehler, wenn das Cmdlet "Get-ChildItem" ein Microsoft.Win32.RegistryKey-Objekt zurückgibt, z. B. die Objekte auf dem Laufwerk "HKLM:" oder "HKCU:" des Windows PowerShell-Registrierungsanbieters.

Beispiel 2

C:\PS>write-error  "Access denied."

Beschreibung
-----------
Dieser Befehl schreibt den Fehler für verweigerten Zugriff. Der Befehl gibt die Meldung mithilfe des Message-Parameters an, jedoch wird der optionale Name des Message-Parameters weggelassen.

Beispiel 3

C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument

Beschreibung
-----------
Mit diesem Befehl wird ein Fehler geschrieben und eine Fehlerkategorie angegeben.

Siehe auch

Konzepte

Write-Debug
Write-Verbose
Write-Output
Write-Host
Write-Progress
Write-Warning