Vytvoření a publikování položky

  • Článek

Galerie prostředí PowerShell je místo, kde můžete publikovat a sdílet stabilní moduly PowerShellu, skripty a prostředky Desired State Configuration (DSC) s širší komunitou uživatelů PowerShellu.

Tento článek se zabývá mechanikou a důležitými kroky pro přípravu skriptu nebo modulu a jeho publikování na Galerie prostředí PowerShell. Důrazně doporučujeme, abyste si prostudovali pokyny pro publikování, abyste pochopili, jak zajistit, aby položky, které publikujete, byly široce přijímány Galerie prostředí PowerShell uživateli.

Minimální požadavky na publikování položky na Galerie prostředí PowerShell jsou:

  • Mít účet Galerie prostředí PowerShell a klíč rozhraní API přidružený k němu
  • Ujistěte se, že se v položce nachází Požadovaná metadata.
  • Pomocí nástrojů pro předběžné ověření se ujistěte, že je vaše položka připravená k publikování.
  • Publikování položky do Galerie prostředí PowerShell pomocí příkazů Publish-Module a Publish-Script
  • Reagování na dotazy nebo nejasnosti týkající se vaší položky

Galerie prostředí PowerShell přijímá moduly PowerShellu a skripty PowerShellu. Když odkazujeme na skripty, máme na mysli skript PowerShellu, který je jedním souborem a není součástí většího modulu.

Postup nastavení účtu Galerie prostředí PowerShell najdete v tématu Vytvoření účtu Galerie prostředí PowerShell.

Po vytvoření účtu můžete získat klíč rozhraní API potřebný k publikování položky. Po přihlášení pomocí účtu se vaše uživatelské jméno zobrazí v horní části Galerie prostředí PowerShell stránek místo registrace. Kliknutím na své uživatelské jméno přejdete na stránku Můj účet, kde najdete klíč rozhraní API.

Důležité

S klíčem rozhraní API se musí zacházet stejně bezpečně jako s vaším přihlašovacím údajem a heslem. Pomocí tohoto klíče můžete vy nebo kdokoli jiný aktualizovat libovolnou položku, kterou vlastníte v Galerie prostředí PowerShell. Doporučujeme klíč pravidelně aktualizovat, což je možné provést pomocí resetování klíče na stránce Můj účet.

Galerie prostředí PowerShell poskytuje informace uživatelům galerie z polí metadat, která jsou součástí skriptu nebo manifestu modulu. Vytváření nebo úpravy položek pro publikování na Galerie prostředí PowerShell má malou sadu požadavků na informace zadané v manifestu položky. Důrazně doporučujeme, abyste si prostudovali část Metadata položek v pokynech pro publikování , kde se dozvíte, jak poskytnout uživatelům s vašimi položkami ty nejlepší informace.

Rutiny New-ModuleManifest a New-ScriptFileInfo vytvoří šablonu manifestu se zástupnými symboly pro všechny prvky manifestu.

Oba manifesty mají dvě části, které jsou důležité pro publikování, a to oblast Data primárního klíče a PSData privateData. Data primárního klíče v manifestu modulu PowerShellu jsou všechno mimo část PrivateData. Sada primárních klíčů je svázaná s verzí PowerShellu, která se používá, a nedefinované se nepodporují. PrivateData podporuje přidávání nových klíčů, takže prvky specifické pro Galerie prostředí PowerShell jsou v PSData.

Elementy manifestu, které jsou nejdůležitější pro vyplnění položky, kterou publikujete do Galerie prostředí PowerShell, jsou:

  • Název skriptu nebo modulu – tyto názvy pocházejí z názvů .PS1 pro skript nebo . PSD1 pro modul.
  • Verze – toto je povinný primární klíč, formát by měl odpovídat pokynům semVer. Podrobnosti najdete v tématu Osvědčené postupy.
  • Autor – jedná se o požadovaný primární klíč, který obsahuje název, který se má přidružit k položce. Viz Autoři a vlastníci níže.
  • Popis – jedná se o požadovaný primární klíč, který slouží ke stručné vysvětlení toho, co tato položka dělá, a případné požadavky na použití.
  • ProjectURI – toto je důrazně doporučené pole identifikátoru URI v PSData, které poskytuje odkaz na úložiště GitHub nebo podobné umístění, kde provádíte vývoj pro danou položku.
  • Značky – důrazně doporučujeme označit balíček na základě jeho kompatibility s PSEditions a platformami. Podrobnosti najdete v pokynech pro publikování.

Autoři a vlastníci Galerie prostředí PowerShell položek jsou související koncepty, ale ne vždy se shodují. Vlastníci položek jsou uživatelé s účty Galerie prostředí PowerShell, kteří mají oprávnění k údržbě položky. Může existovat mnoho vlastníků, kteří můžou aktualizovat libovolnou položku. Vlastník je k dispozici pouze v Galerie prostředí PowerShell a je ztracen, pokud je položka zkopírována z jednoho systému do jiného. Author je řetězec, který je integrovaný do dat manifestu, takže je vždy součástí položky. Doporučení pro položky z produktů Microsoftu:

  • Mít více vlastníků, přičemž alespoň jeden z nich je název týmu, který danou položku vytváří.
  • Požádejte autora, aby byl dobře známý název týmu (například tým sady Azure SDK) nebo Microsoft Corporation.

Předběžné ověření položky

Před publikováním položky do Galerie prostředí PowerShell je potřeba spustit v kódu několik nástrojů:

  • Analyzátor skriptů PowerShellu, který je v Galerie prostředí PowerShell
  • Pro moduly Test-ModuleManifest, který je součástí PowerShellu
  • Pro skripty Test-ScriptFileInfo, které jsou součástí PowerShellu Get

Analyzátor skriptů PowerShellu je nástroj pro analýzu statického kódu, který zkontroluje kód, aby se ujistil, že splňuje základní pokyny pro kódování PowerShellu. Tento nástroj identifikuje běžné a kritické problémy ve vašem kódu a měl by se spouštět pravidelně během vývoje, aby vám pomohl připravit položku k publikování. Analyzátor skriptů PowerShellu zobrazí seznam problémů identifikovaných jako chyby, upozornění a informace. Před publikováním do Galerie prostředí PowerShell je nutné vyřešit všechny chyby. Upozornění je potřeba zkontrolovat a většinu z nich byste měli řešit. Analyzátor skriptů PowerShellu se spustí při každém publikování nebo aktualizaci položky v Galerie prostředí PowerShell. Provozní tým galerie bude kontaktovat vlastníky položek a řešit zjištěné chyby.

Pokud Galerie prostředí PowerShell infrastruktura nemůže přečíst informace manifestu v položce, nebudete moct publikovat. Test-ModuleManifest zachytí běžné problémy, které by způsobily, že modul nebude při instalaci použitelný. Před publikováním do Galerie prostředí PowerShell musí být spuštěn pro každý modul.

Podobně Test-ScriptFileInfo ověřuje metadata ve skriptu a musí být spuštěn na každém skriptu (publikovaném odděleně od modulu) před jeho publikováním do Galerie prostředí PowerShell.

Položky publikování

K publikování položek do Galerie prostředí PowerShell je nutné použít publish-Script nebo Publish-Module. Oba tyto příkazy vyžadují:

  • Cesta k položce, kterou budete publikovat. Pro modul použijte složku s názvem pro váš modul. Pokud zadáte složku, která obsahuje více verzí stejného modulu, musíte zadat RequiredVersion.
  • Klíč rozhraní API NuGet. Toto je klíč rozhraní API, který najdete na stránce Můj účet na Galerie prostředí PowerShell.

Většina ostatních možností v příkazovém řádku by měla být v datech manifestu pro položku, kterou publikujete, takže byste je neměli zadávat v příkazu.

Abyste se vyhnuli chybám, důrazně doporučujeme před publikováním vyzkoušet příkazy pomocí příkazu -WhatIf -Verbose. Tím ušetříte spoustu času, protože pokaždé, když publikujete do Galerie prostředí PowerShell, musíte aktualizovat číslo verze v části manifestu položky.

Příklady:

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Pečlivě si prohlédněte výstup, a pokud se nezobrazí žádné chyby nebo upozornění, opakujte příkaz bez příkazu -WhatIf.

Všechny položky publikované do Galerie prostředí PowerShell budou kontrolovány na přítomnost virů a budou analyzovány pomocí Analyzátoru skriptů PowerShellu. Všechny problémy, které v daném okamžiku vzniknou, budou odeslány zpět vydavateli k vyřešení.

Jakmile publikujete položku na Galerie prostředí PowerShell, budete muset watch pro zpětnou vazbu k dané položce.

  • Ujistěte se, že monitorujete e-mailovou adresu přidruženou k účtu použitému k publikování. Uživatelé a tým Galerie prostředí PowerShell Operations vám prostřednictvím daného účtu poskytnou zpětnou vazbu, včetně problémů z PSSA nebo antivirových kontrol. Pokud je e-mailový účet neplatný nebo pokud jsou mu nahlášeny závažné problémy a zůstanou dlouho nevyřešeny, je možné položky považovat za opuštěné a budou odebrány z Galerie prostředí PowerShell, jak je popsáno v našich podmínkách použití.