Write-Error
Zapisuje obiekt w strumieniu błędów.
Składnia
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>]
Opis
Polecenie Write-Error
cmdlet deklaruje błąd niepowodujący zakończenia. Domyślnie błędy są wysyłane w strumieniu błędów do programu hosta do wyświetlenia wraz z danymi wyjściowymi.
Aby napisać błąd niepowodujący zakończenia, wprowadź ciąg komunikatu o błędzie, obiekt ErrorRecord lub obiekt Exception . Użyj innych parametrów polecenia , Write-Error
aby wypełnić rekord błędu.
Błędy niepowodujące zakończenia zapisują błąd w strumieniu błędów, ale nie zatrzymują przetwarzania poleceń. Jeśli w kolekcji elementów wejściowych zadeklarowany jest błąd niepowodujący zakończenia, polecenie kontynuuje przetwarzanie innych elementów w kolekcji.
Aby zadeklarować błąd zakończenia, użyj słowa kluczowego Throw
.
Aby uzyskać więcej informacji, zobacz about_Throw.
Przykłady
Przykład 1. Zapisywanie błędu dla obiektu RegistryKey
Get-ChildItem | ForEach-Object {
if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
{
Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
}
else
{
$_
}
}
To polecenie deklaruje błąd, który nie kończy się, gdy Get-ChildItem
polecenie cmdlet zwraca Microsoft.Win32.RegistryKey
obiekt, taki jak obiekty w HKLM:
dostawcy rejestru programu PowerShell lub lub HKCU:
.
Przykład 2: Zapisywanie komunikatu o błędzie w konsoli
Write-Error "Access denied."
To polecenie deklaruje błąd niepowodujący zakończenia i zapisuje błąd "Odmowa dostępu". Polecenie używa parametru Message do określenia komunikatu, ale pomija opcjonalną nazwę parametru Komunikat .
Przykład 3: Zapisywanie błędu w konsoli i określanie kategorii
Write-Error -Message "Error: Too many input values." -Category InvalidArgument
To polecenie deklaruje błąd niepowodujący zakończenia i określa kategorię błędów.
Przykład 4. Zapisywanie błędu przy użyciu obiektu 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."
To polecenie używa obiektu Exception do deklarowania błędu niepowodującego zakończenia.
Pierwsze polecenie używa tabeli skrótów do utworzenia obiektu System.Exception . Zapisuje obiekt wyjątku w zmiennej $E
. Tabelę skrótów można użyć do utworzenia dowolnego obiektu typu, który ma konstruktor o wartości null.
Drugie polecenie używa Write-Error
polecenia cmdlet do deklarowania błędu niepowodującego zakończenia. Wartość parametru Exception jest obiektem Exception w zmiennej $E
.
Parametry
-Category
Określa kategorię błędu. Wartość domyślna to NotSpecified. Dopuszczalne wartości dla tego parametru to:
- Nieokreślone
- OpenError
- CloseError
- DeviceError
- ZakleszczenieWykrywalne
- InvalidArgument
- InvalidData
- InvalidOperation
- InvalidResult
- Nieprawidłowy typ
- MetadataError
- Nieimplementowane
- Nieinstalowane
- ObjectNotFound
- OperacjaStopped
- Limit czasu operacji
- SyntaxError
- Parsererror
- PermissionDenied
- ResourceBusy
- ResourceExists
- Zasób Niedostępny
- ReadError
- WriteError
- FromStdErr
- Securityerror
- ProtocolError
- Błąd połączenia
- Błąd uwierzytelniania
- LimitsExceeded
- QuotaExceeded
- NotEnabled
Aby uzyskać informacje o kategoriach błędów, zobacz ErrorCategory Enumeration (Wyliczenie ErrorCategory).
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
Określa akcję, która spowodowała błąd.
Type: | String |
Aliases: | Activity |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryReason
Określa, jak lub dlaczego działanie spowodowało błąd.
Type: | String |
Aliases: | Reason |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryTargetName
Określa nazwę obiektu, który był przetwarzany podczas wystąpienia błędu.
Type: | String |
Aliases: | TargetName |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CategoryTargetType
Określa typ obiektu, który był przetwarzany podczas wystąpienia błędu.
Type: | String |
Aliases: | TargetType |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ErrorId
Określa ciąg identyfikatora, aby zidentyfikować błąd. Ciąg powinien być unikatowy dla błędu.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ErrorRecord
Określa obiekt rekordu błędu, który reprezentuje błąd. Użyj właściwości obiektu, aby opisać błąd.
Aby utworzyć obiekt rekordu błędu, użyj New-Object
polecenia cmdlet lub uzyskaj obiekt rekordu błędu z tablicy w zmiennej automatycznej $Error
.
Type: | ErrorRecord |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Exception
Określa obiekt wyjątku, który reprezentuje błąd. Użyj właściwości obiektu, aby opisać błąd.
Aby utworzyć obiekt wyjątku, użyj tabeli skrótów New-Object
lub użyj polecenia cmdlet .
Type: | Exception |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Message
Określa tekst komunikatu o błędzie. Jeśli tekst zawiera spacje lub znaki specjalne, należy go ująć w cudzysłów. Możesz również przekazać ciąg komunikatu do Write-Error
.
Type: | String |
Aliases: | Msg |
Position: | 0 |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-RecommendedAction
Określa akcję, którą użytkownik powinien podjąć, aby usunąć lub zapobiec błędowi.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TargetObject
Określa obiekt, który był przetwarzany podczas wystąpienia błędu. Wprowadź obiekt, zmienną zawierającą obiekt lub polecenie, które pobiera obiekt.
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Dane wejściowe
Ciąg zawierający komunikat o błędzie można przekazać potokiem do Write-Error
adresu .
Dane wyjściowe
Error object
Write-Error
zapisuje tylko w strumieniu błędów. Nie zwraca żadnych obiektów.
Uwagi
Write-Error
nie zmienia wartości zmiennej automatycznej $?
, dlatego nie sygnalizuje warunku błędu zakończenia. Aby zasygnalizować błąd zakończenia, użyj metody $PSCmdlet.WriteError().