Richtlijnen en best practices voor PowerShellGallery-publicatie

In dit artikel worden aanbevolen stappen beschreven die door Microsoft-teams worden gebruikt om ervoor te zorgen dat de pakketten die naar het PowerShell Gallery worden gepubliceerd, algemeen worden gebruikt en een hoge waarde bieden aan gebruikers, op basis van de manier waarop de PowerShell Gallery manifestgegevens verwerkt en feedback van grote aantallen PowerShell Gallery gebruikers. Pakketten die worden gepubliceerd volgens deze richtlijnen, zullen waarschijnlijk meer worden geïnstalleerd, vertrouwd en meer gebruikers aantrekken.

Hieronder vindt u richtlijnen voor wat een goed PowerShell Gallery pakket maakt, welke optionele manifestinstellingen het belangrijkst zijn, het verbeteren van uw code met feedback van initiële revisoren en Powershell Script Analyzer, versiebeheer van uw module, documentatie, tests en voorbeelden voor het gebruik van wat u hebt gedeeld. Veel van deze documentatie volgt de richtlijnen voor het publiceren van DSC-resourcemodules van hoge kwaliteit.

Zie Een pakket maken en publiceren voor de mechanica van het publiceren van een pakket naar de PowerShell Gallery.

Feedback over deze richtlijnen wordt verwelkomd. Als u feedback hebt, kunt u problemen openen in onze GitHub-documentatieopslagplaats.

Aanbevolen procedures voor het publiceren van pakketten

De volgende aanbevolen procedures zijn wat de gebruikers van PowerShell Gallery items zeggen belangrijk en worden vermeld in de volgorde van nominale prioriteit. Pakketten die aan deze richtlijnen voldoen, zijn veel waarschijnlijker gedownload en door anderen aangenomen.

  • PSScriptAnalyzer gebruiken
  • Documentatie en voorbeelden opnemen
  • Reageren op feedback
  • Modules opgeven in plaats van scripts
  • Koppelingen naar een projectsite opgeven
  • Tag uw pakket met de compatibele PSEdition(s) en platforms
  • Tests opnemen met uw modules
  • Licentievoorwaarden opnemen en/of koppelen
  • Uw code ondertekenen
  • Volg de SemVer-richtlijnen voor versiebeheer
  • Algemene tags gebruiken, zoals beschreven in Common PowerShell Gallery tags
  • Publicatie testen met behulp van een lokale opslagplaats
  • PowerShellGet gebruiken om te publiceren

Elk van deze wordt kort besproken in de onderstaande secties.

PSScriptAnalyzer gebruiken

PSScriptAnalyzer is een gratis hulpprogramma voor statische codeanalyse dat werkt in PowerShell-code. PSScriptAnalyzer identificeert de meest voorkomende problemen in PowerShell-code, en vaak een aanbeveling voor het oplossen van het probleem. Het hulpprogramma is eenvoudig te gebruiken en categoriseert de problemen als fouten (ernstig, moet worden aangepakt), waarschuwing (moet worden gecontroleerd en moet worden aangepakt) en informatie (de moeite waard om te controleren op aanbevolen procedures). Alle pakketten die naar het PowerShell Gallery worden gepubliceerd, worden gescand met PSScriptAnalyzer en eventuele fouten worden teruggegeven aan de eigenaar en moeten worden opgelost.

De aanbevolen procedure is om te worden uitgevoerd Invoke-ScriptAnalyzer met -Recurse en -Severity waarschuwing.

Controleer de resultaten en zorg ervoor dat:

  • Alle fouten worden gecorrigeerd of opgelost in uw documentatie.
  • Alle waarschuwingen worden beoordeeld en waar van toepassing behandeld.

Gebruikers die pakketten downloaden van de PowerShell Gallery worden sterk aangeraden PSScriptAnalyzer uit te voeren en alle fouten en waarschuwingen te evalueren. Gebruikers zullen zeer waarschijnlijk contact opnemen met pakketeigenaren als ze zien dat er een fout is gerapporteerd door PSScriptAnalyzer. Als uw pakket een overtuigende reden heeft om code te bewaren die als fout wordt gemarkeerd, voegt u die informatie toe aan uw documentatie om te voorkomen dat u dezelfde vraag vaak hoeft te beantwoorden.

Documentatie en voorbeelden opnemen

Documentatie en voorbeelden zijn de beste manier om ervoor te zorgen dat gebruikers kunnen profiteren van gedeelde code.

Documentatie is het handigste om op te nemen in pakketten die zijn gepubliceerd naar de PowerShell Gallery. Gebruikers omzeilen in het algemeen pakketten zonder documentatie, omdat het alternatief is om de code te lezen om te begrijpen wat het pakket is en hoe het te gebruiken. Er zijn verschillende artikelen beschikbaar over het leveren van documentatie met PowerShell-pakketten, waaronder:

  • Richtlijnen voor het verstrekken van hulp staan in Help bij het schrijven van cmdlets.
  • Help bij het maken van cmdlets, wat de beste aanpak is voor elk PowerShell-script, functie of cmdlet. Voor meer informatie over het maken van cmdlet-help, begint u met help bij het schrijven van cmdlets. Zie Help op basis van opmerkingen als u hulp in een script wilt toevoegen.
  • Veel modules bevatten ook documentatie in tekstindeling, zoals MarkDown-bestanden. Dit kan met name handig zijn wanneer er een projectsite in GitHub is, waarbij Markdown een sterk gebruikte indeling is. De aanbevolen procedure is om Markdown met gitHub-smaak te gebruiken.

Voorbeelden laten zien hoe het pakket moet worden gebruikt. Veel ontwikkelaars zullen zeggen dat ze voorbeelden bekijken voordat ze documentatie raadplegen om te begrijpen hoe ze iets kunnen gebruiken. De beste typen voorbeelden tonen basisgebruik, plus een gesimuleerde realistische use-case en de code is goed becommentarieerd. Voorbeelden voor modules die naar het PowerShell Gallery zijn gepubliceerd, moeten zich in een map Voorbeelden bevinden onder de hoofdmap van de module.

Een goed patroon voor voorbeelden vindt u in de PSDscResource-module onder de Examples\RegistryResource map. Er zijn vier voorbeeldgebruiksvoorbeelden met een korte beschrijving bovenaan elk bestand dat documenten bevat die worden gedemonstreerd.

Afhankelijkheden beheren

Het is belangrijk om modules op te geven waaraan uw module afhankelijk is in het modulemanifest. Hierdoor hoeft de eindgebruiker zich geen zorgen te maken over het installeren van de juiste versies van modules waarvan u afhankelijk bent. Als u afhankelijke modules wilt opgeven, moet u het vereiste moduleveld in het modulemanifest gebruiken. Hiermee worden alle vermelde modules geladen in de globale omgeving voordat u uw module importeert, tenzij deze al zijn geladen. Sommige modules kunnen bijvoorbeeld al door een andere module worden geladen. Het is ook mogelijk om een specifieke versie op te geven die moet worden geladen met behulp van het veld RequiredVersion in plaats van het veld ModuleVersion . Wanneer u ModuleVersion gebruikt, wordt de nieuwste versie geladen die beschikbaar is met minimaal de opgegeven versie. Wanneer u het veld RequiredVersion niet gebruikt, is het belangrijk om een specifieke versie op te geven, is het belangrijk om versie-updates voor de vereiste module te controleren. Het is vooral belangrijk om op de hoogte te zijn van wijzigingen die fouten veroorzaken die van invloed kunnen zijn op de gebruikerservaring met uw 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"})

Reageren op feedback

Pakketeigenaren die goed reageren op feedback, worden zeer gewaardeerd door de community. Gebruikers die constructieve feedback geven, zijn belangrijk om te reageren, omdat ze geïnteresseerd zijn in het pakket om te proberen het te verbeteren.

Er is één feedbackmethode beschikbaar in de PowerShell Gallery:

  • Eigenaar van contactpersoon: hiermee kan een gebruiker een e-mailbericht verzenden naar de eigenaar van het pakket. Als pakketeigenaar is het belangrijk om het e-mailadres te controleren dat wordt gebruikt met de PowerShell Gallery pakketten en om te reageren op problemen die worden veroorzaakt. Het enige nadeel van deze methode is dat alleen de gebruiker en eigenaar de communicatie ooit zullen zien, zodat de eigenaar vaak dezelfde vraag moet beantwoorden.

Eigenaren die op constructieve wijze reageren op feedback, worden gewaardeerd door de community. Gebruik de mogelijkheid in het rapport om meer informatie aan te vragen. Geef indien nodig een tijdelijke oplossing op of bepaal of een update een probleem oplost.

Als er ongepast gedrag is waargenomen vanuit een van deze communicatiekanalen, gebruikt u de functie Rapportmisbruik van de PowerShell Gallery om contact op te nemen met de galeriebeheerders.

Modules Versus Scripts

Het delen van een script met andere gebruikers is geweldig en biedt anderen voorbeelden van het oplossen van problemen die ze mogelijk hebben. Het probleem is dat scripts in de PowerShell Gallery afzonderlijke bestanden zijn zonder afzonderlijke documentatie, voorbeelden en tests.

PowerShell-modules hebben een mapstructuur waarmee meerdere mappen en bestanden kunnen worden opgenomen in het pakket. De modulestructuur maakt het mogelijk om de andere pakketten die we vermelden als best practices op te geven: help bij cmdlets, documentatie, voorbeelden en tests. Het grootste nadeel is dat een script in een module beschikbaar moet worden gesteld en als functie moet worden gebruikt. Zie Een Windows PowerShell module schrijven voor meer informatie over het maken van een module.

Er zijn situaties waarin een script een betere ervaring biedt voor de gebruiker, met name met DSC-configuraties. De aanbevolen procedure voor DSC-configuraties is het publiceren van de configuratie als een script met een bijbehorende module die de documenten, voorbeelden en tests bevat. Het script bevat de bijbehorende module met behulp van RequiredModules = @(Name of the Module). Deze benadering kan worden gebruikt met elk script.

Zelfstandige scripts die de andere aanbevolen procedures volgen, bieden echte waarde voor andere gebruikers. Het verstrekken van documentatie op basis van opmerkingen en een koppeling naar een projectsite wordt ten zeerste aanbevolen bij het publiceren van een script naar de PowerShell Gallery.

Een projectsite is waar een uitgever rechtstreeks kan communiceren met de gebruikers van hun PowerShell Gallery pakketten. Gebruikers geven de voorkeur aan pakketten die dit bieden, omdat ze gemakkelijker informatie over het pakket kunnen krijgen. Veel pakketten in de PowerShell Gallery worden ontwikkeld in GitHub. Andere pakketten worden geleverd door organisaties met een speciale aanwezigheid op het web. Elk van deze kan worden beschouwd als een projectsite.

Als volgt wordt een koppeling toegevoegd door ProjectURI op te geven in de sectie PSData van het manifest:

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

Wanneer een ProjectURI wordt opgegeven, bevat de PowerShell Gallery een koppeling naar de projectsite aan de linkerkant van de pakketpagina.

Tag uw pakket met de compatibele PSEdition(s) en platforms

Gebruik de volgende tags om gebruikers te laten zien welke pakketten goed werken met hun omgeving:

  • PSEdition_Desktop: Pakketten die compatibel zijn met Windows PowerShell
  • PSEdition_Core: Pakketten die compatibel zijn met PowerShell 6 en hoger
  • Windows: Pakketten die compatibel zijn met het Windows-besturingssysteem
  • Linux: Pakketten die compatibel zijn met Linux-besturingssystemen
  • MacOS: Pakketten die compatibel zijn met het Mac-besturingssysteem

Door uw pakket te taggen met de compatibele platform(s) wordt het opgenomen in de zoekfilters galerie in het linkerdeelvenster van de zoekresultaten. Als u uw pakket host op GitHub, kunt u, wanneer u uw pakket tagt, ook gebruikmaken van ons voorbeeld van het PowerShell Gallery compatibiliteitsschild voor compatibiliteitsschilden.

Tests opnemen

Het opnemen van tests met opensource-code is belangrijk voor gebruikers, omdat het hen zekerheid geeft over wat u valideert en informatie biedt over de werking van uw code. Gebruikers kunnen er ook voor zorgen dat ze de oorspronkelijke functionaliteit niet verbreken als ze uw code aanpassen aan hun omgeving.

Het wordt sterk aanbevolen dat tests worden geschreven om te profiteren van het Pester-testframework, dat speciaal is ontworpen voor PowerShell. Pester is beschikbaar in GitHub, de PowerShell Gallery en wordt geleverd in Windows 10, Windows Server 2016, WMF 5.0 en WMF 5.1.

De Pester-projectsite in GitHub bevat goede documentatie over het schrijven van Pester-tests, van aan de slag met best practices.

De doelen voor testdekking worden aangeroepen in de documentatie voor resourcemodules van hoge kwaliteit, met aanbevolen codedekking van 70% eenheid.

Alle pakketten die zijn gepubliceerd naar de PowerShell Gallery moeten de licentievoorwaarden opgeven of afhankelijk zijn van de licentie die is opgenomen in de Gebruiksvoorwaarden onder Tentoonstelling A. De beste manier om een andere licentie op te geven, is door een koppeling naar de licentie te bieden met behulp van de LicenseURI in PSData. Zie Het manifest van pakketten en de gebruikersinterface van de galerie voor meer informatie.

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'

Uw code ondertekenen

Codeondertekening biedt gebruikers het hoogste zekerheidsniveau voor wie het pakket heeft gepubliceerd en dat de kopie van de code die ze verkrijgen precies is wat de uitgever heeft uitgebracht. Zie Inleiding tot codeondertekening voor meer informatie over het ondertekenen van code. PowerShell ondersteunt validatie van ondertekening van code via twee primaire benaderingen:

  • Scriptbestanden ondertekenen
  • Catalogusondertekening van een module

Het ondertekenen van PowerShell-bestanden is een gevestigde benadering om ervoor te zorgen dat de code die wordt uitgevoerd, is geproduceerd door een betrouwbare bron en niet is gewijzigd. Meer informatie over het ondertekenen van PowerShell-scriptbestanden vindt u in het artikel Over ondertekening . In het overzicht kan een handtekening worden toegevoegd aan elk .PS1 bestand dat Door PowerShell wordt gevalideerd wanneer het script wordt geladen. PowerShell kan worden beperkt met behulp van de cmdlets voor uitvoeringsbeleid om ervoor te zorgen dat ondertekende scripts worden gebruikt.

Catalogusondertekeningsmodules is een functie die is toegevoegd aan PowerShell in versie 5.1. Het ondertekenen van een module wordt behandeld in het artikel Catalogus-cmdlets . In het overzicht wordt catalogusondertekening uitgevoerd door een catalogusbestand te maken, dat een hashwaarde bevat voor elk bestand in de module en dat bestand vervolgens te ondertekenen.

De PowerShellGetPublish-Module en Install-ModuleUpdate-Module cmdlets controleren de handtekening om te controleren of deze geldig is. Controleer vervolgens of de hash-waarde voor elk pakket overeenkomt met wat er in de catalogus staat. Save-Module valideert geen handtekening. Als een eerdere versie van de module op het systeem is geïnstalleerd, Install-Module controleert u of de ondertekeningsinstantie voor de nieuwe versie overeenkomt met wat eerder is geïnstalleerd. Install-Module en Update-Module gebruikt de handtekening op een .PSD1 bestand als het pakket niet is ondertekend. Catalogusondertekening werkt met, maar vervangt geen scriptbestanden voor ondertekening. In PowerShell worden catalogushandtekeningen tijdens de laadtijd van de module niet gevalideerd.

Volg de SemVer-richtlijnen voor versiebeheer

SemVer is een openbare conventie waarin wordt beschreven hoe u een versie structureert en wijzigt om eenvoudige interpretatie van wijzigingen mogelijk te maken. De versie voor uw pakket moet worden opgenomen in de manifestgegevens.

  • De versie moet zijn gestructureerd als drie numerieke blokken gescheiden door punten, zoals in 0.1.1 of 4.11.192.
  • Versies die beginnen met 0 geven aan dat het pakket nog niet gereed is voor productie en dat het eerste getal alleen moet beginnen 0 als dat het enige gebruikte nummer is.
  • Wijzigingen in het eerste getal (1.9.9999 in) 2.0.0geven belangrijke en belangrijke wijzigingen tussen de versies aan.
  • Wijzigingen in het tweede getal (1.1 in 1.2) geven wijzigingen op functieniveau aan, zoals het toevoegen van nieuwe cmdlets aan een module.
  • Wijzigingen in het derde getal geven niet-belangrijke wijzigingen aan, zoals nieuwe parameters, bijgewerkte steekproeven of nieuwe tests.
  • Wanneer u versies opgeeft, worden de versies als tekenreeksen gesorteerd in PowerShell, zodat 1.01.0 deze worden behandeld als groter dan 1.001.0.

PowerShell is gemaakt voordat SemVer werd gepubliceerd, dus biedt het ondersteuning voor de meeste maar niet alle elementen van SemVer, met name:

  • Het biedt geen ondersteuning voor prereleasetekenreeksen in versienummers. Dit is handig wanneer een uitgever een preview-versie van een nieuwe primaire versie wil leveren nadat een versie 1.0.0is opgegeven. Dit wordt ondersteund in een toekomstige release van de cmdlets PowerShell Gallery en PowerShellGet.
  • PowerShell en de PowerShell Gallery versietekenreeksen met 1, 2 en 4 segmenten toestaan. Veel vroege modules hebben de richtlijnen niet gevolgd en productreleases van Microsoft bevatten build-informatie als een vierde blok getallen (bijvoorbeeld 5.1.14393.1066). Vanuit het oogpunt van versiebeheer worden deze verschillen genegeerd.

Testen met behulp van een lokale opslagplaats

De PowerShell Gallery is niet ontworpen als doel voor het testen van het publicatieproces. De beste manier om het end-to-end-proces van publiceren naar de PowerShell Gallery te testen, is door uw eigen lokale opslagplaats in te stellen en te gebruiken. Dit kan op een aantal manieren worden gedaan, waaronder:

  • Stel een lokaal PowerShell Gallery-exemplaar in met behulp van het project PS Private Gallery in GitHub. Dit preview-project helpt u bij het instellen van een exemplaar van de PowerShell Gallery die u kunt beheren en gebruiken voor uw tests.
  • Stel een interne Nuget-opslagplaats in. Dit vereist meer werk om in te stellen, maar heeft het voordeel dat u nog enkele vereisten valideert, met name het valideren van het gebruik van een API-sleutel en of er al dan niet afhankelijkheden aanwezig zijn in het doel wanneer u publiceert.
  • Stel een bestandsshare in als de testopslagplaats. Dit is eenvoudig in te stellen, maar omdat het een bestandsshare is, vinden de hierboven vermelde validaties niet plaats. Een potentieel voordeel in dit geval is dat de bestandsshare de vereiste API-sleutel niet controleert, zodat u dezelfde sleutel kunt gebruiken die u zou gebruiken om naar de PowerShell Gallery te publiceren.

Met een van deze oplossingen kunt Register-PSRepository u een nieuwe opslagplaats definiëren, die u gebruikt in de -Repository parameter voor Publish-Module.

Nog een extra punt over het publiceren van tests: elk pakket dat u naar de PowerShell Gallery publiceert, kan niet worden verwijderd zonder hulp van het operations-team, die zal bevestigen dat niets afhankelijk is van het pakket dat u wilt publiceren. Daarom ondersteunen we de PowerShell Gallery niet als testdoel en zullen we contact opnemen met elke uitgever die dit doet.

PowerShellGet gebruiken om te publiceren

Het wordt sterk aanbevolen dat uitgevers de Publish-Module en Publish-Script cmdlets gebruiken bij het werken met de PowerShell Gallery. PowerShellGet is gemaakt om te voorkomen dat u belangrijke informatie over het installeren van en publiceren naar de PowerShell Gallery onthoudt. Uitgevers hebben er soms voor gekozen Om PowerShellGet over te slaan en de NuGet-client of PackageManagement-cmdlets te gebruiken, in plaats van Publish-Module. Er zijn een aantal details die gemakkelijk worden gemist, wat resulteert in diverse ondersteuningsaanvragen.

Als er een reden is dat u deze niet kunt gebruiken Publish-Module of Publish-Script, laat het ons dan weten. Dien een probleem in in de GitHub-opslagplaats van PowerShellGet en geef de details op die ervoor zorgen dat u NuGet of PackageManagement kiest.

De meest succesvolle benadering die we hebben gevonden voor pakketten die naar de PowerShell Gallery zijn gepubliceerd, is dit:

  • Voer de eerste ontwikkeling uit op een opensource-projectsite. Het PowerShell-team maakt gebruik van GitHub.
  • Gebruik feedback van revisoren en PowerShell Script Analyzer om de code stabiel te krijgen.
  • Neem documentatie op, zodat anderen weten hoe u uw werk kunt gebruiken.
  • Test de publicatieactie met behulp van een lokale opslagplaats.
  • Publiceer een stabiele of Alpha-release naar de PowerShell Gallery, zorg ervoor dat u de documentatie en koppeling naar uw projectsite opneemt.
  • Verzamel feedback en herhaal de code op uw projectsite en publiceer vervolgens stabiele updates naar de PowerShell Gallery.
  • Voeg voorbeelden en Pester-tests toe in uw project en uw module.
  • Bepaal of u uw pakket wilt ondertekenen.
  • Wanneer u denkt dat het project gereed is voor gebruik in een productieomgeving, publiceert u een 1.0.0 versie naar de PowerShell Gallery.
  • Blijf feedback verzamelen en uw code herhalen op basis van gebruikersinvoer.