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 na základě zpětné vazby od počátečních recenzentů a nástroje Powershell Script Analyzer, správa verzí modulu, dokumentace, testy a příklady, jak používat to, co jste sdíleli. Velká část této dokumentace se řídí pokyny pro publikování vysoce kvalitních modulů prostředků DSC.

Mechaniku 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 na 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ů SemVer pro správu verzí
• 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ý pracuje s kódem PowerShell. Nástroj PSScriptAnalyzer identifikuje nejběžnější problémy, které se vyskytují v kódu PowerShellu, a často i doporučení, jak 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é na Galerie prostředí PowerShell budou zkontrolovány pomocí PSScriptAnalyzer a všechny chyby budou hlášeny zpět vlastníkovi a musí být vyřešeny.

Nejlepším postupem je spustit Invoke-ScriptAnalyzer pomocí -Recurse a -Severity Warning.

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, se důrazně doporučuje spustit skript PSScriptAnalyzer a vyhodnotit všechny chyby a upozornění. Uživatelé velmi pravděpodobně kontaktují vlastníky balíčků, pokud uvidí, že PSScriptAnalyzer nahlásil chybu. 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 pro poskytování nápovědy jsou uvedeny v nápovědě k rutinám Jak psát rutiny.
• 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 v tématu Jak napsat nápovědu k rutině. Chcete-li přidat nápovědu do skriptu, přečtěte si článek O nápovědě založené na poznámká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 Markdown 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 pro příklady lze nalézt v modulu PSDscResource pod složkou 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í ModuleVersion se načte nejnovější dostupná verze s minimem zadané verze. Pokud nepoužíváte pole RequiredVersion , je pro zadání konkrétní verze důležité sledovat aktualizace 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 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 vypíše doprovodný 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 svůj balíček hostujete na GitHubu, můžete při označování balíčku využít také náš Galerie prostředí PowerShell.

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. Pester je k dispozici na GitHubu, v galerii prostředí PowerShell a je k dispozici ve Windows 10, Windows Server 2016, WMF 5.0 a WMF 5.1.

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

Cíle pro pokrytí testů jsou uvedeny v dokumentaci k modulu prostředků vysoké kvality, přičemž se doporučuje pokrytí testovacího kódu 70% jednotek.

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

Všechny balíčky publikované v Galerie prostředí PowerShell musí specifikovat licenční podmínky nebo musí být vázány licencí obsaženou v podmínkách použití v příloze A. Nejlepším přístupem k zadání jiné licence je poskytnout odkaz na licenci pomocí LicenseURI v PSData. Další informace naleznete v tématech 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ě naleznete 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 podepisovat soubory skriptů PowerShell, jsou popsané v článku O podepisování . V přehledu lze podpis přidat do libovolného .PS1 souboru, 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. Jak podepsat modul je popsán v článku Rutiny 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, a zkontrolují podpis, aby se ujistily, že je platný, a Update-Module pak potvrdí, že hodnota hash pro každý balíček odpovídá tomu, Install-Moduleco je v katalogu. Save-Module Neověřuje podpis. Pokud je v systému nainstalována předchozí verze modulu, potvrdí, že podpisové oprávnění pro novou verzi odpovídá tomu, Install-Module co bylo nainstalováno dříve. Install-Module a Update-Module použije podpis u .PSD1 souboru, 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 měnit verzi, aby umožňovala snadnou interpretaci změn. Verze balíčku musí být součástí dat manifestu.

• Verze by měla být strukturována jako tři číselné bloky oddělené tečkami, jako v nebo 0.1.14.11.192.
• Verze začínající na 0 označují, že balíček ještě není připraven pro produkční prostředí, a první číslo by mělo začínat pouze 0 v případě, že je to jediné použité číslo.
• Změny v prvním čísle (1.9.9999 to 2.0.0) označují hlavní a zásadní změny mezi verzemi.
• Změny druhého čísla (1.1 to 1.2) označují změny na úrovni funkce, jako je 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ž si vydavatel přeje dodat náhledové vydání nové hlavní verze po poskytnutí verze 1.0.0. To bude podporováno v budoucí verzi Galerie prostředí PowerShell a rutin PowerShellGet .
• PowerShell a Galerie Prostředí PowerShell umožňují řetězce verzí s 1, 2 a 4 segmenty. Mnoho raných modulů se neřídilo pokyny a verze produktů od společnosti Microsoft obsahují informace o sestavení jako čtvrtý 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 prostředí PowerShell 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.
• Nastavte interní ú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.

U kteréhokoli 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 Galerie prostředí PowerShell používali rutiny Publish-Module and Publish-Script . Modul PowerShellGet byl vytvořen, aby vám pomohl vyhnout se zapamatování důležitých podrobností o instalaci z Galerie prostředí PowerShell a publikování do něj. V některých případech se vydavatelé rozhodli přeskočit PowerShellGet a použít klienta NuGet nebo rutiny PackageManagement místo Publish-Module. 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 GitHub a zadejte podrobnosti, které vás přimějí zvolit 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 recenzentů a analyzátoru skriptů PowerShellu dostaňte 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.
• Pokud máte pocit, že je projekt připravený k použití v produkčním prostředí, publikujte 1.0.0 jeho verzi do Galerie prostředí PowerShell.
• Pokračujte ve shromažďování zpětné vazby a iteraci kódu na základě uživatelského vstupu.