Publicatierichtlijnen en aanbevolen procedures voor PowerShellGallery

  • Artikel

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

Hieronder vindt u richtlijnen voor wat een goed PowerShell Gallery pakket is, welke optionele manifestinstellingen het belangrijkst zijn, het verbeteren van uw code met feedback van de eerste revisoren en Powershell Script Analyzer, het 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 mechanismen voor het publiceren van een pakket naar de PowerShell Gallery.

Feedback over deze richtlijnen is welkom. 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 belangrijk vinden en worden weergegeven in de volgorde van de nominale prioriteit. Pakketten die aan deze richtlijnen voldoen, zijn veel waarschijnlijker om door anderen te worden gedownload en geaccepteerd.

  • PSScriptAnalyzer gebruiken
  • Documentatie en voorbeelden opnemen
  • Reageren op feedback
  • Modules opgeven in plaats van scripts
  • Koppelingen naar een projectsite opgeven
  • Label uw pakket met de compatibele PSEdition(s) en platforms
  • Tests opnemen in uw modules
  • Licentievoorwaarden opnemen en/of koppelen
  • Uw code ondertekenen
  • Volg de 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 besproken in de onderstaande secties.

PSScriptAnalyzer gebruiken

PSScriptAnalyzer is een gratis hulpprogramma voor analyse van statische code dat werkt met 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, moeten worden opgelost), Waarschuwing (moet worden gecontroleerd en moeten worden opgelost) en Informatie (de moeite waard om te bekijken voor aanbevolen procedures). Alle pakketten die naar de PowerShell Gallery worden gepubliceerd, worden gescand met PSScriptAnalyzer en eventuele fouten worden gerapporteerd aan de eigenaar en moeten worden opgelost.

De aanbevolen procedure is om uit te voeren Invoke-ScriptAnalyzer met -Recurse en -Severity Waarschuwing.

Bekijk de resultaten en zorg ervoor dat:

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

Gebruikers die pakketten downloaden van de PowerShell Gallery wordt sterk aangeraden om PSScriptAnalyzer uit te voeren en alle fouten en waarschuwingen te evalueren. Gebruikers zullen waarschijnlijk contact opnemen met pakketeigenaren als ze zien dat er een fout is gerapporteerd door PSScriptAnalyzer. Als er een overtuigende reden is voor uw pakket om code te behouden die is gemarkeerd als een fout, 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 handigste om op te nemen in pakketten die zijn gepubliceerd naar de PowerShell Gallery. Over het algemeen omzeilen gebruikers 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 bieden van hulp staan in Help voor cmdlets schrijven.
  • Help voor cmdlets maken, wat de beste aanpak is voor elk PowerShell-script, -functie of -cmdlet. Begin met How to Write Cmdlet Help (Help voor cmdlets schrijven) voor meer informatie over het maken van cmdlet-Help. Zie Informatie over op opmerkingen gebaseerde Help voor meer informatie over het toevoegen van help-informatie 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, waar Markdown een veelgebruikte 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 naar voorbeelden kijken vóór documentatie om te begrijpen hoe ze iets kunnen gebruiken. De beste typen voorbeelden tonen basisgebruik, plus een gesimuleerd realistisch gebruiksvoorbeeld, en de code is goed van commentaar voorzien. Voorbeelden voor modules die zijn gepubliceerd naar de PowerShell Gallery moeten zich in de map Voorbeelden onder de hoofdmap van de module bevinden.

Een goed patroon voor voorbeelden vindt u in de module PSDscResource onder de Examples\RegistryResource map. Er zijn vier voorbeeldgebruiksvoorbeelden met een korte beschrijving bovenaan elk bestand die documenteert wat er wordt gedemonstreerd.

Afhankelijkheden beheren

Het is belangrijk om modules op te geven die afhankelijk zijn van uw module 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 zijn bijvoorbeeld al geladen door een andere module. 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. Als u het veld RequiredVersion niet gebruikt, is het belangrijk om versie-updates voor de vereiste module te controleren om een specifieke versie op te geven. 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 opbouwende 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:

  • Contactpersoon eigenaar: hiermee kan een gebruiker een e-mail 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 te reageren op problemen die worden gemeld. Het enige nadeel van deze methode is dat alleen de gebruiker en eigenaar de communicatie te zien krijgen, dus de eigenaar moet mogelijk dezelfde vraag vaak beantwoorden.

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

Als er ongepast gedrag wordt waargenomen via een van deze communicatiekanalen, gebruikt u de functie Misbruik melden 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 hoe ze problemen kunnen oplossen. 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 in het pakket kunnen worden opgenomen. Met de modulestructuur kunt u de andere pakketten opnemen die we als best practices vermelden: 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 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 best practice voor DSC-configuraties is om de configuratie te publiceren 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 methode kan worden gebruikt met elk script.

Zelfstandige scripts die de andere best practices 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 wanneer u een script publiceert op 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 worden geleverd door organisaties met een speciale aanwezigheid op het web. Elk van deze kan worden beschouwd als een projectsite.

U voegt een koppeling toe door ProjectURI als volgt op te voegen 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.

Label 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 galeriezoekfilters in het linkerdeelvenster van de zoekresultaten. Als u uw pakket host op GitHub en uw pakket tagt, kunt u ook profiteren van ons voorbeeld van PowerShell Gallery compatibiliteitsschild.

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 hoe uw code werkt. Gebruikers kunnen er ook voor zorgen dat ze uw oorspronkelijke functionaliteit niet onderbreken 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 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 tot best practices.

De doelen voor testdekking worden genoemd in de documentatie van de resourcemodule met hoge kwaliteit, waarbij 70% codedekking voor testeenheden wordt aanbevolen.

Alle pakketten die naar de PowerShell Gallery worden gepubliceerd, moeten de licentievoorwaarden specificeren of gebonden zijn aan de licentie die is opgenomen in de Gebruiksvoorwaarden onder Bijlage A. De beste benadering voor het opgeven van een andere licentie is om een koppeling naar de licentie op te geven met behulp van de Licentie-URI in PSData. Zie Packages manifest and Gallery UI (Packages manifest and Gallery UI) 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

Ondertekening van code biedt gebruikers de hoogste mate van zekerheid voor wie het pakket heeft gepubliceerd en dat de kopie van de code die ze hebben verkregen precies is wat de uitgever heeft vrijgegeven. Zie Inleiding tot codeondertekening voor meer informatie over ondertekening van code in het algemeen. PowerShell ondersteunt de 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 algemeen 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 het uitvoeringsbeleid om ervoor te zorgen dat ondertekende scripts worden gebruikt.

Modules voor catalogusondertekening is een functie die is toegevoegd aan PowerShell in versie 5.1. Hoe u een module ondertekent, wordt beschreven in het artikel Catalog Cmdlets . Catalogusondertekening wordt uitgevoerd door een catalogusbestand te maken, dat een hash-waarde bevat voor elk bestand in de module, en vervolgens dat bestand te ondertekenen.

De cmdlets PowerShellGetPublish-Module, Install-Module, en Update-Module controleren de handtekening om er zeker van te zijn dat deze geldig is. Vervolgens wordt gecontroleerd of de hash-waarde voor elk pakket overeenkomt met wat er in de catalogus staat. Save-Module valideert een handtekening niet. Als een eerdere versie van de module op het systeem is geïnstalleerd, Install-Module wordt bevestigd dat de ondertekeningsinstantie voor de nieuwe versie overeenkomt met wat eerder is geïnstalleerd. Install-Module en Update-Module gebruikt de handtekening voor een .PSD1 bestand als het pakket niet is ondertekend met de catalogus. Catalogusondertekening werkt met, maar vervangt geen ondertekeningsscriptbestanden. PowerShell valideert catalogushandtekeningen niet tijdens het laden van de module.

Volg de SemVer-richtlijnen voor versiebeheer

SemVer is een openbare conventie waarin wordt beschreven hoe u een versie kunt structuren en wijzigen 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 0 als dat het enige nummer is dat wordt gebruikt.
  • Wijzigingen in het eerste getal (1.9.9999 naar 2.0.0) duiden op belangrijke wijzigingen en wijzigingen die fouten veroorzaken tussen de versies.
  • Wijzigingen in het tweede getal (1.1 naar 1.2) duiden op wijzigingen op functieniveau, zoals het toevoegen van nieuwe cmdlets aan een module.
  • Wijzigingen in het derde getal duiden op wijzigingen die geen fouten veroorzaken, zoals nieuwe parameters, bijgewerkte steekproeven of nieuwe tests.
  • Wanneer versies worden weergegeven, sorteert PowerShell de versies als tekenreeksen, dus 1.01.0 wordt behandeld als groter dan 1.001.0.

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

  • Het biedt geen ondersteuning voor voorlopige versies van tekenreeksen in versienummers. Dit is handig wanneer een uitgever een preview-versie van een nieuwe primaire versie wil leveren nadat een versie is opgegeven 1.0.0. Dit wordt ondersteund in een toekomstige release van de cmdlets PowerShell Gallery en PowerShellGet.
  • PowerShell en de PowerShell Gallery versiereeksen met 1, 2 en 4 segmenten toestaan. Veel vroege modules voldoen niet aan de richtlijnen en productreleases van Microsoft bevatten build-informatie als een vierde blok met 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 om het publicatieproces te testen. 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 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 het voordeel van het valideren van een paar van de vereisten, met name het valideren van het gebruik van een API-sleutel en of 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 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 te publiceren naar de PowerShell Gallery.

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

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

PowerShellGet gebruiken om te publiceren

Het wordt sterk aanbevolen dat uitgevers de Publish-Module cmdlets en Publish-Script gebruiken wanneer ze 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. Soms hebben uitgevers ervoor gekozen 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 waarom u of Publish-Scriptniet kunt gebruikenPublish-Module, laat het ons weten. Meld een probleem in de PowerShellGet GitHub-opslagplaats en geef de details op die ertoe leiden dat u NuGet of PackageManagement kiest.

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

  • De eerste ontwikkeling uitvoeren 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 moeten 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 een 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 aan uw project en uw module.
  • Bepaal of u uw pakket wilt ondertekenen met code.
  • 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.