Pokyny a osvědčené postupy pro publikování v PowerShellGallery

Tento článek popisuje doporučené kroky používané microsoftovými týmy k zajištění toho, aby se balíčky publikované v galerii Prostředí PowerShell široce přijímaly a poskytovaly uživatelům vysokou hodnotu na základě toho, jak Galerie Prostředí PowerShell zpracovává data manifestu a zpětnou vazbu od velkého počtu uživatelů galerie Prostředí PowerShell. Balíčky publikované podle těchto pokynů budou pravděpodobně nainstalovány, důvěryhodné a přilákají více uživatelů.

Níže jsou uvedeny pokyny pro to, co dělá dobrý balíček Galerie Prostředí PowerShell, jaká volitelná nastavení manifestu jsou nejdůležitější, vylepšení kódu s zpětnou vazbou od počátečních revidujících a analyzátoru skriptů PowerShellu, správa verzí modulu, dokumentace, testy a příklady pro použití toho, co jste sdíleli. Velká část této dokumentace se řídí pokyny pro publikování vysoce kvalitních modulů prostředků DSC.

Mechanismy publikování balíčku do galerie Prostředí PowerShell najdete v tématu Vytvoření a publikování balíčku.

Vítáme zpětnou vazbu k těmto pokynům. Pokud máte zpětnou vazbu, otevřete problémy v našem úložišti dokumentace GitHubu.

Osvědčené postupy pro publikování balíčků

Následující osvědčené postupy jsou to, co uživatelé položek Galerie Prostředí PowerShell říkají, jsou důležité a jsou uvedeny v nominálním pořadí priority. Balíčky, které se řídí těmito pokyny, jsou mnohem pravděpodobnější, že budou staženy a přijaty jinými uživateli.

• Použití psScriptAnalyzeru
• Zahrnout dokumentaci a příklady
• Reakce na zpětnou vazbu
• Poskytnutí modulů místo skriptů
• Zadání odkazů na web projektu
• Označení balíčku kompatibilními platformami PSEdition
• Zahrnutí testů do modulů
• Zahrnutí a/nebo odkaz na licenční podmínky
• Podepsání kódu
• Postupujte podle pokynů pro správu verzí SemVer
• Použití běžných značek, jak je uvedeno v běžných značkách galerie PowerShellu
• Testování publikování pomocí místního úložiště
• Použití modulu PowerShellGet k publikování

Každá z těchto částí je stručně popsána v následujících částech.

Použití psScriptAnalyzeru

PSScriptAnalyzer je bezplatný nástroj pro analýzu statického kódu, který funguje na kódu PowerShellu. PSScriptAnalyzer identifikuje nejběžnější problémy, ke kterým dochází v kódu PowerShellu, a často se doporučuje, jak tento problém vyřešit. Nástroj je snadno použitelný a kategorizuje problémy jako chyby (závažné, musí být vyřešeny), upozornění (je třeba je zkontrolovat a mělo by být vyřešeno) a informace (stojí za to se podívat na osvědčené postupy). Všechny balíčky publikované v galerii Prostředí PowerShell se zkontrolují pomocí PSScriptAnalyzer a všechny chyby se ohlásí zpět vlastníkovi a musí být vyřešeny.

Osvědčeným postupem je spustit Invoke-ScriptAnalyzer s -Recurse a upozorněním na -Severity.

Zkontrolujte výsledky a ujistěte se, že:

• Všechny chyby se opravují nebo řeší v dokumentaci.
• Všechna upozornění se prověřují a řeší tam, kde je to možné.

Uživatelům, kteří stahují balíčky z galerie Prostředí PowerShell, důrazně doporučujeme spustit PSScriptAnalyzer a vyhodnotit všechny chyby a upozornění. Uživatelé budou s velkou pravděpodobností kontaktovat vlastníky balíčků, pokud zjistí, že PSScriptAnalyzerdošlo k chybě . Pokud existuje přesvědčivý důvod, proč má váš balíček zachovat kód označený příznakem chyby, přidejte tyto informace do dokumentace, abyste nemuseli zodpovědět stejnou otázku mnohokrát.

Zahrnout dokumentaci a příklady

Dokumentace a příklady představují nejlepší způsob, jak zajistit, aby uživatelé mohli využívat jakýkoli sdílený kód.

Dokumentace je nejužitečnější věcí, kterou je potřeba zahrnout do balíčků publikovaných v galerii Prostředí PowerShell. Uživatelé obvykle obcházejí balíčky bez dokumentace, protože alternativou je přečíst kód, abyste pochopili, co je balíček a jak ho používat. K dispozici je několik článků o tom, jak poskytnout dokumentaci k balíčkům PowerShellu, mezi které patří:

• Pokyny k poskytování nápovědy najdete v nápovědy k vytváření rutin.
• Vytvoření nápovědy k rutinám, což je nejlepší přístup pro jakýkoli skript, funkci nebo rutinu PowerShellu. Informace o tom, jak vytvořit nápovědu k rutině, začněte Jak napsat nápovědu k rutině. Nápovědu ke skriptu přidáte o nápovědě založené na komentářích.
• Mnoho modulů obsahuje také dokumentaci v textovém formátu, jako jsou soubory MarkDown. To může být užitečné zejména v případě, že je na GitHubu web projektu, kde Markdown je silně používaný formát. Osvědčeným postupem je použít Markdownu s příchutí GitHubu.

Příklady ukazují uživatelům, jak se má balíček použít. Mnoho vývojářů řekne, že se před dokumentací podívá na příklady, abyste pochopili, jak něco použít. Nejlepší typy příkladů ukazují základní použití a simulovaný realistický případ použití a kód je dobře okomentován. Příklady modulů publikovaných v galerii Prostředí PowerShell by měly být ve složce Příklady v kořenovém adresáři modulu.

Dobrý vzor příkladů najdete v modulu PSDscResource ve složce Examples\RegistryResource. Existují čtyři ukázkové případy použití se stručným popisem v horní části každého souboru, který dokumentuje, co je demonstrováno.

Správa závislostí

Je důležité zadat moduly, na které je modul závislý v manifestu modulu. To koncovému uživateli umožní, aby si nemusel dělat starosti s instalací správných verzí modulů, na kterých závisí váš uživatel. Pokud chcete určit závislé moduly, měli byste použít požadované pole modulu v manifestu modulu. Tím se všechny uvedené moduly načtou do globálního prostředí před importem modulu, pokud ještě nebyly načteny. Některé moduly už můžou být například načteny jiným modulem. Je také možné zadat konkrétní verzi, která se má načíst, pomocí pole RequiredVersion místo pole ModuleVersion. Při použití ModuleVersionse načte nejnovější verze dostupná s minimální zadanou verzí. Pokud nepoužíváte pole RequiredVersion, je důležité určit konkrétní verzi, která je důležitá pro monitorování aktualizací verzí požadovaného modulu. Je zvlášť důležité vědět o všech zásadních změnách, které by mohly ovlivnit uživatelské prostředí vašeho modulu.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Reakce na zpětnou vazbu

Vlastníci balíčků, kteří správně reagují na zpětnou vazbu, jsou komunitou vysoce hodnotní. Uživatelé, kteří poskytují konstruktivní zpětnou vazbu, je důležité reagovat, protože mají zájem o balíček, aby se pokusili ho vylepšit.

V galerii PowerShellu je k dispozici jedna metoda zpětné vazby:

• Vlastník kontaktu: Uživatel tak může poslat e-mail vlastníkovi balíčku. Jako vlastník balíčku je důležité monitorovat e-mailovou adresu používanou s balíčky Galerie Prostředí PowerShell a reagovat na problémy, které jsou vyvolány. Nevýhodou této metody je, že komunikaci uvidí jenom uživatel a vlastník, takže vlastník může muset odpovědět na stejnou otázku mnohokrát.

Vlastníci, kteří reagují na zpětnou vazbu, ocení komunita. Pokud chcete požádat o další informace, použijte příležitost v sestavě. V případě potřeby uveďte alternativní řešení nebo zjistěte, jestli aktualizace problém vyřeší.

Pokud je u některého z těchto komunikačních kanálů zjištěno nevhodné chování, obraťte se na správce galerie Galerie Galerie prostředí PowerShell pomocí funkce Ohlášení zneužití.

Moduly versus skripty

Sdílení skriptu s ostatními uživateli je skvělé a poskytuje ostatním příklady řešení problémů, které mohou mít. Problémem je, že skripty v galerii Prostředí PowerShell jsou samostatné soubory bez samostatné dokumentace, příkladů a testů.

Moduly PowerShellu mají strukturu složek, která umožňuje zahrnutí více složek a souborů do balíčku. Struktura modulu umožňuje zahrnutí dalších balíčků, které uvádíme jako osvědčené postupy: nápověda k rutinám, dokumentace, příklady a testy. Největší nevýhodou je, že skript uvnitř modulu musí být vystaven a používán jako funkce. Informace o tom, jak vytvořit modul, najdete v tématu Zápis modulu Prostředí Windows PowerShell.

Existují situace, kdy skript poskytuje uživateli lepší prostředí, zejména s konfigurací DSC. Osvědčeným postupem pro konfigurace DSC je publikování konfigurace jako skriptu s doprovodným modulem, který obsahuje dokumenty, příklady a testy. Skript zobrazí seznam doprovodných modulů pomocí RequiredModules = @(Name of the Module). Tento přístup lze použít s libovolným skriptem.

Samostatné skripty, které dodržují ostatní osvědčené postupy, poskytují ostatním uživatelům skutečnou hodnotu. Poskytnutí dokumentace založené na komentářích a odkaz na web projektu se důrazně doporučuje při publikování skriptu do galerie Prostředí PowerShell.

Zadání odkazu na web projektu

Web projektu je místo, kde může vydavatel pracovat přímo s uživateli jejich balíčků Galerie Prostředí PowerShell. Uživatelé dávají přednost balíčkům, které to poskytují, protože jim umožní získat informace o balíčku snadněji. Mnoho balíčků v galerii PowerShellu se vyvíjí na GitHubu, jiné organizace poskytují vyhrazenou webovou přítomnost. Každý z nich může být považován za web projektu.

Přidání odkazu se provádí zahrnutím identifikátoru ProjectURI v části PSData manifestu následujícím způsobem:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Po zadání identifikátoru ProjectURI bude galerie Prostředí PowerShell obsahovat odkaz na web projektu na levé straně stránky balíčku.

Označení balíčku kompatibilními platformami PSEdition

Pomocí následujících značek předveďte uživatelům, kteří balíčky budou dobře fungovat s jejich prostředím:

• PSEdition_Desktop: Balíčky kompatibilní s Prostředím Windows PowerShell
• PSEdition_Core: Balíčky kompatibilní s PowerShellem 6 a novějším
• Windows: Balíčky kompatibilní s operačním systémem Windows
• Linux: Balíčky kompatibilní s operačními systémy Linux
• MacOS: Balíčky kompatibilní s operačním systémem Mac

Když balíček označíte kompatibilními platformami, budou zahrnuty do filtrů hledání v galerii v levém podokně výsledků hledání. Pokud balíček hostujete na GitHubu, můžete při označování balíčku využít také naše štíty kompatibility galerie PowerShellu.

Zahrnout testy

Zahrnutí testů s opensourcovým kódem je pro uživatele důležité, protože jim poskytuje jistotu o tom, co ověříte, a poskytuje informace o tom, jak váš kód funguje. Umožňuje také uživatelům zajistit, aby neporušili původní funkce, pokud upraví kód tak, aby vyhovoval jejich prostředí.

Důrazně doporučujeme, aby testy byly napsány tak, aby využívaly testovací architekturu Pester, která byla navržena speciálně pro PowerShell. Nástroj Pester je k dispozici v GitHubu, galerii PowerShellua dodává se ve Windows 10, Windows Serveru 2016, WMF 5.0 a WMF 5.1.

Web projektu Pester na GitHubu obsahuje dobrou dokumentaci k psaní testů Pester od začátku po osvědčené postupy.

Cíle pokrytí testů jsou označeny v dokumentaci k vysoce kvalitního modulu prostředkůs doporučeným pokrytím kódu 70% testování jednotek.

Zahrnutí a/nebo odkaz na licenční podmínky

Všechny balíčky publikované v galerii Prostředí PowerShell musí určovat licenční podmínky nebo musí být vázány licencí, která je součástí Podmínek použití v části Vystavujte. Nejlepším přístupem k určení jiné licence je poskytnout odkaz na licenci pomocí LicenseURI v PSData. Další informace najdete v tématu Manifest balíčků a uživatelské rozhraní galerie.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Podepsání kódu

Podepisování kódu poskytuje uživatelům nejvyšší úroveň záruky, kdo balíček publikoval, a že kopie kódu, který získal, je přesně to, co vydavatel vydal. Další informace o podepisování kódu obecně najdete v tématu Úvod do podepisování kódu. PowerShell podporuje ověřování podepisování kódu pomocí dvou primárních přístupů:

• Podpisové soubory skriptů
• Podepisování modulu katalogem

Podepisování souborů PowerShellu je dobře zavedený přístup k zajištění toho, aby se spouštěný kód vytvořil spolehlivým zdrojem a nezměnil se. Podrobnosti o tom, jak podepsat soubory skriptů PowerShellu, najdete v článku O podepisování. V přehledu je možné podpis přidat do libovolného souboru .PS1, který PowerShell ověří při načtení skriptu. PowerShell je možné omezit pomocí rutin zásad spouštění, aby se zajistilo použití podepsaných skriptů.

Podpisové moduly katalogu jsou funkce přidaná do PowerShellu ve verzi 5.1. Postup podepsání modulu najdete v článku o rutinách katalogu . V přehledu se podepisování katalogu provádí vytvořením souboru katalogu, který obsahuje hodnotu hash pro každý soubor v modulu a podepsáním daného souboru.

Rutiny PowerShellGetPublish-Module, Install-Modulea Update-Module zkontrolují podpis, aby byl platný, a pak ověřte, že hodnota hash pro každý balíček odpovídá hodnotě, která je v katalogu. Save-Module neověřuje podpis. Pokud je v systému nainstalovaná předchozí verze modulu, Install-Module potvrdí, že podpisová autorita pro novou verzi odpovídá dříve nainstalované verzi. Install-Module a Update-Module použijí podpis v souboru .PSD1, pokud balíček není podepsaný katalogem. Podepisování katalogů funguje, ale nenahrazuje soubory podpisových skriptů. PowerShell neověřuje podpisy katalogu v době načtení modulu.

Postupujte podle pokynů pro SemVer pro správu verzí

SemVer je veřejná konvence, která popisuje, jak strukturovat a změnit verzi tak, aby umožňovala snadnou interpretaci změn. Verze balíčku musí být součástí dat manifestu.

• Verze by měla být strukturovaná jako tři číselné bloky oddělené tečkami, stejně jako v 0.1.1 nebo 4.11.192.
• Verze začínající 0 značí, že balíček ještě není připravený pro produkční prostředí, a první číslo by mělo začínat pouze 0, pokud se používá pouze toto číslo.
• Změny v prvním čísle (1.9.9999 na 2.0.0) označují hlavní a zásadní změny mezi verzemi.
• Změny druhého čísla (1.1 na 1.2) označují změny na úrovni funkcí, například přidání nových rutin do modulu.
• Změny třetího čísla označují změny, které nejsou zásadní, například nové parametry, aktualizované ukázky nebo nové testy.
• Při výpisu verzí PowerShell seřadí verze jako řetězce, takže 1.01.0 budou považovány za větší než 1.001.0.

PowerShell byl vytvořen před publikováním SemVeru, takže poskytuje podporu pro většinu, ale ne pro všechny prvky SemVer, konkrétně:

• Nepodporuje předběžné verze řetězců v číslech verzí. To je užitečné, když vydavatel chce dodat verzi Preview nové hlavní verze po poskytnutí verze 1.0.0. To bude podporováno v budoucí verzi galerie Prostředí PowerShell a rutin powershellgetu.
• PowerShell a Galerie Prostředí PowerShell umožňují řetězce verzí s 1, 2 a 4 segmenty. Mnoho dřívějších modulů nesplní pokyny a verze produktů od Microsoftu obsahují informace o sestavení jako 4. blok čísel (například 5.1.14393.1066). Z hlediska správy verzí se tyto rozdíly ignorují.

Testování pomocí místního úložiště

Galerie Prostředí PowerShell není navržená jako cíl pro testování procesu publikování. Nejlepším způsobem, jak otestovat kompletní proces publikování do galerie Prostředí PowerShell, je nastavit a používat vlastní místní úložiště. Můžete to udělat několika způsoby, včetně:

• Nastavte místní instanci galerie PowerShellu pomocí projektu privátní galerie PS na GitHubu. Tento projekt Preview vám pomůže nastavit instanci galerie Prostředí PowerShell, kterou můžete řídit a používat pro testy.
• Nastavteinterního úložiště NuGet . Toto nastavení bude vyžadovat více práce, ale bude mít výhodu ověření několika dalších požadavků, zejména ověřování použití klíče rozhraní API a to, zda jsou závislosti v cíli při publikování přítomny.
• Nastavte sdílenou složku jako testovací úložiště . Nastavení je snadné, ale protože se jedná o sdílenou složku, neprobíhá ověření uvedená výše. Jednou z potenciálních výhod v tomto případě je, že sdílená složka nekontroluje požadovaný klíč rozhraní API, takže můžete použít stejný klíč, který byste použili k publikování do galerie Prostředí PowerShell.

V každém z těchto řešení použijte Register-PSRepository k definování nového úložiště, které použijete v parametru -Repository pro Publish-Module.

Jeden další bod o publikování testů: Jakýkoli balíček, který publikujete do galerie Prostředí PowerShell, nelze odstranit bez pomoci provozního týmu, který potvrdí, že na balíčku, který chcete publikovat, nic není závislé. Z tohoto důvodu nepodporujeme Galerii Prostředí PowerShell jako testovací cíl a kontaktujeme všechny vydavatele, kteří to udělali.

Použití modulu PowerShellGet k publikování

Důrazně doporučujeme, aby vydavatelé při práci s galerií PowerShellu používali rutiny Publish-Module a Publish-Script. PowerShellGet byl vytvořen, abyste se vyhnuli zapamatování důležitých podrobností o instalaci a publikování do galerie Prostředí PowerShell. V některých případech se vydavatelé rozhodli přeskočit PowerShellGet a místo použít klienta NuGet nebo rutiny PackageManagement. Existuje řada podrobností, které jsou snadno zmeškané, což vede k řadě žádostí o podporu.

Pokud existuje důvod, proč nemůžete použít Publish-Module nebo Publish-Script, dejte nám prosím vědět. Zapište problém v úložišti PowerShellGet GitHubu a uveďte podrobnosti, které způsobují výběr NuGet nebo PackageManagement .

Doporučený pracovní postup

Pro balíčky publikované v galerii Prostředí PowerShell jsme zjistili, že se jedná o tento postup:

• Proveďte počáteční vývoj na opensourcové lokalitě projektu. Tým PowerShellu používá GitHub.
• Pomocí zpětné vazby od revidujících a analyzátoru skriptů PowerShellu získat kód do stabilního stavu.
• Připojte dokumentaci, aby ostatní věděli, jak vaši práci používat.
• Otestujte akci publikování pomocí místního úložiště.
• Publikujte stabilní verzi nebo verzi Alpha do galerie Prostředí PowerShell a nezapomeňte zahrnout dokumentaci a odkaz na web projektu.
• Shromážděte zpětnou vazbu a iterujte kód na webu projektu a pak publikujte stabilní aktualizace do galerie Prostředí PowerShell.
• Přidejte do projektu a modulu příklady a testy Pesteru.
• Rozhodněte se, jestli chcete balíček podepsat kódem.
• Až budete mít pocit, že je projekt připravený k použití v produkčním prostředí, publikujte do galerie Prostředí PowerShell verzi 1.0.0.
• Pokračujte ve shromažďování zpětné vazby a iteraci kódu na základě uživatelského vstupu.