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

Článek
06/26/2023

Tento článek popisuje doporučené kroky, které týmy Microsoftu používají k zajištění toho, aby byly balíčky publikované do Galerie prostředí PowerShell široce přijaty a poskytovaly uživatelům vysokou hodnotu, a to na základě toho, jak Galerie prostředí PowerShell zpracovává data manifestu, a na základě zpětné vazby od velkého počtu Galerie prostředí PowerShell uživatelů. Balíčky publikované podle těchto pokynů budou pravděpodobně nainstalované, důvěryhodné a přilákají více uživatelů.

Níže najdete pokyny k tomu, co dělá dobrý Galerie prostředí PowerShell balíček, jaká volitelná nastavení manifestu jsou nejdůležitější, vylepšení kódu pomocí zpětné vazby od počátečních kontrolorů a Analyzátoru skriptů PowerShellu, správa verzí modulu, dokumentace, testy a příklady, jak používat to, co jste nasdíleli. Většina 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.

Uví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ů

Podle následujících osvědčených postupů uživatelé Galerie prostředí PowerShell položek říkají, že jsou důležité a jsou uvedeny v nominálním pořadí priority. U balíčků, které se řídí těmito pokyny, je mnohem větší pravděpodobnost, že je stáhnou a přijmou ostatní.

Použití PSScriptAnalyzer
Zahrnout dokumentaci a příklady
Reakce na zpětnou vazbu
Poskytování modulů místo skriptů
Poskytnutí odkazů na web projektu
Označení balíčku kompatibilními psEdition(s) a platformami
Zahrnutí testů do modulů
Zahrnout a/nebo odkaz na licenční podmínky
Podepsání kódu
Postupujte podle pokynů pro SemVer pro správu verzí
Použití běžných značek, jak je popsáno v části Běžné značky Galerie prostředí PowerShell
Testování publikování pomocí místního úložiště
Použití nástroje PowerShellGet k publikování

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

Použití PSScriptAnalyzer

PSScriptAnalyzer je bezplatný nástroj pro analýzu statického kódu, který funguje s kódem PowerShellu. PSScriptAnalyzer identifikuje nejběžnější problémy, ke kterým dochází v kódu PowerShellu, a často doporučí, jak problém vyřešit. Nástroj se snadno používá a kategorizuje problémy jako Chyby (závažné, je třeba řešit), Upozornění (je třeba zkontrolovat a mělo by se řešit) a Informace (stojí za to vyzkoušet osvědčené postupy). Všechny balíčky publikované do Galerie prostředí PowerShell budou kontrolovány pomocí PSScriptAnalyzer a všechny chyby budou nahlášeny zpět vlastníkovi a musí být vyřešeny.

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

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

Všechny chyby jsou opraveny nebo vyřešeny v dokumentaci.
Všechna upozornění se kontrolují a případně řeší.

Uživatelům, kteří stahují balíčky z Galerie prostředí PowerShell, se důrazně doporučuje, aby spustili nástroj PSScriptAnalyzer a vyhodnotili všechny chyby a upozornění. Uživatelé budou pravděpodobně kontaktovat vlastníky balíčků, pokud zjistí, že psScriptAnalyzer nahlásil chybu. Pokud existuje přesvědčivý důvod pro to, aby váš balíček ponechal kód, který je označený jako chyba, přidejte je do dokumentace, abyste nemuseli na stejnou otázku odpovídat mnohokrát.

Zahrnout dokumentaci a příklady

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

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

Pokyny pro poskytování nápovědy najdete v tématu Jak psát nápovědu k 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ě, najdete v části Jak psát nápovědu k rutině. Pokud chcete přidat nápovědu do skriptu, přečtěte si článek O nápovědě založené na komentářích.
Mnoho modulů obsahuje také dokumentaci v textovém formátu, například soubory MarkDown. To může být užitečné zejména v případě, že je na GitHubu web projektu, kde je Markdown často používaný formát. Osvědčeným postupem je použít Markdown s příchutí GitHubu.

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

Vhodný vzor pro příklady najdete v modulu PSDscResource ve Examples\RegistryResource složce. Existují čtyři ukázkové případy použití se stručným popisem v horní části každého souboru, který dokumentuje to, co se demonstruje.

Správa závislostí

Je důležité zadat moduly, na které je modul závislý v manifestu modulu. To umožňuje, aby si koncový uživatel nemusel dělat starosti s instalací správných verzí modulů, na kterých je váš modul závislý. Pokud chcete zadat závislé moduly, měli byste v manifestu modulu použít požadované pole 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. Například některé moduly už můžou být načteny jiným modulem. Je také možné určit konkrétní verzi, která se má načíst, pomocí pole RequiredVersion místo pole ModuleVersion . Při použití ModuluVersion se načte nejnovější dostupná verze s minimální zadanou verzí. Pokud nepoužíváte pole RequiredVersion , je pro zadání konkrétní verze důležité monitorovat aktualizace verzí požadovaného modulu. Je obzvláště 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 ocenění. Uživatelé, kteří poskytují konstruktivní zpětnou vazbu, je důležité reagovat, protože je balíček natolik zajímá, aby se pokusili ho vylepšit.

V Galerie prostředí PowerShell je k dispozici jedna metoda zpětné vazby:

Kontaktovat vlastníka: To uživateli umožňuje 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í jen uživatel a vlastník, takže vlastník bude muset na stejnou otázku odpovědět mnohokrát.

Majitelé, kteří reagují na zpětnou vazbu konstruktivně, jsou komunitou oceňováni. Využijte příležitost v sestavě a požádejte o další informace. V případě potřeby zadejte alternativní řešení nebo zjistěte, jestli aktualizace problém vyřešila.

Pokud některý z těchto komunikačních kanálů zaznamená nevhodné chování, obraťte se na správce galerie pomocí funkce Nahlásit zneužití Galerie prostředí PowerShell.

Moduly a skripty

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

Moduly PowerShellu mají strukturu složek, která umožňuje zahrnout do balíčku více složek a souborů. Struktura modulů 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žit jako funkce. Informace o tom, jak vytvořit modul, najdete v tématu Psaní modulu Windows PowerShell.

V situacích, kdy skript poskytuje uživateli lepší prostředí, zejména u konfigurací DSC. Osvědčeným postupem pro konfigurace DSC je publikovat konfiguraci jako skript s doprovodným modulem, který obsahuje dokumentaci, příklady a testy. Skript zobrazí seznam doprovodného modulu pomocí RequiredModules = @(Name of the Module)příkazu . Tento přístup lze použít s libovolným skriptem.

Samostatné skripty, které se řídí jinými osvědčenými postupy, poskytují ostatním uživatelům skutečnou hodnotu. Při publikování skriptu do Galerie prostředí PowerShell důrazně doporučujeme poskytnout dokumentaci založenou na komentářích a odkaz na web projektu.

Poskytnutí odkazu na web projektu

Web projektu je místo, kde může vydavatel komunikovat přímo s uživateli svých Galerie prostředí PowerShell balíčků. Uživatelé preferují balíčky, které tuto možnost poskytují, protože jim to umožňuje snadněji získat informace o balíčku. Mnoho balíčků v Galerie prostředí PowerShell se vyvíjí na GitHubu, jiné poskytují organizace s vyhrazeným webem. Každý z nich lze považovat za web projektu.

Přidání odkazu se provede tak, že do části PSData manifestu zahrnete ProjectURI 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 psEdition(s) a platformami

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

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

Když balíček označíte kompatibilními platformami, zahrne se do filtrů hledání v galerii v levém podokně výsledků hledání. Pokud balíček hostujete na GitHubu a označíte ho, můžete také využít našeho příkladu Galerie prostředí PowerShell kompatibilních štítů kompatibility.

Zahrnout testy

Zahrnutí testů s opensourcovým kódem je pro uživatele důležité, protože jim dává jistotu o tom, co ověřujete, 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í váš kód tak, aby vyhovoval jejich prostředí.

Důrazně doporučujeme, aby byly testy napsané tak, aby využívaly testovací architekturu Pester, která byla navržena speciálně pro PowerShell. Pester je k dispozici na GitHubu, Galerie prostředí PowerShell a dodává se v Windows 10, Windows Server 2016, WMF 5.0 a WMF 5.1.

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

Cíle pokrytí testu jsou uvedené v dokumentaci k modulu prostředků vysoké kvality s doporučeným pokrytím 70 % kódu testu jednotek.

Zahrnout nebo odkaz na licenční podmínky

Všechny balíčky publikované na Galerie prostředí PowerShell musí obsahovat licenční podmínky nebo musí být vázány licencí, která je součástí podmínek použití v dodatku A. Nejlepší způsob, jak zadat jinou licenci, je poskytnout odkaz na licenci pomocí identifikátoru 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 toho, kdo balíček publikoval, a že kopie kódu, který získali, je přesně to, co vydavatel vydal. Další obecné informace o podepisování kódu najdete v tématu Úvod do podepisování kódu. PowerShell podporuje ověřování podepisování kódu prostřednictvím dvou primárních přístupů:

Soubory podepisovacích skriptů
Podepsání modulu katalogu

Podepisování souborů PowerShellu je dobře zavedený přístup k zajištění toho, aby spouštěný kód byl vytvořen spolehlivým zdrojem a nebyl upraven. Podrobnosti o tom, jak podepsat soubory skriptů PowerShellu, najdete v článku Informace o podepisování . V přehledu je možné 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ů.

Moduly podepisování katalogu jsou funkce přidaná do PowerShellu ve verzi 5.1. Postup podepsání modulu je popsaný v článku o rutinách katalogu . V přehledu se podepisování katalogu provádí tak, že se vytvoří soubor katalogu, který obsahuje hodnotu hash pro každý soubor v modulu, a pak tento soubor podepíšete.

Rutiny PowerShellGetPublish-Module, Install-Modulea Update-Module zkontrolují podpis, aby se ujistily, že je platný, a pak potvrdí, že hodnota hash pro každý balíček odpovídá hodnotě v katalogu. Save-Module neověřuje podpis. Pokud je v systému nainstalovaná předchozí verze modulu, nástroj potvrdí, Install-Module že podpisová autorita pro novou verzi odpovídá dříve nainstalované autoritě. Install-Module a Update-Module použije podpis .PSD1 v souboru, pokud balíček není podepsaný katalogem. Podepisování katalogu funguje s, 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 vašeho 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, například v 0.1.1 nebo 4.11.192.
Verze začínající na 0 indikují, že balíček ještě není připravený na produkční prostředí, a první číslo by mělo začínat pouze v 0 případě, že je to jediné použité číslo.
Změny v prvním čísle (1.9.9999 na 2.0.0) značí hlavní a zásadní změny mezi verzemi.
Změny druhého čísla (1.1 na 1.2) značí změny na úrovni funkce, například přidání nových rutin do modulu.
Změny třetího čísla značí zásadní změny, jako jsou nové parametry, aktualizované vzorky nebo nové testy.
Při výpisu verzí PowerShell seřadí verze jako řetězce, takže 1.01.0 se bude považovat za větší než 1.001.0.

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

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

Testování s využitím místního úložiště

Galerie prostředí PowerShell není navržený tak, aby byl cílem pro testování procesu publikování. Nejlepší způsob, jak otestovat kompletní proces publikování do Galerie prostředí PowerShell, je nastavit a použít vlastní místní úložiště. Můžete to udělat několika způsoby, mezi které patří:

Nastavte místní instanci Galerie prostředí PowerShell pomocí projektu PS Private Gallery na GitHubu. Tento projekt preview vám pomůže nastavit instanci Galerie prostředí PowerShell, kterou můžete ovládat a používat pro testy.
Nastavte interní úložiště NuGet. Nastavení bude vyžadovat více práce, ale výhodou je ověření několika dalších požadavků, zejména ověření použití klíče rozhraní API a toho, jestli se při publikování v cíli nacházejí závislosti.
Nastavte sdílenou složku jako úložiště testů. Nastavení je snadné, ale vzhledem k tomu, že se jedná o sdílenou složku, neprovedou se výše uvedená ověření. 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.

Ještě jeden bod k publikování testů: žádný balíček, který publikujete do Galerie prostředí PowerShell, není možné odstranit bez pomoci provozního týmu, který potvrdí, že na balíčku, který chcete publikovat, nic nezávisí. Z tohoto důvodu nepodporujeme Galerie prostředí PowerShell jako testovací cíl a budeme kontaktovat všechny vydavatele, kteří to uvedou.

Použití modulu PowerShellGet k publikování

Důrazně doporučujeme, aby vydavatelé při práci s Galerie prostředí PowerShell používali Publish-Module rutiny a Publish-Script . Modul PowerShellGet je vytvořený proto, abyste si nepamatovali důležité podrobnosti o instalaci z Galerie prostředí PowerShell a publikování do Galerie prostředí PowerShell. V některých případech se vydavatelé rozhodli přeskočit PowerShellGet a místo Publish-Modulepoužít klienta NuGet nebo rutiny PackageManagement. Existuje řada podrobností, které se snadno přehlédnou, což vede k různým žádostem o podporu.

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

Doporučený pracovní postup

U balíčků publikovaných na Galerie prostředí PowerShell jsme našli nejúspěšnější přístup:

Proveďte počáteční vývoj na webu opensourcového projektu. Tým PowerShellu používá GitHub.
Ke stabilnímu stavu kódu použijte zpětnou vazbu od revidujících a Analyzátoru skriptů PowerShellu .
Přidejte dokumentaci, aby ostatní věděli, jak používat vaši práci.
Otestujte akci publikování pomocí místního úložiště.
Publikujte na Galerie prostředí PowerShell stabilní verzi nebo verzi Alfa, 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 Galerie prostředí PowerShell.
Přidejte příklady a pesterové testy do projektu a modulu.
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 1.0.0 verzi do Galerie prostředí PowerShell.
Dál shromážděte zpětnou vazbu a iterujte kód na základě vstupu uživatele.