Dela via

Skapa och publicera ett objekt

  • Artikel

Den PowerShell-galleriet är platsen där du kan publicera och dela stabila PowerShell-moduler, skript och Desired State Configuration-resurser (DSC) med den bredare PowerShell-användarcommunityn.

Den här artikeln beskriver mekaniken och viktiga steg för att förbereda ett skript eller en modul och publicerar det till PowerShell-galleriet. Vi rekommenderar starkt att du läser riktlinjerna för publicering för att förstå hur du säkerställer att de objekt som du publicerar godkänns mer allmänt av PowerShell-galleriet användare.

Minimikraven för att publicera ett objekt till PowerShell-galleriet är:

  • Ha ett PowerShell-galleriet konto och den API-nyckel som är associerad med det
  • Kontrollera att nödvändiga metadata finns i ditt objekt
  • Använd förvalideringsverktygen för att se till att objektet är redo att publiceras
  • Publicera objektet till PowerShell-galleriet med hjälp av kommandona Publish-Module och Publish-Script
  • Svara på frågor eller frågor om ditt objekt

PowerShell-galleriet accepterar PowerShell-moduler och PowerShell-skript. När vi refererar till skript menar vi ett PowerShell-skript som är en enda fil och inte en del av en större modul.

Information om hur du konfigurerar ditt PowerShell-galleriet-konto finns i Skapa ett PowerShell-galleriet-konto.

När du har skapat ett konto kan du hämta den API-nyckel som behövs för att publicera ett objekt. När du har loggat in med kontot visas ditt användarnamn överst på PowerShell-galleriet sidor i stället för Registrera. Om du klickar på ditt användarnamn kommer du till sidan Mitt konto, där du hittar API-nyckeln.

Viktigt

API-nyckeln måste behandlas lika säkert som din inloggning och ditt lösenord. Med den här nyckeln kan du, eller någon annan, uppdatera alla objekt som du äger i PowerShell-galleriet. Vi rekommenderar att du uppdaterar nyckeln regelbundet, vilket kan göras med hjälp av Återställningsnyckel på sidan Mitt konto.

PowerShell-galleriet innehåller information till gallerianvändare som hämtats från metadatafält som ingår i skript- eller modulmanifestet. Att skapa eller ändra objekt för publicering till PowerShell-galleriet har en liten uppsättning krav för information som anges i objektmanifestet. Vi rekommenderar starkt att du läser avsnittet Objektmetadata i riktlinjerna för publicering för att lära dig hur du ger användarna den bästa informationen med dina objekt.

Cmdletarna New-ModuleManifest och New-ScriptFileInfo skapar manifestmallen åt dig, med platshållare för alla manifestelement.

Båda manifesten har två avsnitt som är viktiga för publicering, området Primärnyckeldata och PSData i PrivateData. Primärnyckeldata i ett PowerShell-modulmanifest är allt utanför avsnittet PrivateData. Uppsättningen med primära nycklar är kopplad till den version av PowerShell som används och odefinierad stöds inte. PrivateData har stöd för att lägga till nya nycklar, så de element som är specifika för PowerShell-galleriet finns i PSData.

Manifestelement som är viktigast att fylla i för objekt som du publicerar till PowerShell-galleriet är:

  • Skript- eller modulnamn – de hämtas från namnen på .PS1 för ett skript eller . PSD1 för en modul.
  • Version – det här är en obligatorisk primärnyckel. Formatet bör följa SemVer-riktlinjerna. Mer information finns i Metodtips.
  • Författare – det här är en obligatorisk primärnyckel och innehåller namnet som ska associeras med objektet. Se Författare och ägare nedan.
  • Beskrivning – det här är en obligatorisk primärnyckel som används för att kortfattat förklara vad det här objektet gör och eventuella krav för att använda det
  • ProjectURI – det här är ett starkt rekommenderat URI-fält i PSData som tillhandahåller en länk till en GitHub-lagringsplats eller liknande plats där du utvecklar objektet
  • Taggar – det är en stark rekommendation att tagga paketet baserat på dess kompatibilitet med PSEditions och plattformar. Mer information finns i Riktlinjerna för publicering.

Författare och ägare av PowerShell-galleriet objekt är relaterade begrepp, men matchar inte alltid. Objektägare är användare med PowerShell-galleriet konton som har behörighet att underhålla objektet. Det kan finnas många ägare som kan uppdatera valfritt objekt. Ägaren är endast tillgänglig från PowerShell-galleriet och går förlorad om objektet kopieras från ett system till ett annat. Författare är en sträng som är inbyggd i manifestdata, så den är alltid en del av objektet. Rekommendationerna för objekt från Microsoft-produkter är:

  • Ha flera ägare, där minst en är namnet på det team som producerar objektet
  • Låt författaren vara ett välkänt teamnamn (till exempel Azure SDK Team) eller Microsoft Corporation

Verifiera objektet i förväg

Det finns några verktyg som du måste köra mot koden innan du publicerar objektet i PowerShell-galleriet:

  • PowerShell Script Analyzer, som finns i PowerShell-galleriet
  • För moduler Test-ModuleManifest som ingår i PowerShell
  • För skript Test-ScriptFileInfo som medföljer PowerShell Get

PowerShell Script Analyzer är ett verktyg för analys av statisk kod som genomsöker koden för att säkerställa att den uppfyller grundläggande riktlinjer för PowerShell-kodning. Det här verktyget identifierar vanliga och kritiska problem i koden och bör köras regelbundet under utvecklingen för att hjälpa dig att förbereda ditt objekt för publicering. PowerShell Script Analyzer innehåller en lista över problem som identifieras som fel, varningar och information. Alla fel måste åtgärdas innan du publicerar till PowerShell-galleriet. Varningar måste granskas och de flesta bör åtgärdas. PowerShell Script Analyzer körs varje gång ett objekt publiceras eller uppdateras i PowerShell-galleriet. Galleriåtgärdsteamet kontaktar objektägare för att åtgärda fel som hittas.

Om manifestinformationen i objektet inte kan läsas av PowerShell-galleriet infrastruktur kan du inte publicera. Test-ModuleManifest fångar upp vanliga problem som gör att modulen inte kan användas när den installeras. Den måste köras för varje modul innan den publiceras till PowerShell-galleriet.

På samma sätt validerar Test-ScriptFileInfo metadata i ett skript och måste köras på varje skript (publicerat separat från en modul) innan det publiceras till PowerShell-galleriet.

Publicera objekt

Du måste använda Publish-Script eller Publish-Module för att publicera objekt till PowerShell-galleriet. Båda dessa kommandon kräver:

  • Sökvägen till det objekt som du ska publicera. För en modul använder du mappen med namnet för din modul. Om du anger en mapp som innehåller flera versioner av samma modul måste du ange RequiredVersion.
  • En Nuget API-nyckel. Det här är API-nyckeln som finns på sidan Mitt konto på PowerShell-galleriet.

De flesta andra alternativ på kommandoraden ska finnas i manifestdata för det objekt som du publicerar, så du bör inte behöva ange dem i kommandot.

För att undvika fel rekommenderar vi starkt att du provar kommandona med hjälp av -WhatIf -Verbose innan du publicerar. Detta sparar mycket tid eftersom du varje gång du publicerar till PowerShell-galleriet måste uppdatera versionsnumret i manifestavsnittet för objektet.

Exempel är:

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

Granska utdata noggrant och om du inte ser några fel eller varningar upprepar du kommandot utan -WhatIf.

Alla objekt som publiceras till PowerShell-galleriet genomsöks efter virus och analyseras med hjälp av PowerShell Script Analyzer. Eventuella problem som uppstår vid den tidpunkten skickas tillbaka till utgivaren för lösning.

När du har publicerat ett objekt till PowerShell-galleriet måste du watch för feedback om ditt objekt.

  • Se till att du övervakar den e-postadress som är associerad med det konto som används för att publicera. Användare och PowerShell-galleriet-driftteamet ger feedback via det kontot, inklusive problem från PSSA- eller antivirusgenomsökningar. Om e-postkontot är ogiltigt eller om allvarliga problem rapporteras till kontot och lämnas olösta under en längre tid, kan objekt betraktas som övergivna och tas bort från PowerShell-galleriet enligt beskrivningen i våra användningsvillkor.