Udostępnij za pośrednictwem

Write-Error

  • Odwołanie
Moduł:
Microsoft.PowerShell.Utility

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 cmdlet Write-Error deklaruje błąd bez 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 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 w kolekcji elementów wejściowych zadeklarowany jest błąd niepowodujący zakończenia, polecenie będzie nadal przetwarzać inne 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 błąd, który nie kończy się, gdy polecenie cmdlet Get-ChildItem zwraca obiekt Microsoft.Win32.RegistryKey, taki jak obiekty w HKLM: lub HKCU: dysków dostawcy rejestru programu PowerShell.

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

To polecenie używa obiektu wyjątku do deklarowania błędu, który nie kończy 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 polecenia cmdlet Write-Error do deklarowania błędu bez zakończenia. Wartość parametru wyjątku jest obiektem Exception w zmiennej $E.

Parametry

-Category

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

  • Nieokreślony
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • Nieprawidłowy typ
  • MetadataError
  • Nieimplementowane
  • Nieinstalowane
  • ObjectNotFound
  • OperationStopped
  • OperationTimeout
  • SkładniaError
  • ParserError
  • PermissionDenied
  • ZasóbBusy
  • ResourceExists
  • ZasóbDostępny
  • ReadError
  • WriteError
  • FromStdErr
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitsExceeded
  • QuotaExceed
  • NotEnabled

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

Typ:ErrorCategory
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
Position:Named
Domyślna wartość:NotSpecified
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-CategoryActivity

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

Typ:String
Aliasy:Activity
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-CategoryReason

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

Typ:String
Aliasy:Reason
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-CategoryTargetName

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

Typ:String
Aliasy:TargetName
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-CategoryTargetType

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

Typ:String
Aliasy:TargetType
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-ErrorId

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

Typ:String
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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.

Typ:ErrorRecord
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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.

Typ:Exception
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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.

Typ:String
Aliasy:Msg
Position:0
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:True
Akceptowanie symboli wieloznacznych:False

-RecommendedAction

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

Typ:String
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych: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.

Typ:Object
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

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. Zapisuje tylko w strumieniu komunikatów o błędzie.

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().