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

Tento článek popisuje doporučené kroky používané týmy Microsoftu k zajištění toho, aby se balíčky publikované do Galerie 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 z velkého počtu Galerie prostředí PowerShell uživatele. 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 pomocí zpětné vazby od počátečních kontrolorů a Analyzátoru skriptů PowerShellu, správy verzí modulu, dokumentace, testů a příkladů pro použití toho, co jste nasdíleli. Většina této dokumentace se řídí pokyny pro publikování modulů prostředků DSC s vysokou kvalitou.

Postup publikování balíčku do Galerie prostředí PowerShell najdete v tématu Vytvoření a publikování balíčku.

Zpětná vazba k těmto pokynům je vítána. 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é Galerie prostředí PowerShell položky říkají, jsou důležité a jsou uvedeny v nominálním pořadí priority. Balíčky, které dodržují tyto pokyny, jsou mnohem pravděpodobnější, že budou staženy a přijaty jinými uživateli.

  • Použití PSScriptAnalyzer
  • Zahrnutí dokumentace a příkladů
  • Reagovat na zpětnou vazbu
  • Poskytování modulů místo skriptů
  • Poskytnutí odkazů na web projektu
  • Označte balíček pomocí kompatibilních psEdition a platforem.
  • Zahrnutí testů do modulů
  • Zahrnutí 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 uvedeno v běžných značkách Galerie prostředí PowerShell
  • Testování publikování pomocí místního úložiště
  • Publikování pomocí modulu PowerShellGet

Každá z těchto částí 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 v kódu PowerShellu. PSScriptAnalyzer identifikuje nejběžnější problémy, které jsou vidět v kódu PowerShellu, a často doporučení, 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šené), upozornění (je potřeba je zkontrolovat a mělo by být vyřešeno) a informace (stojí za to si projít osvědčené postupy). Všechny balíčky publikované do Galerie prostředí PowerShell se naskenují pomocí psScriptAnalyzeru 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 se -Recurse systémem a -Severity upozorněním.

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 v případě potřeby řeší.

Uživatelé, kteří si stáhnou balíčky z Galerie prostředí PowerShell, důrazně doporučujeme spustit PSScriptAnalyzer a vyhodnotit všechny chyby a upozornění. Uživatelé budou velmi pravděpodobně kontaktovat vlastníky balíčků, pokud zjistí, že došlo k chybě hlášené psScriptAnalyzerem. Pokud je pro váš balíček přesvědčivý důvod zachovat kód označený příznakem chyby, přidejte tyto informace do dokumentace, abyste nemuseli zodpovědět stejnou otázku mnohokrát.

Zahrnutí dokumentace a příkladů

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 třeba zahrnout do balíčků publikovaných v Galerie prostředí PowerShell. Uživatelé budou obecně obcházet 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ědě k zápisu 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 nápovědě k postupu zápisu rutiny. Pokud chcete přidat nápovědu ve skriptu, přečtěte si článek O nápovědě založené na komentářích.
  • Mnoho modulů zahrnuje 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 Je to markdown velmi používaný formát. Osvědčeným postupem je používat Markdown s příchutí GitHubu.

Příklady ukazují uživatelům, jak se má balíček použít. Mnoho vývojářů řekne, že si před dokumentací prohlédnou příklady, abyste 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 okomentován. Příklady modulů publikovaných v Galerie prostředí PowerShell by měly být ve složce Příklady v kořenovém adresáři modulu.

Vhodný vzor pro příklady najdete 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 se demonstruje.

Správa závislostí

Je důležité určit moduly, na kterém je modul závislý v manifestu modulu. To umožňuje koncovému uživateli, 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 v manifestu modulu použít požadované pole modulu. Tím se načte všechny uvedené moduly do globálního prostředí před importem modulu, pokud ještě nebyly načteny. Některé moduly už například můžou být načteny jiným modulem. Kromě pole ModuleVersion je také možné zadat konkrétní verzi, která se má načíst pomocí pole RequiredVersion . Při použití modulu ModuleVersion načte nejnovější verzi dostupnou s minimální zadanou verzí. Pokud pole RequiredVersion nepoužíváte, 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 mít vliv na uživatelské prostředí s vaším modulem.

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 Galerie prostředí PowerShell je k dispozici jedna metoda zpětné vazby:

  • Vlastník kontaktu: To umožňuje uživateli odeslat e-mail vlastníkovi balíčku. Jako vlastník balíčku je důležité monitorovat e-mailovou adresu použitou s balíčky Galerie prostředí PowerShell a reagovat na problémy, které jsou vyvolány. Nevýhodou této metody je to, že komunikaci uvidí jenom uživatel a vlastník, takže vlastník možná bude muset odpovědět na stejnou otázku mnohokrát.

Vlastníci, kteří reagují na zpětnou vazbu konstruktivní, ocení komunita. Využijte příležitost v sestavě k vyžádání dalších informací. V případě potřeby zadejte alternativní řešení nebo zjistěte, jestli aktualizace problém vyřeší.

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

Moduly versus skripty

Sdílení skriptu s ostatními uživateli je skvělé a poskytuje ostatním příklady, jak řešit problémy, které mohou mít. Problém spočívá 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 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 Psaní modulu Windows PowerShell.

Existují situace, kdy skript poskytuje uživatelům 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 uvádí 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. 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.

Web projektu je místo, kde může vydavatel pracovat přímo s uživateli svých Galerie prostředí PowerShell balíčků. 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 Galerie prostředí PowerShell 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 provedete tak, že do části PSData manifestu zahrnete kód ProjectURI:

  # 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čte balíček pomocí kompatibilních psEdition a platforem.

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 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, zahrnete ho do vyhledávacích filtrů galerie 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é náš příkladkompatibility štítů kompatibility Galerie prostředí PowerShell 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ěří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, Galerie prostředí PowerShell a lodích v 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 uvedené v dokumentaci k modulu prostředků vysoké kvality s doporučeným pokrytím kódu testu jednotek 70 %.

Všechny balíčky publikované v Galerie prostředí PowerShell musí určovat licenční podmínky nebo být vázány licencí, která je součástí podmínek použití v rámci předmětu A. Nejlepším přístupem k určení jiné licence je poskytnutí odkazu 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, 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 prostřednictvím dvou primárních přístupů:

  • Soubory podpisových skriptů
  • Podepsá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 .PS1 souboru, který PowerShell ověří při načtení skriptu. PowerShell může být omezený 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 najdete 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 následným podepsáním daného souboru.

Rutiny PowerShellGetPublish-ModuleInstall-Module a Update-Module zkontrolují podpis, aby byly platné, a pak ověřte, že hodnota hash každého balíčku odpovídá hodnotě hash v katalogu. Save-Module neověřuje podpis. Pokud je v systému nainstalovaná předchozí verze modulu, ověří se, Install-Module že podpisová autorita pro novou verzi odpovídá dříve nainstalované verzi. Install-Module a Update-Module použije podpis v .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čítání modulu.

Při správě verzí postupujte podle pokynů pro SemVer.

SemVer je veřejná konvence, která popisuje, jak strukturovat a změ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 strukturovaná jako tři číselné bloky oddělené tečkami, jako v 0.1.1 nebo 4.11.192.
  • Verze začínající 0 indikují, že balíček ještě není připravený pro produkční prostředí, a první číslo by mělo začínat 0 pouze v případě, že se použije jediné číslo.
  • Změny v prvním čísle (1.9.9999 pro 2.0.0) označují hlavní a zásadní změny mezi verzemi.
  • Změny druhého čísla (1.1 pro 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í nerušné 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 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 po poskytnutí verze 1.0.0dodat 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í ř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í určen jako cíl pro testování procesu publikování. Nejlepší způsob, 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 vaše testy.
  • Nastavte interní úložiště NuGet. To bude vyžadovat více práce na nastavení, 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, nebudou probíhat ověření uvedená výše. Jednou z možný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 některého 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 Galerie prostředí PowerShell jako testovací cíl a budeme kontaktovat každého vydavatele, který to udělá.

Použití modulu PowerShellGet k publikování

Důrazně doporučujeme, aby vydavatelé při práci s Galerie prostředí PowerShell používali tyto Publish-Module rutinyPublish-Script. PowerShellGet byl vytvořen, abyste si nepamatovali důležité podrobnosti 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 nich použít klienta NuGet nebo rutinyPublish-ModulePackageManagement . Existuje řada podrobností, které jsou snadno zmeškané, což vede k řadě žádostí o podporu.

Pokud je důvod, proč nemůžete použít Publish-Module nebo Publish-Scriptnám dejte vědět. Vytvořte problém v úložišti GitHubu PowerShellGet a zadejte podrobnosti, které způsobují výběr NuGetu nebo PackageManagementu.

Pro balíčky publikované v Galerie prostředí PowerShell jsme zjistili co nejspělější přístup:

  • Proveďte počáteční vývoj v opensourcové lokalitě projektu. Tým PowerShellu používá GitHub.
  • Pomocí zpětné vazby od revidujících a Analyzátoru skriptů PowerShellu získejte kód do stabilního stavu.
  • Zahrňte 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 stabilní verzi nebo alfa 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.
  • Do projektu a modulu přidejte 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 1.0.0 verzi do Galerie prostředí PowerShell.
  • Pokračujte ve shromažďování zpětné vazby a iterace kódu na základě uživatelského vstupu.