Záznamy chyb Windows PowerShellu

Článek
09/24/2021

Rutiny musí předat objekt System. Management. Automation. ErrorRecord , který identifikuje chybový stav pro ukončovací a neukončující chyby.

Objekt System. Management. Automation. ErrorRecord obsahuje následující informace:

Výjimka, která popisuje chybu. Často se jedná o výjimku, kterou rutina zachytil a převádí na záznam chyby. Každý záznam chyby musí obsahovat výjimku.

Pokud rutina nezachytává výjimku, musí vytvořit novou výjimku a zvolit třídu výjimek, která nejlépe popisuje chybový stav. Nemusíte však vyvolat výjimku, protože je k ní možné přistupovat prostřednictvím vlastnosti System. Management. Automation. ErrorRecord. Exception objektu System. Management. Automation. ErrorRecord .

identifikátor chyby, který poskytuje cílené označení, které lze použít pro účely diagnostiky a Windows PowerShell skripty pro zpracování konkrétních chybových stavů s konkrétními obslužnými rutinami chyb. Každý záznam chyby musí obsahovat identifikátor chyby (viz chybový identifikátor).
Kategorie chyb, která poskytuje obecné označení, které lze použít pro diagnostické účely. Každý záznam chyby musí určovat kategorii chyb (viz kategorie chyby).
Volitelná chybová zpráva a doporučená akce (viz výměna chybové zprávy).
Volitelné informace o vyvolání rutiny, která vyvolala chybu. tyto informace jsou určené Windows PowerShell (viz zpráva o vyvolání).
Cílový objekt, který byl zpracován v okamžiku, kdy došlo k chybě. Může to být vstupní objekt nebo to může být jiný objekt, který vaše rutina zpracovává. Například pro příkaz remove-item -recurse c:\somedirectory může být chyba instance objektu FileInfo pro "c:\somedirectory\lockedfile". Informace o cílovém objektu jsou volitelné.

Identifikátor chyby

Při vytváření záznamu chyby zadejte identifikátor, který určuje chybový stav v rámci rutiny. Windows PowerShell kombinuje cílový identifikátor s názvem vaší rutiny k vytvoření plně kvalifikovaného identifikátoru chyby. K plně kvalifikovanému identifikátoru chyby lze přistupovat prostřednictvím vlastnosti System. Management. Automation. ErrorRecord. FullyQualifiedErrorId objektu System. Management. Automation. ErrorRecord . Identifikátor chyby není k dispozici samostatně. Je k dispozici pouze jako součást plně kvalifikovaného identifikátoru chyby.

Při vytváření záznamů o chybách použijte následující pokyny:

Nastavit identifikátory chyb specifické pro chybový stav Cílí na identifikátory chyb pro diagnostické účely a pro skripty, které zpracovávají konkrétní chybové stavy s konkrétními obslužnými rutinami chyb. Uživatel by měl být schopný použít identifikátor chyby k identifikaci chyby a jejího zdroje. Identifikátory chyb umožňují také vytváření sestav pro konkrétní chybové stavy z existujících výjimek, takže nové podtřídy výjimek nejsou vyžadovány.
Obecně přiřaďte různým cestám kódu různé chybové identifikátory. Výhody pro koncové uživatele od konkrétních identifikátorů. Každá cesta kódu, která volá System. Management. Automation. rutina. WriteError nebo System. Management. Automation. rutine. Throwterminatingerror * má vlastní identifikátor. Jako pravidlo definujte nový identifikátor při definování nového řetězce šablony pro chybovou zprávu a naopak. Nepoužívejte chybovou zprávu jako identifikátor.
Když publikujete kód pomocí určitého identifikátoru chyby, vytvoříte sémantiku chyb s tímto identifikátorem pro kompletní životní cyklus podpory produktu. Nepoužívejte ho znovu v kontextu, který je sémanticky odlišný od původního kontextu. Pokud se sémantika této chyby změní, vytvořte a pak použijte nový identifikátor.
Obecně byste měli použít konkrétní identifikátor chyby pouze pro výjimky konkrétního typu CLR. Pokud se změní typ výjimky nebo typ cílového objektu, vytvořte a pak použijte nový identifikátor.
Vyberte text pro identifikátor chyby, který stručně odpovídá chybě, kterou vytváříte. používejte standardní .NET Framework konvence pojmenování a psaní velkých písmen. Nepoužívejte prázdné znaky ani interpunkční znaménka. Nelokalizovat identifikátory chyb.
Nevytvářejte dynamicky identifikátory chyb nereprodukovatelným způsobem. Nepoužívejte například informace o chybě, jako je ID procesu. Identifikátory chyb jsou užitečné pouze v případě, že odpovídají identifikátorům chyb zobrazeným jinými uživateli, u kterých dochází ke stejné chybové situaci.

Kategorie chyby

Když vytvoříte záznam chyby, určete kategorii chyby pomocí jedné z konstant definovaných výčtem System. Management. Automation. ErrorCategory . Windows PowerShell používá kategorii chyb pro zobrazení informací o chybě, když uživatelé nastavili $ErrorView proměnnou na "CategoryView" .

Nepoužívejte konstantu System. Management. Automation. ErrorCategory NotSpecified . Pokud máte nějaké informace o chybě nebo o operaci, která způsobila chybu, vyberte kategorii, která nejlépe popisuje chybu nebo operaci, a to i v případě, že kategorie není perfektní shodou.

informace zobrazované Windows PowerShell se označují jako řetězec kategorie zobrazení a jsou sestaveny z vlastností třídy System. Management. Automation. Errorcategoryinfo . (Tato třída je k dispozici prostřednictvím vlastnosti Error System. Management. Automation. ErrorRecord. CategoryInfo .)

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

Následující seznam popisuje zobrazené informace:

kategorie: Windows PowerShell definovaná konstanta System. Management. Automation. ErrorCategory .
Cílový_název: ve výchozím nastavení se jedná o název objektu, který rutina zpracovala v okamžiku, kdy došlo k chybě. Nebo jiný řetězec definovaný rutinou.
TargetType: ve výchozím nastavení typ cílového objektu. Nebo jiný řetězec definovaný rutinou.
Aktivita: ve výchozím nastavení se jedná o název rutiny, která záznam chyby vytvořila. Nebo, nějaký jiný řetězec definovaný rutinou.
Důvod: ve výchozím nastavení je to typ výjimky. Nebo jiný řetězec definovaný rutinou.

Výměna chybové zprávy

Při vývoji záznamu chyby pro rutinu se výchozí chybová zpráva pro tuto chybu nachází z textu výchozí zprávy ve vlastnosti System. Exception. Message . tato vlastnost je jen pro čtení, jejíž text zprávy je určen pouze pro účely ladění (podle pokynů pro .NET Framework). Doporučujeme vytvořit chybovou zprávu, která nahrazuje nebo rozšiřuje výchozí text zprávy. Zajistěte, aby byla zpráva uživatelsky přívětivější a konkrétnější pro rutinu.

Náhradní zpráva je poskytována objektem System. Management. Automation. ErrorDetails . Použijte jeden z následujících konstruktorů tohoto objektu, protože poskytují dodatečné informace o lokalizaci, které mohou být použity Windows PowerShell.

ErrorDetails (rutina, řetězec, řetězec, objekt []): Tento konstruktor použijte, pokud je řetězec šablony řetězec prostředku ve stejném sestavení, ve kterém je rutina implementovaná, nebo pokud chcete načíst řetězec šablony pomocí přepsání metody System. Management. Automation. rutine. metodu GetResourceString .
ErrorDetails (Assembly; String; String; Object []): Tento konstruktor použijte, pokud je řetězec šablony v jiném sestavení a nenačtete ho pomocí přepsání třídy System. Management. Automation. rutina. metodu GetResourceString.

náhradní zpráva by měla být v souladu s pokyny pro návrh .NET Framework pro psaní zpráv výjimek s malým rozdílem. V pokynech se uvádí, že by měly být pro vývojáře napsány zprávy výjimek. Tyto náhradní zprávy by se měly zapsat pro uživatele rutiny.

Před voláním metod System. Management. Automation. rutine. WriteError nebo System. Management. Automation. rutine. Throwterminatingerror * je nutné přidat chybovou zprávu o nahrazení. Chcete-li přidat náhradní zprávu, nastavte vlastnost System. Management. Automation. ErrorRecord. ErrorDetails záznamu chyby. je-li tato vlastnost nastavena, Windows PowerShell zobrazí vlastnost System. Management. Automation. ErrorDetails. Message * namísto výchozího textu zprávy.

Doporučené informace o akci

Objekt System. Management. Automation. ErrorDetails může také poskytovat informace o akcích, které jsou doporučovány při výskytu chyby.

Informace o vyvolání

když rutina pomocí system. management. automation. rutiny. WriteError nebo System. management. Automation. rutina. Throwterminatingerror * nahlásí záznam chyby, Windows PowerShell automaticky přidá informace, které popisují příkaz, který byl vyvolán, když došlo k chybě. Tyto informace poskytuje objekt System. Management. Automation. Invocationinfo , který obsahuje název rutiny, která byla vyvolána příkazem, samotný příkaz a informace o kanálu nebo skriptu. Tato vlastnost je jen ke čtení.