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 Write-Error cmdlet deklaruje błąd, który nie kończy się. 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 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 Get-ChildItem polecenie cmdlet zwraca Microsoft.Win32.RegistryKey obiekt, taki jak obiekty w HKLM:HKCU: lub dyskach 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 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 doesn't contain any XML files."

To polecenie używa obiektu Exception w celu zadeklarowania 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 Write-Error polecenia cmdlet do deklarowania błędu, który nie kończy się. Wartość parametru Exception 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
  • Połączenie ionError
  • AuthenticationError
  • LimitsExceeded
  • QuotaExceeded
  • NotEnabled

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

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 pobierz obiekt rekordu błędu z tablicy w zmiennej automatycznej $Error .

Type:ErrorRecord
Position:0
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ótu lub użyj New-Object polecenia cmdlet .

Type:Exception
Position:0
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 rozwiązać problem lub zapobiec temu 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

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