Windows PowerShelles hibarekordok

Cikk
09/24/2021

A parancsmagnak át kell mennie egy System.Management.Automation.ErrorRecord objektumon, amely azonosítja a megszakítási és nem megszakítási hibák hiba feltételét.

A System.Management.Automation.ErrorRecord objektum a következő információkat tartalmazza:

A hibát leíró kivétel. Ez gyakran kivételt képez a parancsmag által észlelt és hibarekordba konvertált kivétel. Minden hibarekordnak tartalmaznia kell egy kivételt.

Ha a parancsmag nem észlelt kivételt, létre kell hoznia egy új kivételt, és ki kell választania a hiba feltételét legjobban leíró kivételosztályt. Nem kell azonban kivételt dobnunk, mert az a System.Management.Automation.ErrorRecord.Exception tulajdonságon keresztül érhető el a System.Management.Automation.ErrorRecord objektumban.

Egy hibaazonosító, amely egy célzott tervezőt biztosít, amelyet diagnosztikai célokra és Windows PowerShell szkriptek adott hibafeltételek adott hibakezelőkhöz való kezelésére használnak. Minden hibarekordnak tartalmaznia kell egy hibaazonosítót (lásd a hibaazonosítót).
Hibakategória, amely diagnosztikai célokra használható általános tervezőt biztosít. Minden hibarekordnak meg kell adnia egy hibakategóriát (lásd: Hibakategória).
Egy nem kötelező helyettesítő hibaüzenet és egy javasolt művelet (lásd a helyettesítő hibaüzenetet).
Nem kötelező meghívási információk a hibát kezelő parancsmagról. Ezt az információt a Windows PowerShell adja meg (lásd: Meghívási üzenet).
A hiba beestekor feldolgozott célobjektum. Ez lehet a bemeneti objektum, vagy egy másik objektum, amit a parancsmag feldolgozott. A parancs esetén például a hiba egy FileInfo objektum egy példánya remove-item -recurse c:\somedirectory lehet a "c:\somedirectory\lockedfile" mappában. A célobjektum adatai nem kötelezőek.

Hibaazonosító

Hibarekord létrehozásakor adjon meg egy azonosítót, amely a hiba feltételét jelöli a parancsmagban. Windows PowerShell a célazonosítót a parancsmag nevével kombinálva létrehoz egy teljes hibaazonosítót. A teljes hibaazonosító a System.Management.Automation.ErrorRecord.FullyQualifiedErrorId tulajdonságon keresztül érhető el a System.Management.Automation.ErrorRecord objektumban. A hibaazonosító önmagában nem érhető el. Csak a teljes hibaazonosító részeként érhető el.

A hibarekordok létrehozásakor a következő irányelvek alapján hozhat létre hibaazonosítókat:

A hiba feltételére jellemző hibaazonosítók. A hibaazonosítókat diagnosztikai célokra és olyan szkriptek számára célozza meg, amelyek adott hibafeltételeket kezelnek adott hibakezelők használatával. A felhasználónak képesnek kell lennie arra, hogy a hibaazonosítóval azonosítsa a hibát és annak forrását. A hibaazonosítók a meglévő kivételek adott hibafeltételekre vonatkozó jelentéskészítését is lehetővé teszik, így nincs szükség új kivétel-alosztályra.
Általában különböző hibaazonosítókat kell hozzárendelni különböző kódútvonalakhoz. A végfelhasználó számára előnyösek az adott azonosítók. A System.Management.Automation.Cmdlet.WriteError vagy a System.Management.Automation.Cmdlet.Throwterminatingerror* kódútvonalak gyakran saját azonosítóval rendelkezik. Szabályként határozzon meg egy új azonosítót, amikor új sablonsringet ad meg a hibaüzenethez, és fordítva. Ne használja a hibaüzenetet azonosítóként.
Ha egy adott hibaazonosítóval tesz közzé kódot, a teljes terméktámogatási életciklushoz meg kell állapítania a hibák szemantikáját ezzel az azonosítóval. Ne használja újra olyan környezetben, amely szemantikailag eltér az eredeti környezettől. Ha a hiba szemantikája megváltozik, hozzon létre, majd használjon egy új azonosítót.
Egy adott hibaazonosítót általában csak egy adott CLR-típus kivételei esetén érdemes használni. Ha a kivétel típusa vagy a célobjektum típusa megváltozik, hozzon létre, majd használjon egy új azonosítót.
Válassza ki a hibaazonosító szövegét, amely tömören megfelel a jelentésben megadott hibának. Használjon szabványos .NET-keretrendszer elnevezési és nagybetűs elnevezési konvenciókat. Ne használjon térközt vagy írásjelet. Ne honosítsa a hibaazonosítókat.
Ne hozzon létre hibaazonosítókat dinamikusan, reprodukálhatatlan módon. Ne építsen be például hibainformációt, például folyamatazonosítót. A hibaazonosítók csak akkor hasznosak, ha olyan felhasználók által látott hibaazonosítóknak felelnek meg, akik ugyanazt a hiba feltételt tapasztalják.

Hibakategória

Hibarekord létrehozásakor adja meg a hiba kategóriáját a System.Management.Automation.ErrorCategory enumerálás által meghatározott állandók egyikével. Windows PowerShell a hibakategóriát használja a hibainformációk megjelenítéséhez, amikor a felhasználók a $ErrorView változót a következőre állítják: "CategoryView" .

Kerülje a System.Management.Automation.ErrorCategory NotSpecified állandót. Ha bármilyen információja van a hibáról vagy a hibát okozó műveletről, válassza ki azt a kategóriát, amely a legjobban leírja a hibát vagy a műveletet, még akkor is, ha a kategória nem tökéletes egyezés.

A Windows PowerShell megjelenített információkat kategórianézeti sztringnek nevezzük, és a System.Management.Automation.Errorcategoryinfo osztály tulajdonságaiból épülnek fel. (Ez az osztály a System.Management.Automation.ErrorRecord.CategoryInfo tulajdonságon keresztül érhető el.)

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

Az alábbi lista a megjelenített információkat ismerteti:

Kategória: Windows PowerShell System.Management.Automation.ErrorCategory állandó.
TargetName: Alapértelmezés szerint a parancsmag által a hiba beestekor feldolgozott objektum neve. Vagy egy másik, parancsmag által definiált sztring.
TargetType: Alapértelmezés szerint a célobjektum típusa. Vagy egy másik, parancsmag által definiált sztring.
Tevékenység: Alapértelmezés szerint a hibarekordot létrehozó parancsmag neve. Vagy egy másik, parancsmag által definiált sztringet.
Ok: Alapértelmezés szerint a kivétel típusa. Vagy egy másik, parancsmag által definiált sztring.

Csere hibaüzenet

Amikor hibarekordot fejleszt egy parancsmaghoz, a hiba alapértelmezett hibaüzenete a System.Exception.Message tulajdonság alapértelmezett üzenetszövege. Ez egy csak olvasható tulajdonság, amelynek az üzenetszövege csak hibakeresési célokra szolgál (a .NET-keretrendszer megfelelően). Javasoljuk, hogy hozzon létre egy hibaüzenetet, amely lecseréli vagy kiegészíti az alapértelmezett üzenetszöveget. Az üzenet legyen felhasználóbarátabb és a parancsmagra jellemzőbb.

A helyettesítő üzenetet egy System.Management.Automation.ErrorDetails objektum biztosítja. Használja az objektum alábbi konstruktorok egyikét, mert további honosítási információkat biztosítanak, amelyek a Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): Akkor használja ezt a konstruktort, ha a sablonsztring ugyanabban a szerelvényben található erőforrássztring, amelyben a parancsmagot megvalósítják, vagy ha a sablonsztringet a System.Management.Automation.Cmdlet.GetResourceString metódus felülbírálása révén szeretné betölteni.
ErrorDetails(Assembly, String, String, Object[]): Akkor használja ezt a konstruktort, ha a sablonsztring egy másik szerelvényben található, és nem a System.Management.Automation.Cmdlet.GetResourceStringfelülbírálásán keresztül töltődik be.

A helyettesítő üzenetnek meg kell felelnie .NET-keretrendszer tervezési útmutatónak a kivételüzenetek írására, kis eltéréssel. Az irányelvek szerint a kivételüzeneteket fejlesztőknek kell megírni. Ezeket a helyettesítő üzeneteket a parancsmag felhasználója számára kell megírni.

A helyettesítő hibaüzenetet a System.Management.Automation.Cmdlet.WriteError vagy a System.Management.Automation.Cmdlet.Throwterminatingerror* metódusok előtt kell hozzáadni. Helyettesítő üzenet hozzáadásához állítsa be a hibarekord System.Management.Automation.ErrorRecord.ErrorDetails tulajdonságát. Ha ez a tulajdonság be van állítva, Windows PowerShell alapértelmezett üzenetszöveg helyett a System.Management.Automation.ErrorDetails.Message* tulajdonság jelenik meg.

Javasolt műveletinformációk

A System.Management.Automation.ErrorDetails objektum arra is képes, hogy információt nyújtson a hiba bekövetkezése esetén javasolt műveletekről.

Meghívási információk

Ha egy parancsmag a System.Management.Automation.Cmdlet.WriteError vagy a System.Management.Automation.Cmdlet.Throwterminatingerror* parancsmagot használja hibarekord jelentéséhez, a Windows PowerShell automatikusan hozzáadja az adatokat, amelyek leírják a hiba beestekor meghívott parancsot. Ezt az információt egy System.Management.Automation.Invocationinfo objektum biztosítja, amely tartalmazza a parancs által meghívott parancsmag nevét, magát a parancsot, valamint a folyamatra vagy szkriptre vonatkozó információkat. Ez a tulajdonság csak olvasható.