Udostępnij za pomocą

Write-Error

Moduł:
Microsoft.PowerShell.Utility Module

Zapisuje obiekt w strumieniu błędów.

Składnia

NoException (Domyślna) 

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

Opis

Polecenie cmdlet Write-Error deklaruje błąd bez zakończenia. Domyślnie błędy są wysyłane w strumieniu błędów, aby program hosta mógł je wyświetlić wraz z danymi wyjściowymi.

Aby napisać błąd bez zakończenia, wprowadź ciąg komunikatu o błędzie, obiekt ErrorRecord lub obiekt Exception. Użyj innych parametrów 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 na jeden z elementów w kolekcji elementów wejściowych zadeklarowany zostanie błąd nie kończący procesu, polecenie będzie nadal przetwarzać pozostałe elementy 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: Zapis 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 niekończący się błąd, gdy cmdlet Get-ChildItem zwraca obiekt Microsoft.Win32.RegistryKey, taki jak obiekty w napędach HKLM: lub HKCU: dostawcy rejestru programu PowerShell.

Przykład 2. Zapisywanie komunikatu o błędzie w konsoli

Write-Error "Access denied."

To polecenie deklaruje błąd nieterminalny i zapisuje błąd "Odmowa dostępu". Polecenie używa parametru Message w celu określenia komunikatu, ale pomija opcjonalną nazwę parametru Message.

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, który nie powoduje zakończenia, i określa kategorię błędu.

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 doesn't contain any XML files."

To polecenie używa obiektu wyjątku do zadeklarowania błędu niekończącego się.

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 cmdlet Write-Error do deklarowania błędu niekończącego działania. Wartość parametru wyjątku jest obiektem Exception w zmiennej .

Parametry

-Category

Określa kategorię błędu. Wartość domyślna to NotSpecified. Dopuszczalne wartości tego parametru to:

  • Nieokreślony
  • OpenError
  • CloseError
  • Błąd urządzenia
  • Wykryto zakleszczenie
  • NieprawidłowyArgument
  • NieprawidłoweDane
  • Nieprawidłowa operacja
  • NieprawidłowyWynik
  • Nieprawidłowy typ
  • MetadataError
  • Niezaimplementowane
  • Nie zainstalowano
  • ObjectNotFound
  • OperacjaZatrzymana
  • OperationTimeout
  • Błąd składni
  • ParserError
  • Odmowa dostępu
  • Zasób zajęty
  • ResourceExists
  • ZasóbNiedostępny
  • Błąd odczytu
  • Błąd zapisu
  • FromStdErr
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • Przekroczono limity
  • Przekroczono limit
  • Nieaktywny

Aby uzyskać informacje o kategoriach błędów, zobacz ErrorCategory Enumeration.

Właściwości parametru

Typ:ErrorCategory
Domyślna wartość:NotSpecified
Dopuszczalne wartości: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
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

NoException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False
WithException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-CategoryActivity

Określa akcję, która spowodowała błąd.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:Aktywność

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-CategoryReason

Określa, jak lub dlaczego działanie spowodowało błąd.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:Powód

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-CategoryTargetName

Określa nazwę obiektu, który był przetwarzany podczas wystąpienia błędu.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:TargetName

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-CategoryTargetType

Określa typ obiektu, który był przetwarzany podczas wystąpienia błędu.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:TypDocelowy

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-ErrorId

Określa ciąg identyfikatora, aby zidentyfikować błąd. Ciąg powinien być unikalny dla błędu.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

NoException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False
WithException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów: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 polecenia cmdlet New-Object lub uzyskaj obiekt rekordu błędu z tablicy w zmiennej automatycznej $Error.

Właściwości parametru

Typ:ErrorRecord
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

ErrorRecord
Position:0
Obowiązkowy:True
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów: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 lub użyj polecenia cmdlet New-Object.

Właściwości parametru

Typ:Exception
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

WithException
Position:0
Obowiązkowy:True
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów: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.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False
Aliasy:Msg

Zestawy parametrów

NoException
Position:0
Obowiązkowy:True
Wartość z potoku:True
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False
WithException
Position:0
Obowiązkowy:False
Wartość z potoku:True
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-RecommendedAction

Określa akcję, którą użytkownik powinien podjąć, aby rozwiązać problem lub zapobiec temu błędowi.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów: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.

Właściwości parametru

Typ:Object
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

NoException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False
WithException
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Dane wejściowe

String

Możesz przekazać ciąg zawierający komunikat o błędzie do tego polecenia cmdlet.

Dane wyjściowe

None

To polecenie cmdlet nie zwraca żadnych danych wyjściowych. Tylko zapisuje do strumienia komunikatów o błędzie.

Uwagi

Write-Error nie zmienia wartości zmiennej automatycznej $?, dlatego nie sygnalizuje zakończenia błędu. Aby zasygnalizować błąd zakończenia, użyj metody $PSCmdlet.WriteError().