Pokyny, které je nutné dodržovat při vývoji rutin

  • Článek

Při psaní rutin je nutné 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 nedosáhá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

Pokyny k návrhu

Při navrhování rutin je třeba dodržovat následující pokyny, které zajistí 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, podívejte se na pokyny pro kód, kde najdete podobné pokyny.

Použít jenom schválené příkazy (RD01)

Sloveso zadané v atributu Cmdlet musí pochovat z rozpoznané sady sloves poskytovaných Windows PowerShell. Nesmí to být jedno ze zakázaných synonym. Pomocí konstantních řetězců, které jsou definovány následujícími výčty, určete příkazy rutin:

Další informace o schválených názvech sloves najdete v tématu Rutiny sloves.

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 zjišťovat, co rutina dělá, a snadno zjistit schopnosti 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ého jména v rutinách odlište své rutiny od ostatních rutin. Podstatné jméno označuje prostředek, ve kterém se operace provede. Samotná operace je reprezentována operací .

Názvy rutin: Znaky, které nelze použít (RD02)

Při pojmete rutiny nepoužívejte žádné z následujících speciálních znaků.

Znak Name
# znaménko čísla
, Čárka
() Závorkách
{} Závorky
[] Závorkách
& Ampersand
- pomlčka Poznámka: Spojovník lze použít k oddělení slovesa od podstatného jména, ale nelze ho použít v rámci slovesa.
/ lomítko
\ zpětné lomítko
$ znak dolaru
^ stříška
; Středník
: Tlustého střeva
" dvojité uvozovky
' jednoduché uvozovky
<> lomené závorky
| svislý pruh
? otazník
@ při znaménku
` odškrtání zpět (diakrittika)
* 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, které se přidávají 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 najdete v tématu Běžné názvy parametrů.

Žádosti o potvrzení podpory (RD04)

Pro rutiny, které provádějí operaci, která upravuje systém, by měly volat metodu System.Management.Automation.Cmdlet.ShouldProcess*, aby si vyžádaly potvrzení, a ve speciálních případech zavolat metodu System.Management.Automation.Cmdlet.ShouldContinue*. (Metoda System.Management.Automation.Cmdlet.ShouldContinue* by měla být volána až po volání metody System.Management.Automation.Cmdlet.ShouldProcess*.)

Aby bylo možné tato volání provést, rutina musí určit, že podporuje žádosti o potvrzení nastavením klíčového SupportsShouldProcess slova atributu Cmdlet. Další informace o nastavení tohoto atributu najdete v tématu Deklarace atributu rutiny.

Poznámka

Pokud atribut Cmdlet třídy rutiny indikuje, že rutina podporuje volání metody System.Management.Automation.Cmdlet.ShouldProcess* a rutina nemůže provést volání metody System.Management.Automation.Cmdlet.ShouldProcess*, uživatel může systém neočekávaně upravit.

Pro všechny úpravy systému použijte metodu System.Management.Automation.Cmdlet.ShouldProcess*. Předvolba uživatele a WhatIf parametr ří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 WhatIf parametrem . Pokud vaše rutina volá metodu System.Management.Automation.Cmdlet.ShouldContinue*, měla by mít parametr, který obchází volání těchto dvou metod a pokračuje v Force operaci. To je důležité, protože umožňuje použití rutiny v neinteraktivních skriptech a hostitelích.

Pokud vaše rutiny tato volání podporují, uživatel může určit, jestli se má akce skutečně provést. Například rutina Stop-Process volá metodu System.Management.Automation.Cmdlet.ShouldContinue* předtím, než zastaví sadu důležitých procesů, včetně procesů System, Winlogon a Spoolsv.

Další informace o podpoře těchto metod najdete v tématu Vyžádání potvrzení.

Podpora vynucení parametru pro interaktivní relace (RD05)

Pokud se vaše rutina používá interaktivně, vždy zadejte parametr Force, který přepíše interaktivní akce, jako jsou výzvy nebo čtení řádků vstupu). To je důležité, protože umožňuje použití rutiny v neinteraktivních skriptech a hostitelích. Následující metody může implementovat interaktivní hostitel.

Výstupní objekty dokumentu (RD06)

Windows PowerShell používá objekty, které jsou zapsány do kanálu. Aby mohli uživatelé využívat výhody objektů, které jsou vraceny jednotlivými rutinami, je nutné, aby byly vráceny vrácené objekty a aby bylo nutné zdokumentovat, pro které členy těchto vrácených objektů se používají.

Pokyny pro kód

Při psaní kódu rutiny musí být dodrženy následující pokyny. Když najdete pokyny pro kód, které se týkají vaší situace, nezapomeňte se podívat na pokyny pro návrh podobných pokynů.

Odvození z rutiny nebo tříd PSCmdlet (RC01)

Rutina musí být odvozena od základní třídy System. Management. Automation. rutine nebo System. Management. Automation. PSCmdlet . rutiny odvozené od třídy System. Management. Automation. rutiny nezávisí na modulu runtime Windows PowerShell. mohou být volány přímo z libovolného jazyka Microsoft .NET Framework. rutiny odvozené od třídy System. Management. Automation. PSCmdlet závisí na modulu runtime Windows PowerShell. Proto se spouštějí v prostředí runspace.

Všechny třídy rutiny, 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.

Zadejte atribut rutiny (RC02)

aby bylo možné rutinu rozpoznat pomocí Windows PowerShell, musí být její .NET Framework třídy dekorovaná pomocí atributu rutiny. Tento atribut určuje následující funkce rutiny.

  • Pár sloves a substantivum, který identifikuje rutinu.

  • Výchozí sada parametrů, která se používá v případě, že je zadáno více sad parametrů. výchozí sada parametrů se používá, když Windows PowerShell nemá dostatek informací k určení, který parametr je nastaven na použití.

  • Určuje, zda rutina podporuje volání metody System. Management. Automation. rutine. ShouldProcess * . Tato metoda zobrazí uživateli potvrzovací zprávu předtím, než rutina provede změnu systému. Další informace o tom, jak se vyžadují žádosti o potvrzení, najdete v tématu vyžádání potvrzení.

  • Určete úroveň dopadu (nebo závažnost) akce přidružené k potvrzovací zprávě. Ve většině případů by měla být použita výchozí hodnota střední. Další informace o tom, jak úroveň dopadu ovlivňuje žádosti o potvrzení zobrazené uživateli, najdete v tématu vyžádání potvrzení.

Další informace o deklaraci atributu rutiny naleznete v tématu CmdletAttribute Declaration.

Přepsat vstupní metodu zpracování (RC03)

aby se rutina účastnila Windows PowerShell prostředí, musí přepsat alespoň jednu z následujících metod zpracování vstupu.

System. Management. Automation. rutina. BeginProcessing Tato metoda se volá jednou a používá se k poskytování funkcí předběžného zpracování.

System. Management. Automation. rutina. ProcessRecord Tato metoda se volá víckrát a používá se k poskytování funkcí záznamu podle záznamu.

System. Management. Automation. rutina. EndProcessing Tato metoda je volána jednou a slouží k poskytnutí funkce následného zpracování.

Zadejte atribut OutputType (RC04)

atribut OutputType (představený v Windows PowerShell 2,0) určuje typ .NET Framework, který rutina vrátí do kanálu. Určením typu výstupu rutin můžete objekty vracené rutinou snadněji zjistitelné jinými rutinami. Další informace o upravení třídy rutiny pomocí tohoto atributu naleznete v tématu deklarace atributu OutputType.

Neuchovávat popisovače do výstupních objektů (RC05)

Rutina nesmí uchovávat žádné popisovače pro objekty, které jsou předány metodě System. Management. Automation. rutine. WriteObject * . Tyto objekty jsou předány do další rutiny v kanálu nebo jsou používány skriptem. Pokud zachováte popisovače pro objekty, budou dvě entity vlastnit každý objekt, což způsobí chyby.

Robustní zpracování chyb (RC06)

Prostředí pro správu v podstatě detekuje a způsobuje důležité změny v systému, který spravujete. Proto je důležité, aby rutiny správně zpracovaly chyby. další informace o záznamech chyb naleznete v tématu Windows PowerShell zasílání zpráv o chybách.

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 $ErrorView proměnné prostředí na CategoryView. Možné kategorie jsou definovány výčtem System. Management. Automation. ErrorCategory .

  • vytvoří-li rutina nové vlákno a kód, který je spuštěn v tomto vlákně, vyvolá neošetřenou výjimku, Windows PowerShell nezachytí chybu a ukončí proces.

  • pokud objekt obsahuje ve svém destruktoru kód, který způsobí neošetřenou výjimku, Windows PowerShell nezachytí chybu a ukončí proces. K tomu dojde také v případě, že objekt volá metody Dispose, které způsobují neošetřenou výjimku.

nasazení rutin pomocí modulu Windows PowerShell (RC07)

vytvořte modul Windows PowerShell pro zabalení a nasazení rutin. podpora modulů se zavádí v Windows PowerShell 2,0. Sestavení, která obsahují vaše třídy rutiny, můžete použít přímo jako soubory binárních modulů (to je velmi užitečné při testování rutin), nebo můžete vytvořit manifest modulu, který odkazuje na sestavení rutiny. (Můžete také přidat existující sestavení modulu snap-in při použití modulů.) další informace o modulech najdete v tématu vytváření Windows PowerShell modulu.

Viz také

Doporučované pokyny pro vývoj rutin

Pokyny, které byste měli zvážit při vývoji rutin

Vytvoření rutiny Windows PowerShellu