Delen via

Publicatierichtlijnen en aanbevolen procedures voor PowerShellGallery

  • Artikel

In dit artikel worden aanbevolen stappen beschreven die door Microsoft-teams worden gebruikt om ervoor te zorgen dat de pakketten die zijn gepubliceerd in de PowerShell Gallery algemeen worden gebruikt en veel waarde bieden aan gebruikers, op basis van hoe de PowerShell Gallery manifestgegevens verwerkt en feedback van grote aantallen PowerShell Gallery-gebruikers. Pakketten die volgens deze richtlijnen worden gepubliceerd, zijn waarschijnlijker geïnstalleerd, vertrouwd en trekken meer gebruikers aan.

Hieronder vindt u richtlijnen voor het maken van een goed PowerShell Gallery-pakket, 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 publicerenvoor 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 volgorde van nominale prioriteit. Pakketten die aan deze richtlijnen voldoen, zijn veel waarschijnlijker gedownload en goedgekeurd door anderen.

  • 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 SemVer richtlijnen voor versiebeheer
  • Algemene tags gebruiken, zoals beschreven in Algemene PowerShell Gallery-tags
  • Publicatie testen met behulp van een lokale opslagplaats
  • PowerShellGet gebruiken om te publiceren

Elk van deze wordt kort behandeld in de onderstaande secties.

PSScriptAnalyzer gebruiken

PSScriptAnalyzer- is een gratis hulpprogramma voor statische codeanalyse dat werkt met PowerShell-code. PSScriptAnalyzer- identificeert de meest voorkomende problemen die worden gezien 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 opgelost), waarschuwing (moet worden gecontroleerd en moet worden aangepakt) en informatie (de moeite waard om te controleren op aanbevolen procedures). Alle pakketten die in de 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 Invoke-ScriptAnalyzer uit te voeren met -Recurse en -Severity Waarschuwing.

Controleer de resultaten en zorg ervoor dat:

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

Gebruikers die pakketten downloaden uit de PowerShell Gallery, worden sterk aangeraden om 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 gemeld door PSScriptAnalyzer. Als uw pakket een overtuigende reden heeft om code te bewaren die als een fout wordt gemarkeerd, voegt u die informatie toe aan uw documentatie om te voorkomen dat u dezelfde vraag vaak moet 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 handigst om op te nemen in pakketten die zijn gepubliceerd naar de PowerShell Gallery. Gebruikers over het algemeen omzeilen pakketten zonder documentatie, omdat het alternatief is om de code te lezen om te begrijpen wat het pakket is en hoe ze het moeten gebruiken. Er zijn verschillende artikelen beschikbaar over het bieden van documentatie met PowerShell-pakketten, waaronder:

  • Richtlijnen voor het bieden van hulp bevinden zich in Help-voor cmdlets schrijven.
  • Help bij het maken van cmdlets, wat de beste methode is voor een PowerShell-script, -functie of -cmdlet. Begin met Help voor cmdlets schrijvenvoor meer informatie over het maken van help-informatie over het maken van cmdlets. Zie Help op basis van opmerkingenom hulp toe te voegen in een script.
  • 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 intensief gebruikte indeling is. De best practice is om Markdown-met gitHub-smaak te gebruiken.

Voorbeelden laten gebruikers zien hoe het pakket moet worden gebruikt. Veel ontwikkelaars zullen zeggen dat ze voorbeelden bekijken vóór documentatie om te begrijpen hoe ze iets moeten gebruiken. De beste typen voorbeelden geven basisgebruik weer, plus een gesimuleerd realistisch gebruiksvoorbeeld en de code is goed gecommentarieerd. Voorbeelden voor modules die naar de 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 map Examples\RegistryResource. Er zijn vier voorbeeldgebruiksvoorbeelden met een korte beschrijving bovenaan elk bestand waarin wordt beschreven wat er wordt 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 in de globale omgeving geladen voordat u de module importeert, tenzij ze 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 ModuleVersiongebruikt, wordt de nieuwste versie geladen die beschikbaar is met minimaal de opgegeven versie. Wanneer u het veld RequiredVersion niet gebruikt, moet u een specifieke versie opgeven die belangrijk is om versie-updates voor de vereiste module te controleren. Het is vooral belangrijk om rekening te houden met eventuele belangrijke wijzigingen 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 op te reageren, omdat ze voldoende 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 eigenaar van een pakket 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 gemeld. Het enige nadeel van deze methode is dat alleen de gebruiker en eigenaar de communicatie ooit zullen zien, dus de eigenaar moet mogelijk vaak dezelfde vraag beantwoorden.

Eigenaren die constructief 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 identificeer of een update een probleem oplost.

Als er ongepast gedrag wordt waargenomen vanuit een van deze communicatiekanalen, gebruikt u de functie Misbruik van rapporten van de PowerShell Gallery om contact op te nemen met de beheerders van de galerie.

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 één bestand 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 voor cmdlets, documentatie, voorbeelden en tests. Het grootste nadeel is dat een script in een module moet worden weergegeven en als functie moet worden gebruikt. Zie Een Windows PowerShell-module schrijvenvoor 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 hierdoor gemakkelijker informatie over het pakket kunnen krijgen. Veel pakketten in de PowerShell Gallery zijn 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.

U voegt als volgt een koppeling toe door ProjectURI op te halen in de sectie PSData van het manifest:

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

Wanneer er een ProjectURI is opgegeven, bevat de PowerShell Gallery een koppeling naar de Project-site 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 platformen, wordt het opgenomen in de zoekfilters in de galerie in het linkerdeelvenster van de zoekresultaten. Als u uw pakket host op GitHub en u uw pakket tagt, kunt u ook profiteren van onze PowerShell Gallery-compatibiliteitsschildencompatibiliteitsschild.

Tests opnemen

Het opnemen van tests met opensource-code is belangrijk voor gebruikers, omdat ze er zeker van zijn wat u valideert en informatie biedt over hoe uw code werkt. Gebruikers kunnen er ook voor zorgen dat ze de oorspronkelijke functionaliteit niet breken als ze uw code aanpassen aan hun omgeving.

Het wordt sterk aanbevolen om tests te schrijven om te profiteren van het Pester-testframework, dat speciaal is ontworpen voor PowerShell. Pester is beschikbaar in GitHub, de PowerShell Galleryen 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 de testdekking worden aangeroepen in de documentatie van de resourcemodule van hoge kwaliteit, waarbij 70%-eenheidscodedekking wordt aanbevolen.

Alle pakketten die naar de PowerShell Gallery zijn gepubliceerd, moeten de licentievoorwaarden opgeven of afhankelijk zijn van de licentie die is opgenomen in de Gebruiksvoorwaarden onder Exhibit A. De beste manier om een andere licentie op te geven, is door een koppeling naar de licentie op te geven met behulp van de LicenseURI- in PSData-. Zie Packages manifest en Gallery UIvoor 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

Ondertekening van code biedt gebruikers het hoogste niveau van zekerheid 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 ondertekening van programmacodevoor meer informatie over ondertekening van programmacode. PowerShell ondersteunt validatie van ondertekening van code via twee primaire benaderingen:

  • Scriptbestanden ondertekenen
  • Catalogus die een module ondertekent

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 het ondertekenen van. 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 het Uitvoeringsbeleid cmdlets 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 Catalogus-cmdlets artikel. In het overzicht wordt catalogusondertekening uitgevoerd door een catalogusbestand te maken, dat een hash-waarde bevat voor elk bestand in de module en dat bestand vervolgens ondertekent.

De PowerShellGet-Publish-Module, Install-Moduleen Update-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, controleert Install-Module of de handtekeninginstantie voor de nieuwe versie overeenkomt met wat eerder is geïnstalleerd. Install-Module en Update-Module gebruiken de handtekening op een .PSD1 bestand als het pakket niet is ondertekend. Catalogusondertekening werkt met, maar vervangt geen ondertekeningsscriptbestanden. PowerShell valideert geen catalogushandtekeningen tijdens de laadtijd van de module.

Volg 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 nummer alleen moet beginnen met 0 als dat het enige gebruikte nummer is.
  • Wijzigingen in het eerste getal (1.9.9999 in 2.0.0) geven 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 voorbeelden of nieuwe tests.
  • Wanneer u versies opgeeft, worden de versies in PowerShell als tekenreeksen gesorteerd, zodat 1.01.0 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 na het verstrekken van een versie 1.0.0. Dit wordt ondersteund in een toekomstige release van de PowerShell Gallery en PowerShellGet cmdlets.
  • PowerShell en de PowerShell Gallery staan versietekenreeksen met 1, 2 en 4 segmenten toe. Veel vroege modules voldoen niet aan de richtlijnen 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 PS Private Gallery-project in GitHub. Dit voorbeeldproject helpt u bij het instellen van een exemplaar van de PowerShell Gallery die u kunt beheren en gebruiken voor uw tests.
  • Een interne Nuget-opslagplaats instellen. Dit vereist meer werk om in te stellen, maar heeft het voordeel dat u nog enkele van de vereisten valideert, met name het valideren van het gebruik van een API-sleutel en of er afhankelijkheden aanwezig zijn in het doel wanneer u publiceert.
  • Een bestandsshare instellen als de test-opslagplaats. Dit is eenvoudig in te stellen, maar omdat het een bestandsshare is, vinden de hierboven genoteerde 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 u Register-PSRepository gebruiken om een nieuwe opslagplaats te definiëren, die u in de parameter -Repository voor Publish-Modulegebruikt.

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 wordt de PowerShell Gallery niet ondersteund als testdoel en wordt contact opgenomen met een uitgever die dit doet.

PowerShellGet gebruiken om te publiceren

Het wordt sterk aanbevolen dat uitgevers de cmdlets Publish-Module en Publish-Script 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 ervoor 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 een verscheidenheid aan ondersteuningsaanvragen.

Als er een reden is dat u Publish-Module of Publish-Scriptniet kunt gebruiken, 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 aanpak die we hebben gevonden voor pakketten die zijn gepubliceerd naar de PowerShell Gallery, is dit:

  • Voer initiële 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 ze uw werk kunnen gebruiken.
  • Test de publicatieactie met behulp van een lokale opslagplaats.
  • Publiceer een stabiele of Alpha-release in 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 klaar 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.