A PowerShellGallery közzétételi irányelvei és ajánlott eljárásai

  • Cikk

Ez a cikk a Microsoft teams által javasolt lépéseket ismerteti annak biztosítására, hogy a PowerShell-galéria közzétett csomagokat széles körben alkalmazzák, és magas értéket biztosítsanak a felhasználóknak, attól függően, hogy a PowerShell-galéria hogyan kezeli a jegyzékadatokat, valamint a PowerShell-galéria felhasználók nagy számának visszajelzései alapján. Az irányelvek alapján közzétett csomagok nagyobb valószínűséggel lesznek telepítve, megbízhatók és több felhasználót vonzanak.

Az alábbiakban bemutatjuk, hogy mitől jó PowerShell-galéria csomag, melyek a legfontosabbak az opcionális jegyzékbeállítások, a kód továbbfejlesztése a kezdeti véleményezők és a PowerShell-szkriptelemző visszajelzései alapján, a modul verziószámozása, a dokumentáció, a tesztek és példák a megosztott adatok használatára. A dokumentáció nagy része a kiváló minőségű DSC-erőforrásmodulok közzétételére vonatkozó irányelveket követi.

A csomagok PowerShell-galéria való közzétételének mechanikájáért lásd: Csomag létrehozása és közzététele.

Az irányelvekkel kapcsolatos visszajelzéseket szívesen fogadjuk. Ha van visszajelzése, nyissa meg a problémákat a GitHub dokumentációs adattárában.

Ajánlott eljárások a csomagok közzétételéhez

A következő ajánlott eljárások azok, amelyeket a PowerShell-galéria elemek felhasználói fontosnak mondanak, és névleges prioritási sorrendben vannak felsorolva. Az irányelveket követő csomagokat sokkal valószínűbb, hogy mások letöltik és elfogadják.

  • A PSScriptAnalyzer használata
  • Dokumentáció és példák belefoglalása
  • Reagáljon a visszajelzésre
  • Modulok megadása szkriptek helyett
  • Projektwebhelyre mutató hivatkozások megadása
  • A csomag címkézése a kompatibilis PSEdition(ek)sel és platformokkal
  • Tesztek belefoglalása a modulokkal
  • Licencfeltételek belefoglalása és/vagy hivatkozása
  • A kód aláírása
  • A SemVer verziószámozási irányelveinek követése
  • Gyakori címkék használata a Gyakori PowerShell-galéria címkékben leírtak szerint
  • Közzététel tesztelése helyi adattár használatával
  • Közzététel a PowerShellGet használatával

Ezekről az alábbi szakaszokban röviden olvashat.

A PSScriptAnalyzer használata

A PSScriptAnalyzer egy ingyenes statikus kódelemzési eszköz, amely a PowerShell-kódon működik. A PSScriptAnalyzer azonosítja a PowerShell-kódban tapasztalt leggyakoribb problémákat, és gyakran javaslatot tesz a probléma megoldására. Az eszköz könnyen használható, és kategorizálja a problémákat hibák (súlyos, meg kell oldani), figyelmeztetés (meg kell vizsgálni, és meg kell oldani), és információk (érdemes megnézni az ajánlott eljárásokat). A PowerShell-galéria közzétett összes csomagot a PSScriptAnalyzerrel ellenőrzi a rendszer, és a hibák vissza lesznek jelentve a tulajdonosnak, és meg kell oldani őket.

Az ajánlott eljárás a és a figyelmeztetés használata Invoke-ScriptAnalyzer-Recurse-Severity .

Tekintse át az eredményeket, és győződjön meg arról, hogy:

  • A dokumentációban minden hibát kijavítunk vagy kijavítunk.
  • Minden figyelmeztetést áttekintünk, és adott esetben foglalkozunk.

A PowerShell-galéria csomagokat letöltő felhasználókat erősen javasoljuk, hogy futtassa a PSScriptAnalyzert, és értékelje ki az összes hibát és figyelmeztetést. A felhasználók nagy valószínűséggel kapcsolatba lépnek a csomagtulajdonosokkal, ha azt látják, hogy a PSScriptAnalyzer hibát jelentett. Ha a csomagnak meggyőző oka van arra, hogy a hibaként megjelölt kódot megtartsa, adja hozzá ezeket az információkat a dokumentációhoz, hogy ne kelljen többször válaszolnia ugyanarra a kérdésre.

Dokumentáció és példák belefoglalása

A dokumentáció és példák a legjobb módja annak, hogy a felhasználók kihasználhassák a megosztott kódokat.

A dokumentáció a leginkább hasznos, ha a PowerShell-galéria közzétett csomagokban szerepel. A felhasználók általában dokumentáció nélkül kerülik meg a csomagokat, a másik lehetőség, hogy elolvassák a kódot, hogy megértsék, mi a csomag, és hogyan kell használni. A PowerShell-csomagok dokumentációját több cikk is tartalmazza, többek között az alábbiakat:

  • A súgó megadásának irányelvei a Parancsmagok írása súgóban találhatók.
  • A parancsmag súgójának létrehozása, amely a legjobb módszer minden PowerShell-szkripthez, függvényhez vagy parancsmaghoz. A parancsmagok létrehozásáról a Parancsmag írása súgó című témakörben olvashat. Ha segítségre van szüksége egy szkriptben, olvassa el a Megjegyzésalapú súgó című témakört.
  • Számos modul szöveges formátumú dokumentációt is tartalmaz, például MarkDown-fájlokat. Ez különösen hasznos lehet, ha a GitHubon van egy projektwebhely, ahol a Markdown egy erősen használt formátum. Az ajánlott eljárás a GitHub-szerű Markdown használata.

A példák bemutatják a felhasználóknak, hogyan kívánják használni a csomagot. Sok fejlesztő azt fogja mondani, hogy a dokumentáció előtt példákat vizsgálnak meg, hogy megértsék, hogyan kell használni valamit. A legjobb példák az alapszintű használatot, valamint egy szimulált valósághű használati esetet mutatnak be, és a kód jól megjegyezhető. A PowerShell-galéria közzétett modulok példáinak a modulgyöker alatti Examples mappában kell lenniük.

Jó példaminta található a PSDscResource modulban a Examples\RegistryResource mappában. Négy mintahasználati eset található, amelyek mindegyik fájl tetején rövid leírást tartalmaznak, amelyek dokumentálják a bemutatott adatokat.

Függőségek kezelése

Fontos megadni azokat a modulokat, amelyektől a modul függ a moduljegyzékben. Ez lehetővé teszi, hogy a végfelhasználónak ne kelljen aggódnia a modulok megfelelő verzióinak telepítése miatt, amelyekről a felhasználó függőséget vállal. A függő modulok megadásához a moduljegyzékben a szükséges modulmezőt kell használnia. Ez betölti a felsorolt modulokat a globális környezetbe a modul importálása előtt, kivéve, ha már betöltötték őket. Előfordulhat például, hogy egyes modulokat már betölt egy másik modul. A ModuleVersion mező helyett egy adott verziót is megadhat a Betöltéshez a RequiredVersion mezővel. A ModuleVersion használatakor betölti a legújabb elérhető verziót a megadott verzió minimumával. Ha nem a RequiredVersion mezőt használja, egy adott verzió megadásához fontos figyelni a szükséges modul verziófrissítéseit. Különösen fontos tisztában lenni azokkal a kompatibilitástörő változásokkal, amelyek hatással lehetnek a modul felhasználói élményére.

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"})

Visszajelzésre való reagálás

A visszajelzésekre megfelelően válaszoló csomagtulajdonosokat a közösség nagyra értékeli. Azok a felhasználók, akik konstruktív visszajelzést adnak, fontos, hogy válaszoljanak, mivel elég érdekli őket a csomag, hogy megpróbálják javítani.

A PowerShell-galéria egy visszajelzési módszer érhető el:

  • Kapcsolat tulajdonosa: Ez lehetővé teszi, hogy a felhasználó e-mailt küldjön a csomag tulajdonosának. Csomagtulajdonosként fontos figyelni a PowerShell-galéria csomagokkal használt e-mail-címet, és válaszolni a felmerülő problémákra. Ennek a módszernek az egyetlen hátránya, hogy csak a felhasználó és a tulajdonos fogja látni a kommunikációt, így előfordulhat, hogy a tulajdonosnak többször is válaszolnia kell erre a kérdésre.

Azok a tulajdonosok, akik konstruktívan válaszolnak a visszajelzésekre, értékelik a közösség. További információ kéréséhez használja a jelentésben található lehetőséget. Szükség esetén adjon meg egy áthidaló megoldást, vagy állapítsa meg, hogy egy frissítés megoldja-e a problémát.

Ha a kommunikációs csatornák egyikében nem megfelelő viselkedés figyelhető meg, a PowerShell-galéria Jelentéssel való visszaélés funkciójával lépjen kapcsolatba a katalógusgazdával.

Modulok és szkriptek

A szkriptek megosztása más felhasználókkal nagyszerű, és példákat kínál másoknak az esetleges problémák megoldására. A probléma az, hogy a PowerShell-galéria szkriptjei különálló dokumentációt, példákat és teszteket nem tartalmazó fájlok.

A PowerShell-modulok olyan mappastruktúrával rendelkeznek, amely lehetővé teszi, hogy több mappa és fájl is szerepeljen a csomagban. A modulstruktúra lehetővé teszi, hogy a többi csomagot ajánlott eljárásként soroljuk fel: a parancsmag súgóját, a dokumentációt, a példákat és a teszteket. A legnagyobb hátránya, hogy egy modulon belüli szkriptet közzé kell tenni, és függvényként kell használni. A modul létrehozásával kapcsolatos információkért lásd: Windows PowerShell modul írása.

Vannak olyan helyzetek, amikor a szkriptek jobb élményt nyújtanak a felhasználó számára, különösen a DSC-konfigurációk esetében. A DSC-konfigurációk ajánlott eljárása a konfiguráció szkriptként való közzététele a dokumentumokat, példákat és teszteket tartalmazó kísérő modullal. A szkript felsorolja a kísérő modult a használatával RequiredModules = @(Name of the Module). Ez a megközelítés bármilyen szkripttel használható.

Az egyéb ajánlott eljárásokat követő önálló szkriptek valós értéket biztosítanak a többi felhasználó számára. A parancsfájlok PowerShell-galéria való közzétételekor erősen ajánlott megjegyzésalapú dokumentációt és egy projektwebhelyre mutató hivatkozást megadni.

A projektwebhelyen a közzétevők közvetlenül kommunikálhatnak a PowerShell-galéria-csomagjaik felhasználóival. A felhasználók az ezt biztosító csomagokat részesítik előnyben, mivel lehetővé teszik számukra, hogy könnyebben lekérjék a csomaggal kapcsolatos információkat. A PowerShell-galéria számos csomagja a GitHubon lett kifejlesztve, mások pedig dedikált webes jelenléttel rendelkező szervezetek. Ezek mindegyike projektwebhelynek tekinthető.

A hivatkozás hozzáadásához vegye fel a ProjectURI-t a jegyzék PSData szakaszában az alábbiak szerint:

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

Ha meg van adva a ProjectURI, a PowerShell-galéria tartalmazni fog egy hivatkozást a projektwebhelyre a csomaglap bal oldalán.

A csomag címkézése a kompatibilis PSEdition(ek)sel és platformokkal

Az alábbi címkékkel bemutathatja a felhasználóknak, hogy mely csomagok fognak jól működni a környezetükkel:

  • PSEdition_Desktop: A Windows PowerShell kompatibilis csomagok
  • PSEdition_Core: A PowerShell 6-os és újabb verzióival kompatibilis csomagok
  • Windows: A Windows operációs rendszerrel kompatibilis csomagok
  • Linux: Linux operációs rendszerekkel kompatibilis csomagok
  • MacOS: A Mac operációs rendszerrel kompatibilis csomagok

Ha a csomagot a kompatibilis platform(ok)tal címkézi, az megjelenik a keresési eredmények bal oldali paneljén található Katalógus keresési szűrői között. Ha a csomagot a GitHubon üzemelteti, a csomag címkézésekor a PowerShell-galéria kompatibilitási pajzs kompatibilitásipajzs példáját is kihasználhatja.

Tesztek belefoglalása

A nyílt forráskódú kóddal rendelkező tesztek felvétele fontos a felhasználók számára, mivel biztosítja számukra, hogy mit ellenőriznek, és információt nyújtanak a kód működéséről. Emellett lehetővé teszi a felhasználók számára, hogy ne szegjék meg az eredeti funkciót, ha a kódot a környezetüknek megfelelően módosítják.

Erősen ajánlott a teszteket úgy írni, hogy kihasználják a Kifejezetten a PowerShellhez tervezett Pester tesztelési keretrendszert. A Pester elérhető a GitHubon, a PowerShell-galéria és a hajókon Windows 10, Windows Server 2016, WMF 5.0 és WMF 5.1 rendszerben.

A GitHub Pester projektwebhelye jó dokumentációt tartalmaz a Pester-tesztek írásáról, az első lépésektől az ajánlott eljárásokig.

A tesztlefedettség céljait a Magas minőségű erőforrásmodul dokumentációja ismerteti, és a 70%-os egységtesztelési kódlefedettség ajánlott.

A PowerShell-galéria közzétett összes csomagnak meg kell adnia a licencfeltételeket, vagy kötelezőnek kell lennie az A. kiállítás alatti használati feltételekben foglalt licencnek. Egy másik licenc megadásának legjobb módszere a licencre mutató hivatkozás megadása a PSDatalicencURI-jának használatával. További információ: Csomagok jegyzékfájlja és katalógus felhasználói felülete.

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'

A kód aláírása

A kódaláírás biztosítja a felhasználók számára a legmagasabb szintű garanciát a csomag közzétételének kiére vonatkozóan, és hogy az általuk beszerzett kód másolata pontosan az, amit a közzétevő kiadott. A kódaláírással kapcsolatos általános információkért lásd: Bevezetés a kódaláírásba. A PowerShell két elsődleges megközelítéssel támogatja a kódaláírás ellenőrzését:

  • Szkriptfájlok aláírása
  • Modul aláírásának katalógusa

A PowerShell-fájlok aláírása egy jól bevált módszer annak biztosítására, hogy a végrehajtott kódot egy megbízható forrás hozta létre, és nem módosították. A PowerShell-szkriptfájlok aláírásával kapcsolatos részletekért tekintse meg az Aláírással kapcsolatos cikket. Az áttekintésben minden .PS1 olyan fájlhoz hozzáadhat aláírást, amelyet a PowerShell ellenőriz a szkript betöltésekor. A PowerShell a végrehajtási szabályzat parancsmagjaival korlátozható az aláírt szkriptek használatának biztosítása érdekében.

A katalógus-aláíró modulok a PowerShell 5.1-es verziójában hozzáadott funkciók. A modul aláírásáról a Katalógusparancsmagok című cikkben olvashat. Az áttekintésben a katalógus-aláírás egy katalógusfájl létrehozásával történik, amely a modul minden fájljának kivonatértékét tartalmazza, majd aláírja a fájlt.

A PowerShellGetPublish-Module, Install-Modulea és Update-Module a parancsmagok ellenőrzik az aláírást, és ellenőrzik, hogy érvényes-e, majd ellenőrizze, hogy az egyes csomagok kivonatértéke megegyezik-e a katalógusban található értékkel. Save-Module nem ellenőrzi az aláírást. Ha a modul egy korábbi verziója van telepítve a rendszeren, megerősíti, Install-Module hogy az új verzió aláíró hatósága megegyezik a korábban telepített verzióval. Install-Module és Update-Module az aláírást fogja használni egy .PSD1 fájlon, ha a csomag nincs aláírva a katalógusban. A katalógus-aláírás működik, de nem helyettesíti az aláíró szkriptfájlokat. A PowerShell nem ellenőrzi a katalógus-aláírásokat a modul betöltésekor.

A SemVer verziószámozásra vonatkozó irányelveinek követése

A SemVer egy nyilvános konvenció, amely leírja, hogyan strukturálhatja és módosíthatja a verziót, hogy lehetővé tegye a változások egyszerű értelmezését. A csomag verziójának szerepelnie kell a jegyzékadatokban.

  • A verziót három numerikus blokkként kell strukturálni, pontokkal elválasztva, mint a vagy 4.11.192a fájlban0.1.1.
  • A következővel 0 kezdődő verziók azt jelzik, hogy a csomag még nem áll készen az éles üzemre, és az első szám csak akkor kezdődhet 0 , ha ez az egyetlen használt szám.
  • Az első szám változásai (1.9.9999 a) 2.0.0-ban a verziók közötti jelentős és kompatibilitástörő változásokat jelzik.
  • A második szám (1.1 )-ra 1.2történő módosítása funkciószintű változásokat jelez, például új parancsmagok hozzáadása egy modulhoz.
  • A harmadik szám módosításai nem kompatibilitástörő változásokat jeleznek, például új paramétereket, frissített mintákat vagy új teszteket.
  • A verziók listázásakor a PowerShell sztringekként rendezi a verziókat, így 1.01.0 a rendszer nagyobbként kezeli őket, mint 1.001.0.

A PowerShell a SemVer közzététele előtt lett létrehozva, így a SemVer legtöbb eleméhez, de nem minden eleméhez nyújt támogatást, különösen:

  • Nem támogatja az előzetes sztringeket a verziószámokban. Ez akkor hasznos, ha egy közzétevő egy új főverzió előzetes kiadását szeretné kiadni egy verzió 1.0.0megadása után. Ez a PowerShell-galéria és a PowerShellGet-parancsmagok egy későbbi kiadásában lesz támogatott.
  • A PowerShell és a PowerShell-galéria 1, 2 és 4 szegmenst tartalmazó verziósztringeket engedélyeznek. Számos korai modul nem követte az irányelveket, és a Microsoft termékkiadásai a buildadatokat 4. számblokkként tartalmazzák (például 5.1.14393.1066). Verziószámozási szempontból a rendszer figyelmen kívül hagyja ezeket a különbségeket.

Tesztelés helyi adattár használatával

A PowerShell-galéria nem a közzétételi folyamat tesztelésére szolgálnak. A PowerShell-galéria való közzététel végpontok közötti folyamatának tesztelésének legjobb módja a saját helyi adattár beállítása és használata. Ez többféleképpen is elvégezhető, például:

  • Állítson be egy helyi PowerShell-galéria-példányt a Ps Private Gallery projekt használatával a GitHubon. Ez az előzetes verziójú projekt segít beállítani a PowerShell-galéria egy példányát, amelyet szabályozhat, és használhat a tesztekhez.
  • Állítson be egy belső Nuget-adattárat. Ez több munkát igényel a beállításhoz, de azzal az előnnyel jár, hogy még néhány követelményt érvényesít, nevezetesen egy API-kulcs használatát, valamint azt, hogy a közzétételkor vannak-e függőségek a célban.
  • Állítson be egy fájlmegosztást tesztadattárként. Ez egyszerűen beállítható, de mivel fájlmegosztásról van szó, a fent említett ellenőrzések nem fognak végbevenni. Ebben az esetben az egyik lehetséges előnye, hogy a fájlmegosztás nem ellenőrzi a szükséges API-kulcsot, így ugyanazt a kulcsot használhatja, amelyet a PowerShell-galéria való közzétételhez használna.

Ezen megoldások Register-PSRepository bármelyikével definiálhat egy új adattárat, amelyet a -Repository paraméterben Publish-Modulehasznál.

Egy további pont a tesztelési közzétételről: a PowerShell-galéria közzétett csomagok nem törölhetők az üzemeltetési csapat segítsége nélkül, akik megerősítik, hogy semmi sem függ a közzétenni kívánt csomagtól. Ezért nem támogatjuk a PowerShell-galéria tesztelési célként, és kapcsolatba lépünk bármely közzétevővel, aki ezt teszi.

Közzététel a PowerShellGet használatával

Erősen ajánlott, hogy a közzétevők a és Publish-Script a Publish-Module parancsmagot használják a PowerShell-galéria használatakor. A PowerShellGet azért lett létrehozva, hogy elkerülje a telepítéssel és a PowerShell-galéria való közzétételsel kapcsolatos fontos részletek megjegyzését. A közzétevők időnként úgy döntöttek, hogy kihagyják a PowerShellGetet , és a Helyett a NuGet-ügyfelet vagy a PackageManagement parancsmagokat használják Publish-Module. Számos olyan részlet van, amelyet könnyen kihagyhat, ami számos támogatási kérést eredményez.

Ha valamilyen okból nem Publish-Module használhatja a vagy Publish-Scripta parancsot, kérjük, tudassa velünk. Jelentse be a problémát a PowerShellGet GitHub-adattárban, és adja meg azokat a részleteket, amelyek miatt a NuGet vagy a PackageManagement lehetőséget választja.

A PowerShell-galéria közzétett csomagok esetében a legsikeresebb módszer a következő:

  • Végezze el a kezdeti fejlesztést egy nyílt forráskódú projektwebhelyen. A PowerShell csapata a GitHubot használja.
  • A véleményezők és a PowerShell Script Analyzer visszajelzései alapján állítsa stabil állapotba a kódot.
  • A dokumentációt is belefoglalhatja, hogy mások is tudják, hogyan használhatja a munkáját.
  • Tesztelje a közzétételi műveletet egy helyi adattár használatával.
  • Tegyen közzé egy stabil vagy alfa kiadást a PowerShell-galéria, és mindenképpen mellékelje a dokumentációt és a projektwebhelyre mutató hivatkozást.
  • Gyűjtsön visszajelzést és iterálja a projektwebhely kódját, majd tegye közzé a stabil frissítéseket a PowerShell-galéria.
  • Példák és Pester-tesztek hozzáadása a projekthez és a modulhoz.
  • Döntse el, hogy kódolni szeretné-e a csomag aláírását.
  • Ha úgy érzi, hogy a projekt készen áll az éles környezetben való használatra, tegyen közzé egy verziót 1.0.0 a PowerShell-galéria.
  • Továbbra is gyűjtsön visszajelzést, és a felhasználói bevitel alapján iterálja a kódot.