Galériabeli közzétételi irányelvek és ajánlott eljárásokPowerShellGallery Publishing Guidelines and Best Practices

Ez a cikk azokat a javasolt lépéseket ismerteti, amelyeket a Microsoft Teams használ a PowerShell-galéria közzétett csomagok széles körben való elfogadására és magas érték biztosítására a felhasználók számára, attól függően, hogy a PowerShell-galéria hogyan kezeli a jegyzékfájlok adatait és a nagy számú PowerShell-galéria felhasználó visszajelzéseit.This article describes recommended steps used by Microsoft teams to ensure the packages published to the PowerShell Gallery will be widely adopted and provide high value to users, based on how the PowerShell Gallery handles manifest data and on feedback from large numbers of PowerShell Gallery users. Az ezen irányelvek alapján közzétett csomagok nagyobb valószínűséggel lesznek telepítve, megbízhatóak, és több felhasználót vonzanak.Packages that are published following these guidelines will be more likely to be installed, trusted, and attract more users.

Az alábbi irányelvek azt ismertetik, hogy mit tesz a jó PowerShell-galéria csomag, mely opcionálisan használható jegyzék-beállítások a legfontosabbak, a kód fejlesztése a kezdeti felülvizsgálók és a PowerShell-parancsfájlok elemzője, a modul verziószámozása, a dokumentáció, a tesztek és példák a megosztott adatok használatára.Included below are guidelines for what makes a good PowerShell Gallery package, what optional Manifest settings are most important, improving your code with feedback from initial reviewers and Powershell Script Analyzer, versioning your module, documentation, tests and examples for how to use what you have shared. A dokumentáció nagy része a kiváló minőségű DSC-erőforrás-modulokközzétételének irányelveit követi.Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

A csomagok a PowerShell-galéria való közzétételének mechanikája: csomagok létrehozása és közzététele.For the mechanics of publishing a package to the PowerShell Gallery, see Creating and Publishing a Package.

Az irányelvekről szóló visszajelzések üdvözölve vannak.Feedback on these guidelines is welcomed. Ha visszajelzést szeretne küldeni, nyissa meg a GitHub dokumentációs tárházábantalálható problémákat.If you do have feedback, please open issues in our GitHub documentation repository.

Ajánlott eljárások a csomagok közzétételéhezBest practices for publishing packages

A következő ajánlott eljárások azt ismertetik, hogy a PowerShell-galéria elemek felhasználói milyen fontosak, és a névleges prioritási sorrendben vannak felsorolva.The following best practices are what the users of PowerShell Gallery items say is important, and are listed in nominal priority order. Az ezeket az irányelveket követő csomagokat sokkal nagyobb eséllyel töltik le és fogadják el mások.Packages that follow these guidelines are far more likely to be downloaded and adopted by others.

  • PSScriptAnalyzer használataUse PSScriptAnalyzer
  • Dokumentációval és példákkal együttInclude documentation and examples
  • Válaszoljon a visszajelzésreBe responsive to feedback
  • Parancsfájlok helyett a modulok megadásaProvide modules rather than scripts
  • A Project-helyre mutató hivatkozások megadásaProvide links to a project site
  • A csomag címkézése a kompatibilis PSEdition (s) és platformokkalTag your package with the compatible PSEdition(s) and platforms
  • Tesztek belefoglalása a modulokkalInclude tests with your modules
  • Licencfeltételek belefoglalása és/vagy hivatkozásaInclude and/or link to license terms
  • A kód aláírásaSign your code
  • SemVer -irányelvek követése a verziószámozáshozFollow SemVer guidelines for versioning
  • Általános címkék használata a közös PowerShell-galéria címkékben dokumentálvaUse common tags, as documented in Common PowerShell Gallery tags
  • Közzététel tesztelése helyi tárház használatávalTest publishing using a local repository
  • Közzététel a PowerShellGet használatávalUse PowerShellGet to publish

Ezek mindegyikét röviden az alábbi részekben tárgyaljuk.Each of these is covered briefly in the sections below.

PSScriptAnalyzer használataUse PSScriptAnalyzer

A PSScriptAnalyzer egy ingyenes, statikus kód-elemzési eszköz, amely PowerShell-kódban működik.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. A PSScriptAnalyzer azonosítja a PowerShell-kódban leggyakrabban előforduló problémákat, és gyakran a probléma megoldására vonatkozó javaslatot is tartalmaz.PSScriptAnalyzer will identify the most common issues seen in PowerShell code, and often a recommendation for how to fix the issue. Az eszköz könnyen használható, és kategorizálja a hibákat (súlyos, kezelendő), a figyelmeztetést (meg kell vizsgálni és kezelni kell), és információt (érdemes megnézni az ajánlott eljárásokat).The tool is easy to use, and categorizes the issues as Errors (severe, must be addressed), Warning (need to be reviewed and should be addressed), and Information (worth checking out for best practices). A PowerShell-galéria közzétett összes csomagot a rendszer a PSScriptAnalyzer használatával vizsgálja, és az esetleges hibákat visszaküldi a tulajdonosnak, és meg kell oldania.All packages published to the PowerShell Gallery will be scanned using PSScriptAnalyzer , and any errors will be reported back to the owner and must be addressed.

Az ajánlott eljárás az, hogy a és a figyelmeztetés használatával fusson Invoke-ScriptAnalyzer -Recurse -Severity .The best practice is to run Invoke-ScriptAnalyzer with -Recurse and -Severity Warning.

Tekintse át az eredményeket, és ügyeljen rá, hogy:Review the results, and ensure that:

  • A rendszer az összes hibát korrigálja vagy megtárgyalja a dokumentációjában.All Errors are corrected or addressed in your documentation.
  • A rendszer minden figyelmeztetést felülvizsgál, és ahol szükséges.All Warnings are reviewed, and addressed where applicable.

Azok a felhasználók, akik csomagokat töltenek le a PowerShell-galériaről, erősen javasoltak a PSScriptAnalyzer futtatására és az összes hiba és figyelmeztetés kiértékelésére.Users who download packages from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. A felhasználók nagyon valószínű, hogy felveszik a kapcsolatot a csomag tulajdonosainak, ha látják, hogy a PSScriptAnalyzer által jelentett hiba történt.Users are very likely to contact package owners if they see that there's an error reported by PSScriptAnalyzer . Ha a csomagnak olyan meggyőző oka van, hogy megtartja a hibát jelző kódot, vegye fel ezeket az információkat a dokumentációba, hogy ne kelljen ugyanarra a kérdésre többször válaszolnia.If there's a compelling reason for your package to keep code that is flagged as an error, add that information to your documentation to avoid having to answer the same question many times.

Dokumentációval és példákkal együttInclude documentation and examples

A dokumentáció és a példák a legjobb módszer annak biztosítására, hogy a felhasználók kihasználhatják a megosztott kódokat.Documentation and examples are the best way to ensure users can take advantage of any shared code.

A dokumentáció a leghasznosabb dolog a PowerShell-galéria közzétett csomagokba való felvételhez.Documentation is the most helpful thing to include in packages published to the PowerShell Gallery. A felhasználók általában a dokumentáció nélkül fogják megkerülni a csomagokat, mivel a másik lehetőség a kód beolvasása, hogy megtudja, mi a csomag, és hogyan használható.Users will generally bypass packages without documentation, as the alternative is to read the code to understand what the package is and how to use it. Több cikk is rendelkezésre áll, amelyekkel megtudhatja, hogyan biztosíthat dokumentációt PowerShell-csomagokkal, beleértve a következőket:There are several articles available about how to provide documentation with PowerShell packages, including:

  • A Súgó megadására vonatkozó irányelvek a parancsmag súgójában olvashatók.Guidelines for providing help are in How to Write Cmdlet Help.
  • A parancsmag súgójának létrehozása, amely a legjobb módszer a PowerShell-parancsfájlok, a függvények vagy a parancsmagok számára.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. A parancsmag súgójának létrehozásával kapcsolatos további információkért Kezdje a parancsmagok súgójának írásával.For information about how to create cmdlet help, start with How to Write Cmdlet Help. Ha egy parancsfájlon belül szeretne segítséget adni, olvassa el a megjegyzések alapján kapcsolatos súgót.To add help within a script, see About Comment Based Help.
  • Számos modul szöveges formátumban is tartalmaz dokumentációt, például MarkDown-fájlokat.Many modules also include documentation in text format, such as MarkDown files. Ez különösen hasznos lehet, ha a GitHubon van egy Markdown, ahol a nagy mértékben használt formátum.This can be particularly helpful when there's a project site in GitHub, where Markdown is a heavily used format. Az ajánlott eljárás a GitHub-ízű Markdownhasználata.The best practice is to use GitHub-flavored Markdown.

A példák azt mutatják be, hogy a csomag mely felhasználók számára készült.Examples show users how the package is intended to be used. Számos fejlesztő azt fogja mondani, hogy példákat mutatnak be a dokumentációra, hogy megértsük, hogyan kell használni valamit.Many developers will say that they look at examples before documentation to understand how to use something. A legjobb példák az alapszintű használatra, valamint egy szimulált reális használati esetre mutatnak, és a kód jól kommentálva van.The best types of examples show basic use, plus a simulated realistic use case, and the code is well-commented. A PowerShell-galéria közzétett modulokra példákat kell megadni a modul gyökerének egyik példás mappájába.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

A példákhoz jó példa található a mappa alatti PSDscResource modulban Examples\RegistryResource .A good pattern for examples can be found in the PSDscResource module under the Examples\RegistryResource folder. Négy minta használati eset van az egyes fájlok tetején található rövid leírással, amely a dokumentált dokumentációt mutatja.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Függőségek kezeléseManage Dependencies

Fontos megadnia azokat a modulokat, amelyeken a modul a modul jegyzékfájljában függ.It's important to specify modules that your module is dependent on in the Module Manifest. Ez lehetővé teszi, hogy a végfelhasználó ne kelljen aggódnia a modulok megfelelő verzióinak telepítésével kapcsolatban.This allows the end user to not have to worry about installing the proper versions of modules that yours take a dependency on. A függő modulok megadásához használja a modul jegyzékfájljának szükséges modul mezőjét.To specify dependent modules, you should use the required module field in the module manifest. Ezzel betölti a felsorolt modulokat a globális környezetbe a modul importálása előtt, kivéve, ha már be lettek töltve.This will load any listed modules into the global environment prior to importing your module unless they've already been loaded. Előfordulhat például, hogy egyes modulokat már egy másik modul is betölt.For example, some modules may already be loaded by a different module. Egy adott verziót is meg lehet adni a betöltéshez a ModuleVersion mező helyett a RequiredVersion mező használatával.It's also possible to specify a specific version to load using the RequiredVersion field rather than the ModuleVersion field. A ModuleVersion használatakor a rendszer az elérhető legújabb verziót fogja betölteni legalább a megadott verzióval.When using ModuleVersion , it will load the newest version available with a minimum of the version specified. Ha nem használja a RequiredVersion mezőt, egy adott verziót kell megadnia, fontos a verzió frissítéseinek figyelése a szükséges modulra.When not using the RequiredVersion field, to specify a specific version it's important to monitor version updates to the required module. Különösen fontos, hogy tisztában legyenek az összes olyan változással, amely hatással lehet a modul felhasználói élményére.It's especially important to be aware of any breaking changes that could affect the user experience with your module.

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

Válasz a visszajelzésreRespond to feedback

A megfelelő visszajelzésre válaszoló csomagok tulajdonosai a Közösségnek igen értékesek.Package owners who respond properly to feedback are highly valued by the community. Azok a felhasználók, akik konstruktív visszajelzést adnak, fontosak a válaszadásra, hiszen a csomagban elég érdeklik, hogy segítsenek a fejlesztésben.Users who provide constructive feedback are important to respond to, as they're interested enough in the package to try to help improve it.

A PowerShell-galériaban egy visszajelzési módszer érhető el:There is one feedback method available in the PowerShell Gallery:

  • Kapcsolatfelvétel a tulajdonossal: Ez lehetővé teszi, hogy a felhasználó e-mailt küldjön a csomag tulajdonosának.Contact Owner: This allows a user to send an email to the package owner. A csomag tulajdonosaként fontos figyelni a PowerShell-galéria-csomagokhoz használt e-mail-címet, és reagálni a felmerült problémákra.As a package owner, is important to monitor the email address used with the PowerShell Gallery packages, and respond to issues that are raised. Ennek a módszernek a hátránya, hogy csak a felhasználó és a tulajdonos fogja látni a kommunikációt, így a tulajdonosnak többször is meg kell válaszolnia ugyanazt a kérdést.The one disadvantage to this method is that only the user and owner will ever see the communication, so the owner may have to answer the same question many times.

A Közösség méltányolja a visszajelzésre reagáló tulajdonosokat.Owners who respond to feedback constructively are appreciated by the community. További információk kéréséhez használja a jelentésben szereplő lehetőséget.Use the opportunity in the report to request more information. Ha szükséges, adjon meg egy megkerülő megoldást, vagy állapítsa meg, hogy egy frissítés javít-e egy problémát.If needed, provide a workaround, or identify if an update fixes a problem.

Ha nem áll rendelkezésre megfelelő viselkedés a fenti kommunikációs csatornák egyikéről sem, használja a PowerShell-galéria jelentési visszaélés funkcióját, hogy kapcsolatba lépjen a gyűjtemény rendszergazdáinak.If there's inappropriate behavior observed from either of these communication channels, use the Report Abuse feature of the PowerShell Gallery to contact the Gallery Administrators.

Modulok és parancsfájlokModules Versus Scripts

A szkriptek más felhasználókkal való megosztása nagyszerű megoldás, és többek között az esetlegesen felmerülő problémák megoldásához nyújt példákat.Sharing a script with other users is great, and provides others with examples of how to solve problems they may have. A probléma az, hogy a PowerShell-galéria található parancsfájlok külön dokumentáció, példák és tesztek nélkül önálló fájlok.The issue is that scripts in the PowerShell Gallery are single files without separate documentation, examples, and tests.

A PowerShell-modulok rendelkeznek olyan mappastruktúrát, amely lehetővé teszi több mappa és fájl felvételét a csomagba.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. A modul szerkezete lehetővé teszi, hogy a többi csomag az ajánlott eljárásoknak megfelelően legyen felsorolva: parancsmag Súgó, dokumentáció, példák és tesztek.The module structure enables including the other packages we list as best practices: cmdlet help, documentation, examples, and tests. A legnagyobb hátránya, hogy egy modulon belüli szkriptet ki kell tenni, és függvényként kell használni.The biggest disadvantage is that a script inside a module must be exposed and used as a function. A modulok létrehozásával kapcsolatos információkért lásd: Windows PowerShell-modul írása.For information on how to create a module, see Writing a Windows PowerShell Module.

Vannak olyan helyzetek, amikor egy parancsfájl jobb felhasználói élményt nyújt a felhasználónak, különösen a DSC-konfigurációk esetében.There are situations where a script provides a better experience for the user, particularly with DSC configurations. A DSC-konfigurációk ajánlott gyakorlata, hogy a konfigurációt a dokumentumokat, példákat és teszteket tartalmazó csatolt modullal ellátott parancsfájlként tegye közzé.The best practice for DSC configurations is to publish the configuration as a script with an accompanying module that contains the docs, examples, and tests. A parancsfájl felsorolja a kapcsolódó modult a használatával RequiredModules = @(Name of the Module) .The script lists the accompanying module using RequiredModules = @(Name of the Module). Ez a módszer bármilyen parancsfájl használatával használható.This approach can be used with any script.

Az egyéb ajánlott eljárásokat követő önálló parancsfájlok valós értéket biztosítanak más felhasználóknak.Standalone scripts that follow the other best practices provide real value to other users. A Megjegyzés-alapú dokumentáció és a projekt webhelyére mutató hivatkozás használata kifejezetten ajánlott, ha parancsfájlokat tesz közzé a PowerShell-galéria.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

A projekt helye, ahol a közzétevő közvetlenül tud kommunikálni PowerShell-galéria csomagjainak felhasználóival.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery packages. A felhasználók inkább az ezt biztosító csomagokat részesítik előnyben, mivel így könnyebben kaphatják meg a csomag információit.Users prefer packages that provide this, as it allows them to get information about the package more easily. A PowerShell-galéria számos csomagja van kifejlesztve a GitHubban, másokat pedig egy dedikált webes jelenléttel rendelkező szervezetek biztosítanak.Many packages in the PowerShell Gallery are developed in GitHub, others are provided by organizations with a dedicated web presence. Ezek mindegyike egy projekt helyének tekinthető.Each of these can be considered a project site.

A hivatkozások hozzáadásához a következő módon kell megtenni a ProjectURI, beleértve a PSData szakaszt:Adding a link is done by including ProjectURI in the PSData section of the manifest as follows:

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

ProjectURI megadása esetén a PowerShell-galéria tartalmazni fog egy hivatkozást a projekt webhelyére a csomag lap bal oldalán.When a ProjectURI is provided, the PowerShell Gallery will include a link to the Project Site on the left side of the package page.

A csomag címkézése a kompatibilis PSEdition (s) és platformokkalTag your package with the compatible PSEdition(s) and platforms

A következő címkék segítségével bemutathatja azokat a felhasználókat, akik a csomagok jól fognak működni a környezetében:Use the following tags to demonstrate to users which packages will work well with their environment:

  • PSEdition_Desktop: a Windows PowerShell szolgáltatással kompatibilis csomagokPSEdition_Desktop: Packages that are compatible with Windows PowerShell
  • PSEdition_Core: a PowerShell Core-kompatibilis csomagokPSEdition_Core: Packages that are compatible with PowerShell Core
  • Windows: a Windows operációs rendszerrel kompatibilis csomagokWindows: Packages that are compatible with the Windows Operating System
  • Linux: Linux operációs rendszerekkel kompatibilis csomagokLinux: Packages that are compatible with Linux Operating Systems
  • MacOS: a Mac operációs rendszerrel kompatibilis csomagokMacOS: Packages that are compatible with the Mac Operating System

Ha címkézi a csomagot a kompatibilis platform (ok) val, a keresési eredmények bal oldali paneljén a katalógus keresési szűrőinek részét képezi majd.By tagging your package with the compatible platform(s) it will be included in the Gallery search filters on the left pane of the search results. Ha a csomagot a githubon futtatja, a csomag címkézése során igénybe veheti a PowerShell-Galéria kompatibilitási pajzsok  kompatibilitási pajzs-példáját is .If you host your package on GitHub, when you tag your package, you can also take advantage of our PowerShell Gallery compatibility shields compatibility shield example.

Tesztek belefoglalásaInclude tests

A nyílt forráskódot tartalmazó tesztek fontosak a felhasználók számára, mivel biztosítanak garanciát az érvényesítéséhez, és információt nyújt a kód működéséről.Including tests with open-source code is important to users, as it gives them assurance about what you validate, and provides information on how your code works. Azt is lehetővé teszi, hogy a felhasználók ne tudják megszüntetni az eredeti funkciót, ha a programkódot úgy módosítják, hogy illeszkedjenek a környezetéhez.It also allows users to ensure they don't break your original functionality if they modify your code to fit their environment.

Erősen ajánlott, hogy a teszteket a rendszer úgy írja be, hogy kihasználhassa a kifejezetten a PowerShell-hez készült, kimondottan PowerShell-tesztelési keretrendszert.It's strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. A Pest a GitHub, a PowerShell-Galériaés a Windows 10, a Windows Server 2016, a WMF 5,0 és a WMF 5,1 hajókon érhető el.Pester is available in GitHub, the PowerShell Gallery, and ships in Windows 10, Windows Server 2016, WMF 5.0 and WMF 5.1.

A githubon található pesting Project-webhely jó dokumentációt tartalmaz a Pest-tesztek megírásához, az első lépésektől kezdve az ajánlott eljárásig.The Pester project site in GitHub includes good documentation on writing Pester tests, from getting started to best practices.

A tesztelési lefedettség célját a magas színvonalú erőforrás-modul dokumentációjahívja meg, a 70%-os tesztelési kód lefedettsége ajánlott.The targets for test coverage are called out in the High Quality Resource Module documentation, with 70% unit test code coverage recommended.

A PowerShell-galéria közzétett összes csomagnak meg kell határoznia a licencfeltételeket, vagy a használati feltételekben foglalt licenchez kötve kell lennie . Egy másik licenc megadásának legjobb módszere, ha a PSData -ben lévő LicenseURI használatával a licencre mutató hivatkozást ad meg.All packages published to the PowerShell Gallery must specify the license terms, or be bound by the license included in the Terms of Use under Exhibit A . The best approach to specifying a different license is to provide a link to the license using the LicenseURI in PSData . További információ: a csomagok jegyzéke és a katalógus felhasználói felülete.For more information, see Packages manifest and Gallery UI.

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ásaSign your code

A kód aláírása biztosítja a legmagasabb szintű garanciát a csomag közzétételére, valamint arról, hogy a beszerzett kód másolata pontosan mit jelent a közzétevő számára.Code signing provides users with the highest level of assurance for who published the package, and that the copy of the code they acquire is exactly what the publisher released. A kódok aláírásával kapcsolatos további tudnivalókért tekintse meg a kód aláírásának bemutatásacímű témakört.To learn more about code signing generally, see Introduction to Code Signing. A PowerShell két elsődleges megközelítéssel támogatja a kódok aláírásának érvényesítését:PowerShell supports validation of code signing through two primary approaches:

  • Parancsfájl-fájlok aláírásaSigning script files
  • Modul aláírásaCatalog signing a module

A PowerShell-fájlok aláírása jól bevált megközelítés annak biztosítására, hogy a végrehajtott programkódot megbízható forrás hozta létre, és nem módosították.Signing PowerShell files is a well-established approach to ensuring that the code being executed was produced by a reliable source, and hasn't been modified. A PowerShell-parancsfájlok aláírásáról a Tudnivalók az aláírásról című cikkben olvashat bővebben.Details on how to sign PowerShell script files is covered in the About Signing article. Az áttekintésben egy aláírást adhat bármely olyan .PS1 fájlhoz, amelyet a PowerShell érvényesít, amikor a parancsfájl betöltődik.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. A PowerShell a végrehajtási házirend -parancsmagok használatával korlátozható az aláírt parancsfájlok használatának biztosítása érdekében.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts.

A katalógus-aláíró modulok a 5,1-es verzióban a PowerShellhez hozzáadott funkciók.Catalog signing modules is a feature added to PowerShell in version 5.1. A modul aláírása a katalógus-parancsmagok című cikkben található.How to sign a module is covered in the Catalog Cmdlets article. Az áttekintésben a katalógus-aláírást egy katalógusfájl létrehozásával végezheti el, amely a modul összes fájljának kivonatoló értékét tartalmazza, majd aláírja a fájlt.In overview, catalog signing is done by creating a catalog file, which contains a hash value for every file in the module, and then signing that file.

A PowerShellGet Publish-Module , Install-Module és a Update-Module parancsmagok az aláírás érvényességének ellenőrzésével ellenőrizhetik az aláírást, majd megerősítik, hogy az egyes csomagok kivonatoló értéke megegyezik a katalógusban szereplő értékekkel.The PowerShellGet Publish-Module, Install-Module, and Update-Module cmdlets will check the signature to ensure it's valid, then confirm that the hash value for each package matches what is in the catalog. Save-Module nem érvényesíti az aláírást.Save-Module doesn't validate a signature. Ha a modul egy korábbi verziója telepítve van a rendszeren, a Install-Module megerősíti, hogy az új verzióhoz tartozó aláíró szolgáltató megfelel a korábban telepített rendszernek.If a previous version of the module is installed on the system, Install-Module will confirm that the signing authority for the new version matches what was previously installed. Install-Module és Update-Module egy fájl aláírását fogja használni, .PSD1 Ha a csomag nincs aláírva.Install-Module and Update-Module will use the signature on a .PSD1 file if the package isn't catalog signed. A katalógus-aláírás együttműködik a-val, de nem váltja fel az aláíró parancsfájlokat.Catalog signing works with, but doesn't replace signing script files. A PowerShell nem ellenőrzi a katalógus-aláírásokat a modul betöltési idején.PowerShell doesn't validate catalog signatures at module load time.

SemVer-irányelvek követése a verziószámozáshozFollow SemVer guidelines for versioning

A SemVer egy nyilvános egyezmény, amely leírja, hogyan lehet egy verziót strukturálni és módosítani a változások egyszerű értelmezése érdekében.SemVer is a public convention that describes how to structure and change a version to allow easy interpretation of changes. A csomag verziójának szerepelnie kell a jegyzékfájl adatai között.The version for your package must be included in the manifest data.

  • A verziónak három, ponttal elválasztott numerikus blokknak kell lennie, mint a 0.1.1 vagy a 4.11.192 .The version should be structured as three numeric blocks separated by periods, as in 0.1.1 or 4.11.192.
  • A-től kezdődő verziók 0 azt jelzik, hogy a csomag még nem áll készen a gyártásra, és az első szám csak akkor kezdődhet, 0 Ha ez az egyetlen szám.Versions starting with 0 indicate that the package isn't yet production ready, and the first number should only begin with 0 if that's the only number used.
  • Az első szám ( 1.9.9999 to) változásai a 2.0.0 verziók közötti jelentős és megszakított változásokat jelzik.Changes in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions.
  • A második szám ( 1.1 to) változásai a 1.2 szolgáltatás szintű módosításokat jelezik, például új parancsmagok hozzáadása egy modulhoz.Changes to the second number (1.1 to 1.2) indicate feature-level changes, such as adding new cmdlets to a module.
  • A harmadik szám módosításai a nem törhető módosításokat jelzik, például az új paramétereket, a frissített mintákat vagy az új teszteket.Changes to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests.
  • A verziók listázásakor a PowerShell karakterláncként rendezi a verziókat, ezért a rendszer az- 1.01.0 nál nagyobb mértékben fogja kezelni őket 1.001.0 .When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 1.001.0.

A PowerShell a SemVer közzététele előtt lett létrehozva, így a SemVer a legtöbb, de nem az összes elemének támogatását biztosítja, pontosabban:PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:

  • A verziószámokban nem támogatja az előzetes kiadású karakterláncokat.It doesn't support prerelease strings in version numbers. Ez akkor hasznos, ha a kiadó egy verzió megadása után egy új főverzió előzetes kiadását szeretné kézbesíteni 1.0.0 .This is useful when a publisher wishes to deliver a preview release of a new major version after providing a version 1.0.0. Ez a PowerShell-galéria és a PowerShellGet -parancsmagok jövőbeli kiadásában lesz támogatott.This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • A PowerShell és a PowerShell-galéria lehetővé teszik az 1, 2 és 4 szegmensek verziószámát.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Számos korai modul nem követte az irányelveket, és a Microsoft termék-kiadásainak negyedik blokkjának (például) a létrehozása 5.1.14393.1066 .Many early modules did not follow the guidelines, and product releases from Microsoft include build information as a 4th block of numbers (for example 5.1.14393.1066). A verziószámozás szempontjából ezeket a különbségeket a rendszer figyelmen kívül hagyja.From a versioning standpoint, these differences are ignored.

Tesztelés helyi tárház használatávalTest using a local repository

A PowerShell-galéria nem a közzétételi folyamat tesztelésére szolgáló cél.The PowerShell Gallery isn't designed to be a target for testing the publishing process. A legjobb módszer, ha tesztelni szeretné a PowerShell-galéria közzétételének végpontok közötti folyamatát, és saját helyi tárházat kell beállítania és használnia.The best way to test out the end-to-end process of publishing to the PowerShell Gallery is to set up and use your own local repository. Ez többféleképpen is elvégezhető, többek között:This can be done in a few ways, including:

  • Hozzon létre egy helyi PowerShell-galéria példányt a GitHubon a PS Private Gallery-projekt használatával.Set up a local PowerShell Gallery instance, using the PS Private Gallery project in GitHub. Ez az előzetes verziójú projekt segítséget nyújt azon PowerShell-galéria példányának beállításához, amelyekkel szabályozható és használható a tesztek.This preview project will help you set up an instance of the PowerShell Gallery that you can control, and use for your tests.
  • Hozzon létre egy belső Nuget-tárházat.Set up an internal Nuget repository. Ehhez több munkát kell beállítania a beállításhoz, de az előnye, hogy több követelményt is érvényesít, például az API-kulcs használatának érvényességét, valamint azt, hogy a cél a közzétételkor megjelenjen-e a függőségek között.This will require more work to set up, but will have the advantage of validating a few more of the requirements, notably validating use of an API key, and whether or not dependencies are present in the target when you publish.
  • Hozzon létre egy fájlmegosztást a tesztelési tárházként .Set up a file share as the test repository . Ez egyszerűen beállítható, de mivel ez egy fájlmegosztás, a fentiekben ismertetett érvényesítések nem lesznek érvényben.This is easy to set up, but since it's a file share, the validations noted above will not take place. Ebben az esetben az egyik lehetséges előnye, hogy a fájlmegosztás nem vizsgálja meg a szükséges API-kulcsot, így ugyanazt a kulcsot használhatja, amelyet a PowerShell-galéria való közzétételhez használhat.One potential advantage in this case is that the file share doesn't check the required API key, so you can use the same key you would use to publish to the PowerShell Gallery.

Ezen megoldások bármelyikével Register-PSRepository megadhat egy új tárházat , amelyet a -Repository (z) paraméterében használhat Publish-Module .With any of these solutions, use Register-PSRepository to define a new repository , which you use in the -Repository parameter for Publish-Module.

Egy további pont a tesztek közzétételével kapcsolatban: a PowerShell-galéria közzétett bármely csomag nem törölhető az operatív csapat segítsége nélkül, aki megerősíti, hogy semmi sem függ a közzétenni kívánt csomagtól.One additional point about test publishing: any package you publish to the PowerShell Gallery can't be deleted without help from the operations team, who will confirm that nothing is dependent upon the package you wish to publish. Ezért nem támogatjuk a PowerShell-galéria tesztelési célként, és felvesszük Önnel a kapcsolatot a közzétevővel.For that reason, we don't support the PowerShell Gallery as a testing target, and will contact any publisher who does so.

Közzététel a PowerShellGet használatávalUse PowerShellGet to publish

Erősen ajánlott, hogy a közzétevők a Publish-Module és a Publish-Script parancsmagot használják a PowerShell-Galéria használatakor.It's strongly recommended that publishers use the Publish-Module and Publish-Script cmdlets when working with the PowerShell Gallery. A PowerShellGet azért jött létre, hogy elkerülje a PowerShell-Galéria telepítésének és közzétételének fontos részleteit.PowerShellGet was created to help you avoid remembering important details about installing from and publishing to the PowerShell Gallery. Alkalmanként a kiadók úgy döntöttek, hogy kihagyják a PowerShellGet , és a NuGet -ügyfelet, vagy a PackageManagement -parancsmagokat használják a helyett Publish-Module .On occasion, publishers have chosen to skip PowerShellGet and use the NuGet client, or PackageManagement cmdlets, instead of Publish-Module. A könnyen kihagyható részletek számos különböző támogatási kérést eredményeznek.There are a number of details that are easily missed, which results in a variety of support requests.

Ha nem tudja használni a vagy a-t Publish-Module Publish-Script , kérjük, tudassa velünk.If there's a reason that you can't use Publish-Module or Publish-Script, please let us know. Fájl a PowerShellGet GitHub-tárházban, és adja meg a NuGet vagy a PackageManagement kiválasztását kiváltó adatokat.File an issue in the PowerShellGet GitHub repo, and provide the details that cause you to choose NuGet or PackageManagement .

A PowerShell-galéria közzétett csomagok legsikeresebb megközelítése a következő:The most successful approach we have found for packages published to the PowerShell Gallery is this:

  • A kezdeti fejlesztést egy nyílt forráskódú projektbeli helyen végezze el.Do initial development in an open-source project site. A PowerShell-csapat a GitHubot használja.The PowerShell Team uses GitHub.
  • Visszajelzéseket használhat a felülvizsgálók és a PowerShell script Analyzer használatával, hogy a kód stabil állapotba kerüljön.Use feedback from reviewers and Powershell Script Analyzer to get the code to stable state.
  • Vegyen fel dokumentációt, hogy mások is tudják, hogyan használják a munkáját.Include documentation, so others know how to use your work.
  • Próbálja ki a közzétételi műveletet egy helyi tárház használatával.Test out the publishing action using a local repository.
  • Tegyen közzé egy stabil vagy alfa-verziót a PowerShell-galériaon, és ügyeljen rá, hogy tartalmazza a dokumentációt és a projekt webhelyére mutató hivatkozást.Publish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site.
  • Gyűjtsön visszajelzéseket, és ismételje meg a kódot a projekt webhelyén, majd tegye közzé a stabil frissítéseket a PowerShell-galéria.Gather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery.
  • Példákat és Pest-teszteket adhat hozzá a projekthez és a modulhoz.Add examples and Pester tests in your project and your module.
  • Döntse el, hogy szeretné-e aláírni a csomagot.Decide if you want to code sign your package.
  • Ha úgy érzi, hogy a projekt készen áll az éles környezetben való használatra, tegyen közzé egy 1.0.0 verziót a PowerShell-Galéria.When you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery.
  • Folytassa a visszajelzések összegyűjtését, és ismételje meg a kódot a felhasználói bevitel alapján.Continue to gather feedback and iterate on your code based on user input.