Een item maken en publiceren

  • Artikel

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

In dit artikel worden de mechanismen en belangrijke stappen beschreven voor het voorbereiden van een script of module en het publiceren ervan naar de PowerShell Gallery. We raden u ten zeer aan de publicatierichtlijnen te lezen 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 hebben en de API-sleutel die eraan is gekoppeld
  • Zorg ervoor dat 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 worden gepubliceerd
  • Publiceer het item naar de PowerShell Gallery met behulp van de opdrachten Publish-Module en Publish-Script
  • Reageren op vragen of zorgen over uw object

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 informatie over het instellen van uw PowerShell Gallery-account.

Nadat 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 boven aan de PowerShell Gallery pagina's weergegeven 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 net zo veilig worden behandeld als uw aanmeldings- en wachtwoord. Met deze sleutel kunt u of iemand anders elk item in de PowerShell Gallery bijwerken. U wordt aangeraden de sleutel regelmatig bij te werken. Dit kunt u doen met behulp van De sleutel opnieuw instellen 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 naar de PowerShell Gallery heeft een kleine set vereisten voor informatie die wordt opgegeven in het itemmanifest. We raden u ten zeerste aan de sectie Metagegevens van items van de publicatierichtlijnen te bekijken voor meer informatie over het verstrekken van de beste informatie aan gebruikers met uw items.

Met de cmdlets New-ModuleManifest en New-ScriptFileInfo wordt de manifestsjabloon voor u gemaakt, 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 bevinden zich 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 items die u publiceert naar de PowerShell Gallery zijn:

  • Script- of modulenaam: deze worden opgehaald uit de namen van de .PS1 voor een script of de . PSD1 voor een module.
  • Versie: dit is een vereiste primaire sleutel. De indeling moet voldoen aan de SemVer-richtlijnen. Zie Best practices 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 eventuele vereisten voor het gebruik ervan
  • ProjectURI: dit is een sterk aanbevolen URI-veld in PSData met een koppeling naar een GitHub-opslagplaats of een vergelijkbare locatie waar u de ontwikkeling van het item uitvoert
  • 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 verwante 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 vanaf 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 van 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 zijn (zoals Azure SDK Team) of Microsoft Corporation

Uw item vooraf valideren

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

  • PowerShell Script Analyzer, dat zich in de PowerShell Gallery
  • Voor modules Test-ModuleManifest die deel uitmaakt van PowerShell
  • Voor scripts, Test-ScriptFileInfo die wordt geleverd bij 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 gereed te maken voor publicatie. PowerShell Script Analyzer biedt een lijst met problemen die zijn geïdentificeerd als Fouten, Waarschuwing en Informatie. Alle fouten moeten worden opgelost voordat u naar de PowerShell Gallery publiceert. Waarschuwingen moeten worden gecontroleerd en de meeste 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 gevonden fouten op te lossen.

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

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

Publicatie-items

U moet 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 voor 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, dus u hoeft deze niet op te geven in de opdracht.

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

Voorbeelden hiervan 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 teruggestuurd naar de uitgever voor oplossing.

Nadat u een item naar de PowerShell Gallery hebt gepubliceerd, moet u watch voor feedback over uw item.

  • Zorg ervoor dat u het e-mailadres controleert 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 met de PSSA of antivirusscans. Als het e-mailaccount ongeldig is of als er ernstige problemen aan het account worden gemeld en lange tijd niet worden opgelost, kunnen items worden beschouwd als verlaten en worden ze verwijderd uit de PowerShell Gallery zoals beschreven in onze Gebruiksvoorwaarden.