Sdílet prostřednictvím

Write-Error

Modul:
Microsoft.PowerShell.Utility Module

Zapíše objekt do datového proudu chyby.

Syntaxe

NoException (Výchozí) 

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

Description

Rutina Write-Error deklaruje neukončující chybu. Ve výchozím nastavení se chyby odesílají ve streamu chyb do hostitelského programu, který se má zobrazit, spolu s výstupem.

Pokud chcete napsat neukončující chybu, zadejte řetězec chybové zprávy, ErrorRecord objektu nebo objekt Výjimka. K naplnění záznamu chyby použijte další parametry Write-Error.

Neukončující chyby zapisují chybu do datového proudu chyb, ale nezastavují zpracování příkazů. Pokud je u jedné položky v kolekci vstupních položek deklarována neukončující chyba, příkaz bude i nadále zpracovávat ostatní položky v kolekci.

Chcete-li deklarovat ukončovací chybu, použijte klíčové slovo throw. Další informace najdete v tématu about_Throw.

Příklady

Příklad 1: Zápis chyby pro objekt RegistryKey

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

Tento příkaz deklaruje neukončující chybu, když rutina Get-ChildItem vrátí objekt Microsoft.Win32.RegistryKey, například objekty v HKLM: nebo HKCU: jednotky poskytovatele registru PowerShellu.

Příklad 2: Napsání chybové zprávy do konzoly

Write-Error "Access denied."

Tento příkaz deklaruje neukončující chybu a zapíše chybu "Přístup odepřen". Příkaz k zadání zprávy používá parametr Message, ale vynechá nepovinný název parametru Message.

Příklad 3: Zapište do konzoly chybu a zadejte kategorii.

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

Tento příkaz deklaruje neukončující chybu a určuje kategorii chyb.

Příklad 4: Zápis chyby pomocí objektu výjimky

$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."

Tento příkaz používá objekt Exception k deklaraci neukončující chyby.

První příkaz používá k vytvoření objektu System.Exception tabulku hash. Uloží objekt výjimky do proměnné $E. K vytvoření libovolného objektu typu, který má konstruktor null, můžete použít tabulku hash.

Druhý příkaz používá rutinu Write-Error k deklaraci neukončující chyby. Hodnota parametru exception je objekt Exception v proměnné .

Parametry

-Category

Určuje kategorii chyby. Výchozí hodnota je Nezadaná. Přijatelné hodnoty pro tento parametr jsou:

  • Nespecifikováno
  • Chyba otevření
  • ZavřítChyba
  • Chyba zařízení
  • Zjištěno zablokování.
  • InvalidArgument
  • Neplatná data
  • Neplatná operace
  • Neplatný výsledek
  • NeplatnýTyp
  • Chyba metadat
  • Není implementováno
  • Nenainstalováno
  • ObjectNotFound
  • OperaceStopped
  • Časový limit operace
  • Chyba syntaxe
  • ParserError
  • Odepření povolení
  • Zaneprázdněný zdroji
  • Prostředek existuje
  • ResourceUnavailable
  • Chyba čtení
  • Chyba zápisu
  • Pochází zStdErr
  • Chyba zabezpečení
  • Chyba protokolu
  • ConnectionError
  • Chyba ověřování
  • Překročené limity
  • Překročen limit
  • NotEnabled

Informace o kategoriích chyb naleznete v tématu Výčtu ErrorCategory.

Vlastnosti parametru

Typ:ErrorCategory
Default value:NotSpecified
Přípustné hodnoty: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
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

NoException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
WithException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-CategoryActivity

Určuje akci, která způsobila chybu.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Aktivita

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-CategoryReason

Určuje, jak nebo proč aktivita způsobila chybu.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Důvod

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-CategoryTargetName

Určuje název objektu, který byl zpracován při výskytu chyby.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Cílový název

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-CategoryTargetType

Určuje typ objektu, který byl zpracován při výskytu chyby.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Typ cíle

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-ErrorId

Určuje řetězec ID pro identifikaci chyby. Řetězec by měl být jedinečný pro chybu.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

NoException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
WithException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-ErrorRecord

Určuje objekt záznamu chyby, který představuje chybu. K popisu chyby použijte vlastnosti objektu.

Pokud chcete vytvořit objekt záznamu chyby, použijte rutinu New-Object nebo získejte objekt záznamu o chybě z pole v $Error automatické proměnné.

Vlastnosti parametru

Typ:ErrorRecord
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

ErrorRecord
Position:0
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Exception

Určuje objekt výjimky, který představuje chybu. K popisu chyby použijte vlastnosti objektu.

K vytvoření objektu výjimky použijte tabulku hash nebo použijte rutinu New-Object.

Vlastnosti parametru

Typ:Exception
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

WithException
Position:0
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Message

Určuje text zprávy chyby. Pokud text obsahuje mezery nebo speciální znaky, uzavřete ho do uvozovek. Můžete také převést řetězec zprávy na Write-Error.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Msg

Sady parametrů

NoException
Position:0
Povinné:True
Hodnota z kanálu:True
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
WithException
Position:0
Povinné:False
Hodnota z kanálu:True
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-RecommendedAction

Určuje akci, kterou má uživatel provést, aby chybu vyřešil nebo zabránil.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-TargetObject

Určuje objekt, který byl zpracován při výskytu chyby. Zadejte objekt, proměnnou obsahující objekt nebo příkaz, který objekt získá.

Vlastnosti parametru

Typ:Object
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

NoException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False
WithException
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

CommonParameters

Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.

Vstupy

String

Řetězec, který obsahuje chybovou zprávu pro tuto rutinu, můžete zamísťovat.

Výstupy

None

Tento cmdlet nevrátí žádný výstup. Zapisuje se pouze do datového proudu chybové zprávy.

Poznámky

Write-Error nezmění hodnotu $? automatické proměnné, proto nezpůsobí ukončující chybový stav. Chcete-li signalizovat ukončující chybu, použijte metodu $PSCmdlet.WriteError().