Pokyny pro poradenský vývoj

Tato část popisuje pokyny, které byste měli zvážit, abyste zajistili dobré vývojové a uživatelské prostředí. Někdy se můžou použít a někdy ne.

Pokyny k návrhu

Při návrhu rutin by se měly zvážit následující pokyny. 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.

Podpora parametru InputObject (AD01)

Vzhledem k tomu, že Prostředí Windows PowerShell pracuje přímo s objekty rozhraní Microsoft .NET Framework, je často k dispozici objekt rozhraní .NET Framework, který přesně odpovídá typu, který uživatel potřebuje k provedení konkrétní operace. InputObject je standardní název parametru, který jako vstup přebírá takový objekt. Například ukázková Stop-Proc rutina v kurzu StopProc definuje InputObject parametr typu Process, který podporuje vstup z kanálu. Uživatel může získat sadu procesních objektů, manipulovat s nimi a vybrat přesné objekty, které se mají zastavit, a předat je přímo do rutiny Stop-Proc .

Podpora vynuceného parametru (AD02)

Rutina někdy potřebuje chránit uživatele před provedením požadované operace. Taková rutina by měla podporovat parametr Force , který uživateli umožní tuto ochranu přepsat, pokud má uživatel oprávnění k provedení operace.

Například rutina Remove-Item obvykle neodebere soubor jen pro čtení. Tato rutina ale podporuje parametr Force , aby uživatel mohl vynutit odebrání souboru jen pro čtení. Pokud uživatel již má oprávnění k úpravě atributu jen pro čtení a uživatel odebere soubor, použití parametru Force zjednodušuje operaci. Pokud ale uživatel nemá oprávnění k odebrání souboru, nemá parametr Force žádný vliv.

Zpracování přihlašovacích údajů přes Windows PowerShell (AD03)

Rutina by měla definovat Credential parametr představující přihlašovací údaje. Tento parametr musí být typu System.Management.Automation.PSCredential a musí být definován pomocí deklarace atributu Credential. Tato podpora automaticky vyzve uživatele k zadání uživatelského jména, hesla nebo obojího, pokud nejsou přímo zadány úplné přihlašovací údaje. Další informace o atributu Credential naleznete v tématu Deklarace atributu credential.

Podpora parametrů kódování (AD04)

Pokud vaše rutina čte nebo zapisuje text do binárního formátu nebo z binárního formátu, například zápis do souboru nebo čtení ze souboru v systému souborů, musí mít rutina parametr Kódování, který určuje, jak je text kódován v binární podobě.

Testovací rutiny by měly vrátit logickou hodnotu (AD05)

Rutiny, které provádějí testy na svých prostředcích, by měly vrátit do kanálu typ System.Boolean , aby je bylo možné použít v podmíněných výrazech.

Pokyny pro kód

Při psaní kódu rutiny byste měli zvážit následující pokyny. Když najdete vodítko, které platí pro vaši situaci, nezapomeňte se podívat na pokyny k návrhu podobných pokynů.

Postupujte podle konvencí pojmenování tříd rutiny (AC01)

Když budete postupovat podle standardních konvencí vytváření názvů, zpřístupníte rutiny a pomůžete uživateli přesně pochopit, co rutiny dělají. Tento postup je zvlášť důležitý pro ostatní vývojáře používající Windows PowerShell, protože rutiny jsou veřejné typy.

Definování rutiny ve správném oboru názvů

Obvykle definujete třídu pro rutinu v oboru názvů rozhraní .NET Framework, který připojuje .Commands k oboru názvů, který představuje produkt, ve kterém je tato rutina spuštěna. Například rutiny, které jsou součástí Windows PowerShellu Microsoft.PowerShell.Commands , jsou definovány v oboru názvů.

Pojmenujte třídu rutiny tak, aby odpovídala názvu rutiny.

Když pojmenujete třídu rozhraní .NET Framework, která implementuje rutinu, pojmenujte třídu <Verb><Noun>Command, kde nahradíte <Verb> zástupné <Noun> symboly slovesem a podstatným jménem použitým pro název rutiny. Například rutina Get-Process je implementována třídou s názvem GetProcessCommand.

Pokud žádný vstup kanálu přepsat BeginProcessing Metoda (AC02)

Pokud vaše rutina nepřijímá vstup z kanálu, mělo by se zpracování implementovat v metodě System.Management.Automation.Cmdlet.BeginProcessing . Použití této metody umožňuje prostředí Windows PowerShell udržovat pořadí mezi rutinami. První rutina v kanálu vždy vrátí své objekty předtím, než zbývající rutiny v kanálu dostanou šanci zahájit jejich zpracování.

Zpracování zastavení požadavků přepsání Metody StopProcessing (AC03)

Přepište metodu System.Management.Automation.Cmdlet.StopProcessing , aby rutina zvládla signál stop. Dokončení operace některých rutin trvá dlouho a umožňují dlouhou dobu předávat mezi voláními modulu runtime Windows PowerShellu, například když rutina blokuje vlákno v dlouhotrvajících voláních RPC. To zahrnuje rutiny, které volání metody System.Management.Automation.Cmdlet.WriteObject , metody System.Management.Automation.Cmdlet.WriteError a dalších mechanismů zpětné vazby, které mohou trvat dlouhou dobu. V těchto případech může uživatel muset těmto rutinám odeslat signál stop.

Implementace rozhraní IDisposable (AC04)

Pokud má vaše rutina objekty, které nejsou uvolněny (zapsané do kanálu) metodou System.Management.Automation.ProcessRecord , může vaše rutina vyžadovat další odstranění objektu. Pokud například vaše rutina otevře popisovač souboru v metodě System.Management.Automation.Automation.BeginProcessing a nechá popisovač otevřený pro použití metodou System.Management.Automation.Cmdlet.ProcessRecord , musí být tento popisovač uzavřen na konci zpracování.

Modul runtime Prostředí Windows PowerShell nevolá vždy metodu System.Management.Automation.Cmdlet.EndProcessing . Metoda System.Management.Automation.Cmdlet.EndProcessing se například nemusí volat, pokud je rutina zrušena uprostřed operace nebo pokud dojde k ukončovací chybě v jakékoli části rutiny. Proto by třída rozhraní .NET Framework pro rutinu, která vyžaduje vyčištění objektu, měla implementovat kompletní model rozhraní System.IDisposable , včetně finalizátoru, aby modul runtime Prostředí Windows PowerShell mohl volat metody System.Management.Automation.Cmdlet.EndProcessing a System.IDisposable.Dispose* na konci zpracování.

Použití typů parametrů popisných pro serializaci (AC05)

Chcete-li podporovat spuštění rutiny na vzdálených počítačích, použijte typy, které lze serializovat v klientském počítači a pak dosazovat na serverový počítač. Následující typy jsou popisné pro serializaci.

Primitivní typy:

• Bajt, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 a UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri a Version.
• Char, String, XmlDocument.

Předdefinované rehydratable typy:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PsCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Další typy:

• Řetězec zabezpečení
• Kontejnery (seznamy a slovníky výše uvedeného typu)

Použití řetězce SecureString pro citlivá data (AC06)

Při zpracování citlivých dat vždy použijte datový typ System.Security.SecureString . To může zahrnovat vstup kanálu do parametrů a také vrácení citlivých dat do kanálu.

I když .NET doporučuje používat SecureString pro nový vývoj, PowerShell nadále podporuje třídu SecureString kvůli zpětné kompatibilitě. Použití řetězce SecureString je stále bezpečnější než použití řetězce prostého textu. PowerShell stále spoléhá na typ SecureString , aby se zabránilo náhodnému vystavení obsahu konzole nebo v protokolech. Řetězec SecureString používejte pečlivě, protože jej lze snadno převést na řetězec ve formátu prostého textu. Úplnou diskuzi o používání secureString naleznete v dokumentaci ke třídě System.Security.SecureString.

Viz také

požadovaných pokynů pro vývoj

důrazně doporučujeme pokyny pro vývoj

psaní rutiny Prostředí Windows PowerShell