Doporučované pokyny pro vývoj rutin

Článek
10/07/2021

Tato část popisuje pokyny, které byste měli dodržovat při psaní rutin. Jsou rozdělené na pokyny pro navrhování rutin a pokyny pro psaní kódu rutiny. Může se stát, že tyto pokyny nejsou použitelné pro každý scénář. Pokud se ale tyto pokyny uplatní a nedodržujete tyto pokyny, můžou mít uživatelé špatný zážitek při používání vašich rutin.

Pokyny k návrhu

Při navrhování rutin pro zajištění konzistentního uživatelského prostředí mezi použitím rutin a dalších rutin by měly být dodrženy následující pokyny. Pokud najdete pokyny k návrhu, které se vztahují na vaši situaci, nezapomeňte se podívat na pravidla pro podobné pokyny v pokynech pro kód.

Použití konkrétního podstatného jména pro název rutiny (SD01)

Podstatná jména používaná v pojmenovávání rutin musí být velmi specifická, aby uživatel mohl zjistit vaše rutiny. Odprefixujte obecná podstatná jména, jako je například server, s zkrácenou verzí názvu produktu. pokud například podstatné jméno odkazuje na server, na kterém běží instance Microsoft SQL Server, použijte podstatné jméno, jako je například "SQLServer". Kombinace konkrétních podstatných jmen a krátkého seznamu schválených operací umožní uživateli rychle zjistit a předvídat funkčnost a zároveň vyhnout duplicitám mezi názvy rutin.

Chcete-li zlepšit činnost koncového uživatele, je podstatné jméno, které jste si zvolili pro název rutiny, obsahovat jednotné. Použijte například název Get-Process namísto Get-Processes . Doporučuje se dodržovat toto pravidlo pro všechny názvy rutin, a to i v případě, že rutina bude nejspíš fungovat na více než jedné položce.

Pro názvy rutin použijte velká písmena Pascal (SD02).

Pro názvy parametrů použijte velká písmena jazyka Pascal. Jinými slovy, na velká písmena první písmeno příkazu a všechny termíny použité v podstatné části. Například Clear-ItemProperty.

Pokyny pro návrh parametrů (SD03)

Rutina vyžaduje parametry, které přijmou data, na kterých musí pracovat, a parametry, které označují informace, které se používají k určení charakteristik operace. Například rutina může mít Name parametr, který přijímá data z kanálu, a rutina může mít Force parametr, který označuje, že rutina může být vynucena k provedení jeho operace. Počet parametrů, které může rutina definovat, není nijak omezený.

Použít názvy standardních parametrů

Rutina by měla používat standardní názvy parametrů, aby uživatel mohl rychle zjistit, co konkrétní parametr znamená. Pokud je vyžadován konkrétnější název, použijte název standardního parametru a zadejte konkrétnější název jako alias. Například Get-Service rutina má parametr, který má obecný název ( Name ) a konkrétnější alias ( ServiceName ). Oba výrazy lze použít k určení parametru.

Další informace o názvech parametrů a jejich datových typech najdete v tématu pokyny pro název a funkčnost parametrů rutiny.

Použít názvy parametrů v číslu

Nepoužívejte plurální názvy pro parametry, jejichž hodnota je jeden element. To zahrnuje parametry, které přijímají pole nebo seznamy, protože uživatel může dodat pole nebo seznam pouze k jednomu prvku.

Názvy parametrů plural by měly být použity pouze v těch případech, kde hodnota parametru je vždy hodnota s více prvky. V těchto případech by rutina měla ověřit, zda je zadáno více prvků, a pokud není zadáno více prvků, by měla rutina uživateli zobrazit upozornění.

Použít pro názvy parametrů velká písmena jazyka Pascal

Pro názvy parametrů použijte velká písmena jazyka Pascal. Jinými slovy velká písmena prvního písmene každého slova v názvu parametru, včetně prvního písmene názvu. Například název parametru ErrorAction používá správné zadání velkých a malých písmen. Následující názvy parametrů používají nesprávná velká písmena:

errorAction
erroraction

Parametry, které mají seznam možností

Existují dva způsoby, jak vytvořit parametr, jehož hodnota se dá vybrat ze sady možností.

Definujte typ výčtu (nebo použijte existující typ výčtu), který určuje platné hodnoty. Pak použijte typ výčtu k vytvoření parametru tohoto typu.
Přidejte atribut ValidateSet do deklarace parametru. Další informace o tomto atributu naleznete v tématu deklarace atributu ValidateSet.

Pro parametry používat standardní typy

Pro zajištění konzistence s jinými rutinami použijte standardní typy pro parametry, kde je to možné. Další informace o typech, které by měly být použity pro jiný parametr, naleznete v tématu standardní názvy parametrů rutiny a typy. toto téma obsahuje odkazy na několik témat popisujících názvy a .NET Framework typy pro skupiny standardních parametrů, jako jsou "parametry aktivit".

použití typů Strongly-Typed .NET Framework

parametry by měly být definovány jako .NET Framework typy pro zajištění lepšího ověřování parametru. Například parametry, které jsou omezeny na jednu hodnotu ze sady hodnot, by měly být definovány jako Výčtový typ. Pro podporu hodnoty identifikátoru URI (Uniform Resource Identifier) definujte parametr jako typ System. URI . Vyhněte se základním parametrům řetězce pro všechny vlastnosti textu s volným formulářem.

Použití konzistentních typů parametrů

Když je stejný parametr použit více rutinami, vždy použijte stejný typ parametru. Pokud Process je parametr například typ System. Int16 pro jednu rutinu, nevytvářejte Process parametr pro jinou rutinu typu System. Uint16 .

Parametry, které přijímají hodnoty true a false

Pokud parametr přijímá pouze true a false , definujte parametr jako typ System. Management. Automation. přepínací parametr. Parametr přepínače je považován za, true když je zadán v příkazu. pokud parametr není zahrnut v příkazu, Windows PowerShell posuzuje hodnotu parametru false . Nedefinujte logické parametry.

Pokud parametr vyžaduje rozlišení mezi 3 hodnotami: $true, $false a "Neurčeno", pak definujte parametr typu s možnou hodnotou null <bool> . K tomu, aby rutina mohla upravit logickou vlastnost objektu, obvykle dochází k nespecifikované hodnotě 3. V tomto případě "Nespecifikovaná" znamená, že nemění aktuální hodnotu vlastnosti.

Podpora polí pro parametry

Uživatelé často musí provádět stejnou operaci proti více argumentům. pro tyto uživatele by rutina měla přijmout pole jako vstup parametru, aby uživatel mohl předat argumenty do parametru jako Windows PowerShell proměnnou. Například rutina GET-Process používá pole pro řetězce, které identifikují názvy procesů, které mají být načteny.

Podpora parametru PassThru

Ve výchozím nastavení mnoho rutin, které upravují systém, jako je například rutina stop-proces , slouží jako "jímky" pro objekty a nevrací výsledek. Tato rutina by měla implementovat PassThru parametr pro vynucení, aby rutina vrátila objekt. PassThruJe-li zadán parametr, rutina vrátí objekt pomocí volání metody System. Management. Automation. rutine. WriteObject . Například následující příkaz zastaví proces Calc a předá výsledný proces do kanálu.

Stop-Process calc -passthru

Ve většině případů by měly přidat, nastavit a nové rutiny podporovat PassThru parametr.

Podpora sad parametrů

Rutina je určena k dosažení jediného účelu. Existuje však často více než jeden způsob, jak popsat operaci nebo cíl operace. Například proces může být identifikován podle názvu, podle jeho identifikátoru nebo pomocí objektu procesu. Rutina by měla podporovat všechny rozumné reprezentace svých cílů. Rutina obvykle splňuje tento požadavek zadáním sad parametrů (označovaných jako sady parametrů), které společně spolupracují. Jeden parametr může patřit do libovolného počtu sad parametrů. Další informace o sadách parametrů najdete v tématu sady parametrů rutin.

Když zadáte sady parametrů, nastavte pouze jeden parametr v sadě na ValueFromPipeline. Další informace o deklaraci atributu parametru naleznete v tématu ParameterAttribute Declaration.

Pokud jsou použity sady parametrů, je výchozí sada parametrů definována atributem rutiny . výchozí sada parametrů by měla zahrnovat parametry, které budou pravděpodobně použity v interaktivní relaci Windows PowerShell. Další informace o deklaraci atributu rutiny naleznete v tématu CmdletAttribute Declaration.

Poskytnutí zpětné vazby uživateli (SD04)

Pokyny v této části použijte k poskytnutí zpětné vazby uživateli. Tato zpětná vazba umožňuje uživateli vědět, co se děje v systému, a zajistit lepší administrativní rozhodnutí.

modul runtime Windows PowerShell umožňuje uživateli určit, jak zpracovat výstup z každého volání Write metody nastavením proměnné předvolby. Uživatel může nastavit několik proměnných předvoleb, včetně proměnné, která určuje, jestli má systém zobrazit informace a proměnnou, která určuje, jestli se má systém před provedením další akce dotazovat na uživatele.

Podpora metod WriteWarning, WriteVerbose a WriteDebug

Rutina by měla zavolat metodu System. Management. Automation. rutine. WriteWarning , když má rutina provést operaci, která může mít nezamýšlený výsledek. Například rutina by měla zavolat tuto metodu, pokud má rutina přepsat soubor, který je jen pro čtení.

Rutina by měla zavolat metodu System. Management. Automation. rutine. WriteVerbose , když uživatel vyžaduje určitou podrobnost o tom, co rutina dělá. Rutina by například měla tyto informace volat, pokud se autor rutiny domnívá, že existují scénáře, které můžou vyžadovat další informace o tom, co tato rutina dělá.

Rutina by měla zavolat metodu System.Management.Automation.Cmdlet.WriteDebug, když vývojář nebo technik podpory produktu musí pochopit, co operaci rutiny poškodí. Rutina nemusí volat metodu System.Management.Automation.Cmdlet.WriteDebug ve stejném kódu, který volá metodu System.Management.Automation.Cmdlet.WriteVerbose, protože parametr představuje obě sady Debug informací.

Podpora zápisu zápisu pro operace, které trvá dlouho

Operace rutin, které se dlouho neskončí a které nelze spustit na pozadí, by měly podporovat průběh vytváření sestav prostřednictvím pravidelných volání metody System.Management.Automation.Cmdlet.WriteProgress.

Použití hostitelských rozhraní

V některých případech musí rutina komunikovat přímo s uživatelem místo pomocí různých metod Write nebo Should podporovaných třídou System.Management.Automation.Cmdlet. V takovém případě by se měla rutina odvozovat z třídy System.Management.Automation.PSCmdlet a použít vlastnost System.Management.Automation.PSCmdlet.Host*. Tato vlastnost podporuje různé úrovně typu komunikace, včetně typů PromptForChoice, Prompt a WriteLine/ReadLine. Na nejurčitá úroveň poskytuje také způsoby čtení a zápisu jednotlivých klíčů a zpracování vyrovnávacích pamětí.

Pokud není rutina speciálně navržená pro generování grafického uživatelského rozhraní (GUI), neměla by obejít hostitele pomocí vlastnosti System.Management.Automation.PSCmdlet.Host*. Příkladem rutiny, která je navržená k vygenerování grafického uživatelského rozhraní, je rutina Out-GridView.

Poznámka

Rutiny by neměly používat rozhraní API System.Console.

Vytvoření souboru nápovědy rutiny (SD05)

Pro každé sestavení rutiny vytvořte soubor Help.xml, který obsahuje informace o rutině. Tyto informace zahrnují popis rutiny, popisy parametrů rutiny, příklady použití rutiny a další informace.

Pokyny pro kód

Při kódování rutin byste měli dodržovat následující pokyny, abyste zajistili konzistentní uživatelské prostředí mezi používáním rutin a dalších rutin. Když najdete pokyny týkající se kódu, které platí pro vaši situaci, podívejte se na pokyny k návrhu, kde najdete podobné pokyny.

Parametry kódování (SC01)

Definujte parametr deklarováním veřejné vlastnosti třídy rutiny, která je dekorována atributem Parameter. Parametry nemusí být statickými členy odvozené třídy .NET Framework pro rutinu. Další informace o deklaraci atributu Parameter najdete v tématu Deklarace atributu parametru.

Podpora Windows PowerShell cest

Cesta Windows PowerShell je mechanismus pro normalizaci přístupu k oborům názvů. Když přiřadíte Windows PowerShell parametru v rutině, může uživatel definovat vlastní "jednotku", která funguje jako zástupce konkrétní cesty. Když uživatel takovou jednotku označí, mohou se uložená data, jako jsou data v registru, používat konzistentně.

Pokud rutina umožňuje uživateli zadat soubor nebo zdroj dat, měl by definovat parametr typu System.String. Pokud je podporováno více než jedna jednotka, typ by měl být pole. Název parametru by měl být Path s aliasem PSPath . Parametr by navíc Path měl podporovat zástupné znaky. Pokud se nevyžaduje podpora zástupných znaků, definujte LiteralPath parametr.

Pokud data, která rutina čte nebo zapisuje, musí být soubor, měla by rutina přijmout vstup cesty Windows PowerShell rutina by měla použít vlastnost System.Management.Automation.Sessionstate.Path k překladu cest Windows PowerShell na cesty, které systém souborů rozpozná. Mezi konkrétní mechanismy patří následující metody:

Pokud je data, která rutina čte nebo zapisuje, pouze sada řetězců namísto souboru, měla by rutina ke čtení a zápisu používat informace o obsahu zprostředkovatele ( Content člen). Tyto informace se získávají z vlastnosti System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Tyto mechanismy umožňují ostatním datovým úložišťm podílet se na čtení a zápisu dat.

Podpora zástupných znaků

Pokud je to možné, měla by rutina podporovat zástupné znaky. Podpora zástupných znaků se vyskytuje na mnoha místech v rutině (zejména v případě, že parametr přebírá řetězec k identifikaci jednoho objektu ze sady objektů). Například ukázková Stop-Proc rutina z kurzu StopProc definuje parametr pro zpracování Name řetězců, které představují názvy procesů. Tento parametr podporuje zástupné znaky, aby uživatel mohl snadno určit procesy, které se má zastavit.

Pokud je k dispozici podpora zástupných znaků, operace rutiny obvykle vytvoří pole. V některých případech nemá smysl podporovat pole, protože uživatel může současně používat pouze jednu položku. Například rutina Set-Location nemusí podporovat pole, protože uživatel nastavuje pouze jedno umístění. V tomto případě rutina stále podporuje zástupné znaky, ale vynutí překlad do jednoho umístění.

Další informace o vzorech se zástupnými znaky najdete v tématu Podpora zástupných znaků v parametrech rutin.

Definování objektů

Tato část obsahuje pokyny pro definování objektů pro rutiny a pro rozšíření existujících objektů.

Definování standardních členů

Definujte standardní členy pro rozšíření typu objektu ve vlastním souboru Types.ps1xml (jako šablonu použijte Windows PowerShell Types.ps1xml). Standardní členy jsou definovány uzlem s názvem PSStandardMembers. Tyto definice umožňují ostatním rutinám a Windows PowerShell runtime pracovat s vaším objektem konzistentním způsobem.

Definování ObjectMembers, které se mají použít jako parametry

Pokud pro rutinu navrhujte objekt , ujistěte se, že se jeho členy mapují přímo na parametry rutin, které ho budou používat. Toto mapování umožňuje snadno odeslat objekt do kanálu a předat ho z jedné rutiny do druhé.

V existujících .NET Framework, které vrací rutiny, často chybí některé důležité nebo pohodlné členy, které vývojář nebo uživatel skriptu potřebuje. Tyto chybějící členy mohou být zvláště důležité pro zobrazení a vytvoření správných názvů členů, aby objekt mohl být správně předán do kanálu. Vytvořte vlastní soubor Types.ps1xml, který tyto požadované členy zdokumentovat. Při vytváření tohoto souboru doporučujeme následující zásady vytváření názvů: <Your_Product_Name>. Types.ps1xml.

Můžete například přidat vlastnost skriptu do typu Mode System.IO.FileInfo, aby se atributy souboru jasněji zobrazují. Kromě toho můžete do typu System.Array přidat vlastnost alias, která umožní konzistentní používání názvu této vlastnosti Count (místo Length ).

Implementace rozhraní IComparable

Implementujte rozhraní System.IComparable pro všechny výstupní objekty. Díky tomu je možné výstupní objekty snadno předát do různých rutin řazení a analýzy.

Aktualizace informací o zobrazení

Pokud zobrazení objektu neposkytuje očekávané výsledky, vytvořte vlastní <YourProductName> . Soubor Format.ps1xml pro tento objekt.

Podpora dobře definovaného vstupu kanálu (SC02)

Implementace pro střed kanálu

Implementujte rutinu za předpokladu, že bude volána zprostředkovaného kanálu (to znamená, že jiné rutiny vyprodukují svůj vstup nebo spotřebují svůj výstup). Můžete například předpokládat, že rutina , protože generuje data, se používá pouze jako první rutina Get-Process v kanálu. Vzhledem k tomu, že je tato rutina navržená pro střed kanálu, umožňuje tato rutina předchozím rutinám nebo datům v kanálu určit procesy, které se mají načíst.

Podpora vstupu z kanálu

Do každé sady parametrů pro rutinu zadejte alespoň jeden parametr, který podporuje vstup z kanálu. Podpora vstupu kanálu umožňuje uživateli načítat data nebo objekty, odesílat je do správné sady parametrů a předávat výsledky přímo do rutiny.

Parametr přijímá vstup z kanálu, pokud atribut Parameter obsahuje klíčové slovo, atribut klíčového slova nebo obě ValueFromPipeline klíčová slova v ValueFromPipelineByPropertyName deklaraci. Pokud žádný z parametrů v sadě parametrů nepodporuje klíčová slova nebo , rutina nemůže být smysluplně umístěna za jinou rutinou, protože ValueFromPipeline ValueFromPipelineByPropertyName ignoruje vstup kanálu.

Podpora metody ProcessRecord

Pokud chcete přijmout všechny záznamy z předchozí rutiny v kanálu, musí vaše rutina implementovat metodu System.Management.Automation.Cmdlet.ProcessRecord. Windows PowerShell tuto metodu volá několikrát, jednou pro každý záznam, který je odeslán do vaší rutiny.

Zápis jednotlivých záznamů do kanálu (SC03)

Když rutina vrátí objekty, měla by rutina zapsat objekty ihned po jejich vygenerování. Rutina by je neměla uchovat, aby je bylo možné do vyrovnávací paměti do kombinovaného pole. Rutiny, které přijímají objekty jako vstup, pak budou moci zpracovat, zobrazit nebo zpracovat a zobrazit výstupní objekty bez zpoždění. Rutina, která generuje výstupní objekty po jednom, by měla volat metodu System.Management.Automation.Cmdlet.WriteObject. Rutina, která generuje výstupní objekty v dávkách (například protože podkladové rozhraní API vrací pole výstupních objektů), by měla volat metodu System.Management.Automation.Cmdlet.WriteObject s druhým parametrem nastaveným na true .

Vytvořte rutiny Case-Insensitive a Case-Preserving (SC04).

Ve výchozím nastavení Windows PowerShell velká a malá písmena. Vzhledem k tomu, že se ale zabývá mnoha již existujícími systémy, Windows PowerShell zachovává případ z důvodu snadného provozu a kompatibility. Jinými slovy, pokud je znak zadán velkými písmeny, Windows PowerShell velká písmena. Aby systémy dobře fungovaly, musí rutina dodržovat tuto konvenci. Pokud je to možné, měla by fungovat bez rozlišení velkých a malých písmen. Měl by však zachovat původní případ pro rutiny, ke kterým později dojde v příkazu nebo v kanálu.

Viz také

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

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

Vytvoření rutiny Windows PowerShellu