Pokyny, které je nutné dodržovat při vývoji rutin
Při psaní rutin je potřeba dodržovat následující pokyny. Jsou rozdělené do pokynů pro navrhování rutin a pokynů pro psaní kódu rutiny. Pokud tyto pokyny nedodržíte, vaše rutiny můžou selhat a uživatelé můžou mít při používání rutin špatné prostředí.
V tomto tématu
Pokyny k návrhu
Pokyny pro kód
odvození z rutin nebo tříd PSCmdlet (RC01)
Pokyny k návrhu
Při navrhování rutin je potřeba dodržovat následující pokyny, aby se zajistilo konzistentní uživatelské prostředí mezi používáním rutin a dalších rutin. Když najdete pokyny k návrhu, které platí pro vaši situaci, nezapomeňte se podívat na pokyny pro kód pro podobné pokyny.
Použít pouze schválené příkazy (RD01)
Příkaz zadaný v atributu rutiny musí pocházet z rozpoznané sady sloves poskytovaných prostředím Windows PowerShell. Nesmí se jednat o jedno ze zakázaných synonym. K určení příkazů rutin použijte konstantní řetězce, které jsou definovány následujícími výčty:
Další informace o schválených názvech sloves naleznete v tématu Rutiny příkazy.
Uživatelé potřebují sadu zjistitelných a očekávaných názvů rutin. Použijte odpovídající příkaz, aby uživatel mohl rychle posoudit, co rutina dělá, a snadno zjišťovat možnosti systému. Například následující příkaz příkazového řádku získá seznam všech příkazů v systému, jejichž názvy začínají na "Start": Get-Command Start-*. Pomocí podstatných jmen v rutinách odlište rutiny od jiných rutin. Podstatné jméno označuje prostředek, na kterém bude operace provedena. Samotná operace je reprezentována slovesem.
Názvy rutin: Znaky, které nelze použít (RD02)
Při pojmenování rutin nepoužívejte žádný z následujících speciálních znaků.
| Znak | Název |
|---|---|
| # | znaménko čísla |
| , | čárka |
| () | závorky |
| {} | šle |
| [] | závorky |
| & | ampersand |
| - | pomlčka Poznámka: Spojovník lze použít k oddělení slovesa od podstatného jména, ale nelze jej použít v rámci podstatného jména nebo ve slovesu. |
| / | Lomítko |
| \ | zpětné lomítko |
| $ | znak dolaru |
| ^ | karetka |
| ; | středník |
| : | tračník |
| " | dvojitá uvozovka |
| ' | jednoduchá uvozovka |
| <> | úhlové závorky |
| | | svislý pruh |
| ? | otazník |
| @ | at sign |
| ` | zadní zaškrtnutí (zvýraznění hrobu) |
| * | hvězdička |
| % | znak procenta |
| + | znaménko plus |
| = | rovnítko |
| ~ | tilda |
Názvy parametrů, které nelze použít (RD03)
Windows PowerShell poskytuje společnou sadu parametrů pro všechny rutiny a další parametry přidané v konkrétních situacích. Při navrhování vlastních rutin nemůžete použít následující názvy: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction a Verbose. Další informace o těchto parametrech naleznete v tématu běžné názvy parametrů.
Žádosti o potvrzení podpory (RD04)
U rutin, které provádějí operaci, která upravuje systém, by měly volat metodu System.Management.Automation.Automation.ByProcess* metodu vyžádat potvrzení. Ve zvláštních případech volají metodu System.Management.Automation.Cmdlet.ShouldContinue*. (Metoda System.Management.Automation.Cmdlet.ShouldContinue* by měla být volána až po zavolání metody System.Management.Automation.Cmdlet.ShouldProcess*.)
Aby bylo možné tato volání provést, musí rutina určit, že podporuje žádosti o potvrzení nastavením klíčového slova SupportsShouldProcess atributu Rutina. Další informace o nastavení tohoto atributu naleznete v tématu Deklarace atributu rutiny.
Poznámka:
Pokud atribut Rutina třídy rutiny označuje, že rutina podporuje volání System.Management.Automation.Automation.Cmdlet.ShouldProcess* metoda a rutina se nezdaří provést volání System.Management.Automation.Cmdlet.ShouldProcess* metoda, může uživatel neočekávaně změnit systém.
Pro všechny úpravy systému použijte metodu System.Management.Automation.Cmdlet.ShouldProcess*. Předvolba uživatele a parametr WhatIf řídí metodu System.Management.Automation.Cmdlet.ShouldProcess*. Naproti tomu volání System.Management.Automation.Cmdlet.ShouldContinue* provádí další kontrolu potenciálně nebezpečných úprav. Tato metoda není řízena žádnou předvolbou uživatele ani parametrem WhatIf. Pokud vaše rutina volá metodu System.Management.Automation.Cmdlet.ShouldContinue*, měla by mít Force parametr, který obchází volání těchto dvou metod a který pokračuje s operací. To je důležité, protože umožňuje, aby se vaše rutina používala v neinteraktivních skriptech a hostitelích.
Pokud vaše rutiny podporují tato volání, může uživatel určit, jestli se má akce skutečně provést. Například rutina Stop-Process volá metodu System.Management.Automation.Cmdlet.ShouldContinue* před zastavením sady důležitých procesů, včetně procesů System, Winlogon a Spoolsv.
Další informace o podpoře těchto metod naleznete v tématu Žádost o potvrzení.
Parametr Vynucení podpory pro interaktivní relace (RD05)
Pokud se vaše rutina používá interaktivně, vždy zadejte parametr Force k přepsání interaktivních akcí, jako jsou výzvy nebo čtení řádků vstupu). To je důležité, protože umožňuje, aby se vaše rutina používala v neinteraktivních skriptech a hostitelích. Interaktivní hostitel může implementovat následující metody.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.PSHostUserInterface.PromptForChoice
System.Management.Automation.Host.IHostUISupportsMultipleChoiceSelection.PromptForChoice
System.Management.Automation.Host.PSHostUserInterface.PromptForCredential*
System.Management.Automation.Host.PSHostUserInterface.ReadLine*
System.Management.Automation.Host.PSHostUserInterface.ReadLineAsSecureString*
Výstupní objekty dokumentu (RD06)
Windows PowerShell používá objekty, které jsou zapsané do kanálu. Aby uživatelé mohli využívat výhod objektů vrácených jednotlivými rutinami, musíte zdokumentovat vrácené objekty a musíte zdokumentovat, k čemu se používají členové vrácených objektů.
Pokyny pro kód
Při psaní kódu rutiny je nutné dodržovat následující pokyny. Když najdete vodítko kódu, které platí pro vaši situaci, nezapomeňte se podívat na pokyny k návrhu podobných pokynů.
Odvození z tříd Rutiny nebo PSCmdlet (RC01)
Rutina musí být odvozena z System.Management.Automation.Cmdlet nebo System.Management.Automation.PSCmdlet základní třídy. Rutiny odvozené z třídy System.Management.Automation.Cmdlet nezávisí na modulu runtime Windows PowerShellu. Mohou být volána přímo z libovolného jazyka Rozhraní Microsoft .NET Framework. Rutiny odvozené z třídy System.Management.Automation.PSCmdlet závisí na modulu runtime Prostředí Windows PowerShell. Proto se spustí v rámci runspace.
Všechny třídy rutin, které implementujete, musí být veřejné třídy. Další informace o těchto třídách rutin najdete v tématu Přehled rutin.
Zadání atributu rutiny (RC02)
Aby byla rutina rozpoznána prostředím Windows PowerShell, musí být její třída rozhraní .NET Framework upravena atributem Rutina. Tento atribut určuje následující funkce rutiny.
Dvojice sloves a podstatných jmen, která identifikuje rutinu.
Výchozí sada parametrů, která se používá při zadání více sad parametrů. Výchozí sada parametrů se používá, když Windows PowerShell nemá dostatek informací k určení, který parametr se má použít.
Označuje, jestli rutina podporuje volání System.Management.Automation.Cmdlet.ShouldProcess* metoda. Tato metoda zobrazí uživateli potvrzovací zprávu před provedením změny v systému. Další informace o tom, jak se provádějí žádosti o potvrzení, najdete v tématu Žádost o potvrzení.
Uveďte úroveň dopadu (nebo závažnost) akce přidružené k potvrzovací zprávě. Ve většině případů by se měla použít výchozí hodnota Střední. Další informace o tom, jak úroveň dopadu ovlivňuje žádosti o potvrzení zobrazené uživateli, najdete v tématu Žádost o potvrzení.
Další informace o deklarování atributu rutiny naleznete v tématu RutinaAttribute Deklarace.
Přepsání metody zpracování vstupu (RC03)
Aby se rutina účastnila prostředí Windows PowerShell, musí přepsat alespoň jednu z následujících metod zpracování vstupu .
System.Management.Automation.Cmdlet.BeginProcessing Tato metoda se nazývá jednorázově a slouží k poskytování funkcí předběžného zpracování.
System.Management.Automation.Cmdlet.ProcessRecord Tato metoda se volá vícekrát a používá se k poskytování funkcí záznamu po záznamu.
System.Management.Automation.Cmdlet.EndProcessing Tato metoda se nazývá jednorázově a používá se k poskytování funkcí následného zpracování.
Určení atributu OutputType (RC04)
Atribut OutputType (zavedený v prostředí Windows PowerShell 2.0) určuje typ rozhraní .NET Framework, který vaše rutina vrátí do kanálu. Zadáním výstupního typu rutin nastavíte, aby objekty vrácené rutinou byly zjistitelnější jinými rutinami. Další informace o dekorování třídy rutiny pomocí tohoto atributu naleznete v tématu OutputType Attribute Deklarace.
Nezachovávejte popisovače výstupních objektů (RC05)
Rutina by neměla uchovávat žádné popisovače objektům, které jsou předány metodě System.Management.Automation.Cmdlet.WriteObject*. Tyto objekty se předávají další rutině v kanálu nebo jsou používány skriptem. Pokud si zachováte popisovače objektů, budou každý objekt vlastnit dvě entity, což způsobí chyby.
Robustní zpracování chyb (RC06)
Prostředí pro správu ze své podstaty detekuje a provádí v systému, který spravujete, důležité změny. Proto je důležité, aby rutiny správně zpracovávaly chyby. Další informace o záznamech chyb najdete v tématu zasílání zpráv o chybách prostředí Windows PowerShell .
Pokud chyba zabrání rutině pokračovat ve zpracování dalších záznamů, jedná se o ukončující chybu. Rutina musí volat metodu System.Management.Automation.Cmdlet.ThrowTerminatingError*, která odkazuje na System.Management.Automation.ErrorRecord objektu. Pokud rutina výjimku nezachytí, modul runtime Windows PowerShellu vyvolá ukončující chybu, která obsahuje méně informací.
V případě neukončující chyby, která nezastaví operaci u dalšího záznamu přicházejícího z kanálu (například záznam vytvořený jiným procesem), musí rutina volat metodu System.Management.Automation.Cmdlet.WriteError*, která odkazuje na System.Management.Automation.ErrorRecord objektu. Příkladem neukončující chyby je chyba, ke které dochází v případě, že se určitý proces nepodaří zastavit. Volání metody System.Management.Automation.Cmdlet.WriteError* umožňuje uživateli konzistentně provádět požadované akce a uchovávat informace pro konkrétní akce, které selžou. Rutina by měla zpracovávat každý záznam co nejstranněji.
Objekt System.Management.Automation.ErrorRecord, na který odkazuje System.Management.Automation.Cmdlet.ThrowTerminatingError* a System.Management.Automation.Cmdlet.WriteError* metody vyžadují výjimku v jejím jádru. Při určování výjimky, která se má použít, postupujte podle pokynů pro návrh rozhraní .NET Framework. Pokud je chyba séanticky stejná jako existující výjimka, použijte tuto výjimku nebo ji odvodit. V opačném případě odvodit novou výjimku nebo hierarchii výjimek přímo z System.Exception typ.
Objekt System.Management.Automation.ErrorRecord také vyžaduje kategorii chyb, která seskupuje chyby pro uživatele. Uživatel může zobrazit chyby založené na kategorii nastavením hodnoty proměnné prostředí $ErrorView na CategoryView. Možné kategorie jsou definovány System.Management.Automation.ErrorCategory výčtu.
Pokud rutina vytvoří nové vlákno a kód spuštěný v daném vlákně vyvolá neošetřenou výjimku, Windows PowerShell chybu nezachytí a proces ukončí.
Pokud má objekt v jeho destruktoru kód, který způsobuje neošetřenou výjimku, Windows PowerShell chybu nezachytí a proces ukončí. K tomu dochází také v případě, že objekt volá Dispose metody, které způsobují neošetřenou výjimku.
Použití modulu Windows PowerShell k nasazení rutin (RC07)
Vytvořte modul Windows PowerShellu pro zabalení a nasazení rutin. Podpora modulů je zavedena ve Windows PowerShellu 2.0. Sestavení, která obsahují třídy rutiny, můžete použít přímo jako binární soubory modulů (to je velmi užitečné při testování rutin) nebo můžete vytvořit manifest modulu, který odkazuje na sestavení rutin. (Existující sestavení modulu snap-in můžete přidat také při použití modulů.) Další informace o modulech najdete v tématu Zápis modulu Prostředí Windows PowerShell.
