Een item maken en publiceren

Het PowerShell Gallery is de plek om stabiele PowerShell-modules, -scripts en -Desired State Configuration-resources (DSC) te publiceren en te delen met de bredere PowerShell-gebruikerscommunity.

Dit artikel bevat informatie over de mechanica en belangrijke stappen voor het voorbereiden van een script of module en het publiceren ervan naar de PowerShell Gallery. We raden u sterk aan de publicatierichtlijnen te bekijken om te begrijpen hoe u ervoor kunt zorgen dat de items die u publiceert, breder worden geaccepteerd door PowerShell Gallery gebruikers.

De minimale vereisten voor het publiceren van een item naar de PowerShell Gallery zijn:

  • Een PowerShell Gallery-account en de API-sleutel eraan zijn gekoppeld
  • Zorg ervoor dat de vereiste metagegevens zich in uw item bevindt
  • Gebruik de hulpprogramma's voor validatie vooraf om ervoor te zorgen dat uw item gereed is om te publiceren
  • Het item publiceren naar de PowerShell Gallery met behulp van de opdrachten Publish-Module en Publish-Script
  • Reageren op vragen of problemen over uw item

De PowerShell Gallery accepteert PowerShell-modules en PowerShell-scripts. Wanneer we naar scripts verwijzen, bedoelen we een PowerShell-script dat één bestand is en geen deel uitmaakt van een grotere module.

Zie Een PowerShell Gallery-account maken voor het instellen van uw PowerShell Gallery-account.

Zodra u een account hebt gemaakt, kunt u de API-sleutel ophalen die nodig is om een item te publiceren. Nadat u zich hebt aangemeld met het account, wordt uw gebruikersnaam weergegeven boven aan de PowerShell Gallery pagina's in plaats van Registreren. Als u op uw gebruikersnaam klikt, gaat u naar de pagina Mijn account, waar u de API-sleutel vindt.

Belangrijk

De API-sleutel moet veilig worden behandeld als uw aanmelding en wachtwoord. Met deze sleutel kunt u of iemand anders elk item dat u bezit, bijwerken in de PowerShell Gallery. U wordt aangeraden de sleutel regelmatig bij te werken. Dit kan worden gedaan met de resetsleutel op de pagina Mijn account.

De PowerShell Gallery biedt informatie aan galeriegebruikers die zijn opgehaald uit metagegevensvelden die zijn opgenomen in het script of modulemanifest. Het maken of wijzigen van items voor publicatie in de PowerShell Gallery heeft een kleine set vereisten voor informatie die is opgegeven in het itemmanifest. We raden u ten zeerste aan de sectie Itemmetagegevens van de publicatierichtlijnen te bekijken om te leren hoe u de beste informatie kunt bieden aan gebruikers met uw items.

De cmdlets New-ModuleManifest en New-ScriptFileInfo maken de manifestsjabloon voor u, met tijdelijke aanduidingen voor alle manifestelementen.

Beide manifesten hebben twee secties die belangrijk zijn voor publicatie, het gebied Primaire sleutelgegevens en PSData van PrivateData. De primaire sleutelgegevens in een PowerShell-modulemanifest zijn alles buiten de sectie PrivateData. De set primaire sleutels is gekoppeld aan de versie van PowerShell die wordt gebruikt en niet-gedefinieerd wordt niet ondersteund. PrivateData ondersteunt het toevoegen van nieuwe sleutels, zodat de elementen die specifiek zijn voor de PowerShell Gallery zich in PSData bevinden.

Manifestelementen die het belangrijkst zijn om in te vullen voor het item dat u naar het PowerShell Gallery publiceert, zijn:

  • Script- of modulenaam: deze worden getrokken uit de namen van de .PS1 voor een script of de . PSD1 voor een module.
  • Versie: dit is een vereiste primaire sleutel, indeling moet voldoen aan SemVer-richtlijnen. Zie Aanbevolen procedures voor meer informatie.
  • Auteur: dit is een vereiste primaire sleutel en bevat de naam die aan het item moet worden gekoppeld. Zie auteurs en eigenaren hieronder.
  • Beschrijving: dit is een vereiste primaire sleutel, die wordt gebruikt om kort uit te leggen wat dit item doet en welke vereisten er zijn voor het gebruik ervan
  • ProjectURI: dit is een sterk aanbevolen URI-veld in PSData dat een koppeling biedt naar een GitHub-opslagplaats of een vergelijkbare locatie waar u ontwikkeling op het item doet
  • Tags: het is een sterke aanbeveling om uw pakket te taggen op basis van de compatibiliteit met PSEditions en platforms. Zie de publicatierichtlijnen voor meer informatie.

Auteurs en eigenaren van PowerShell Gallery items zijn gerelateerde concepten, maar komen niet altijd overeen. Itemeigenaren zijn gebruikers met PowerShell Gallery accounts die gemachtigd zijn om het item te onderhouden. Er kunnen veel eigenaren zijn die elk item kunnen bijwerken. De eigenaar is alleen beschikbaar vanuit de PowerShell Gallery en gaat verloren als het item van het ene systeem naar het andere wordt gekopieerd. Auteur is een tekenreeks die is ingebouwd in de manifestgegevens, zodat deze altijd deel uitmaakt van het item. De aanbevelingen voor items uit Microsoft-producten zijn:

  • Meerdere eigenaren hebben, waarbij ten minste één de naam is van het team dat het item produceert
  • Laat de auteur een bekende teamnaam (zoals Het Azure SDK-team) of Microsoft Corporation zijn

Uw item vooraf valideren

Er zijn enkele hulpprogramma's die u moet uitvoeren voor uw code voordat u het item publiceert naar de PowerShell Gallery:

  • PowerShell Script Analyzer, dat zich in de PowerShell Gallery
  • Voor modules maakt Test-ModuleManifest deel uit van PowerShell
  • Voor scripts Test-ScriptFileInfo die wordt geleverd met PowerShell Get

PowerShell Script Analyzer is een hulpprogramma voor statische codeanalyse waarmee uw code wordt gescand om ervoor te zorgen dat deze voldoet aan de basisrichtlijnen voor PowerShell-codering. Dit hulpprogramma identificeert veelvoorkomende en kritieke problemen in uw code en moet regelmatig worden uitgevoerd tijdens de ontwikkeling om u te helpen uw item klaar te maken voor publicatie. PowerShell Script Analyzer bevat een lijst met problemen die zijn geïdentificeerd als fouten, waarschuwingen en informatie. Alle fouten moeten worden opgelost voordat u naar de PowerShell Gallery publiceert. Waarschuwingen moeten worden gecontroleerd en de meeste waarschuwingen moeten worden aangepakt. PowerShell Script Analyzer wordt uitgevoerd telkens wanneer een item wordt gepubliceerd of bijgewerkt in de PowerShell Gallery. Het team Galeriebewerkingen neemt contact op met itemeigenaren om fouten op te lossen die zijn gevonden.

Als de manifestinformatie in uw item niet kan worden gelezen door de PowerShell Gallery-infrastructuur, kunt u deze niet publiceren. Test-ModuleManifest ondervindt veelvoorkomende problemen waardoor de module niet bruikbaar is wanneer deze wordt geïnstalleerd. Deze moet worden uitgevoerd voor elke module voordat deze naar de PowerShell Gallery wordt gepubliceerd.

Op dezelfde manier valideert Test-ScriptFileInfo de metagegevens in een script en moet worden uitgevoerd op elk script (gescheiden van een module) voordat deze naar de PowerShell Gallery wordt gepubliceerd.

Publicatie-items

U moet het Publish-Script of Publish-Module gebruiken om items naar de PowerShell Gallery te publiceren. Voor beide opdrachten is het volgende vereist:

  • Het pad naar het item dat u gaat publiceren. Gebruik voor een module de map met de naam van uw module. Als u een map opgeeft die meerdere versies van dezelfde module bevat, moet u RequiredVersion opgeven.
  • Een Nuget-API-sleutel. Dit is de API-sleutel op de pagina Mijn account op de PowerShell Gallery.

De meeste andere opties op de opdrachtregel moeten zich in de manifestgegevens bevinden voor het item dat u publiceert. U hoeft ze dus niet op te geven in de opdracht.

Als u fouten wilt voorkomen, wordt u sterk aangeraden de opdrachten uit te voeren met behulp van -WhatIf -Verbose, voordat u deze publiceert. Dit bespaart veel tijd, omdat u telkens wanneer u publiceert naar de PowerShell Gallery, het versienummer moet bijwerken in de manifestsectie van het item.

Voorbeelden zijn:

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Controleer de uitvoer zorgvuldig en als u geen fouten of waarschuwingen ziet, herhaalt u de opdracht zonder -WhatIf.

Alle items die naar de PowerShell Gallery worden gepubliceerd, worden gescand op virussen en worden geanalyseerd met behulp van PowerShell Script Analyzer. Eventuele problemen die zich op dat moment voordoen, worden ter oplossing teruggestuurd naar de uitgever.

Zodra u een item hebt gepubliceerd naar de PowerShell Gallery, moet u kijken naar feedback over uw item.

  • Zorg ervoor dat u het e-mailadres bewaakt dat is gekoppeld aan het account dat wordt gebruikt om te publiceren. Gebruikers en het PowerShell Gallery Operations-team geven feedback via dat account, inclusief problemen van de PSSA- of antivirusscans. Als het e-mailaccount ongeldig is of als er ernstige problemen worden gerapporteerd aan het account en lange tijd onopgeloste gelaten, kunnen items worden beschouwd als verlaten en worden ze verwijderd uit de PowerShell Gallery zoals beschreven in onze Gebruiksvoorwaarden.