Riktlinjer och metodtips för PowerShellGallery-publicering

  • Artikel

Den här artikeln beskriver rekommenderade steg som används av Microsoft-team för att säkerställa att de paket som publiceras till PowerShell-galleriet kommer att användas i stor utsträckning och ge högt värde till användarna, baserat på hur PowerShell-galleriet hanterar manifestdata och på feedback från ett stort antal PowerShell-galleriet användare. Paket som publiceras enligt dessa riktlinjer är mer benägna att installeras, vara betrodda och locka fler användare.

Nedan finns riktlinjer för vad som gör ett bra PowerShell-galleriet paket, vilka valfria manifestinställningar som är viktigast, förbättra koden med feedback från första granskare och Powershell Script Analyzer, versionshantering av din modul, dokumentation, tester och exempel för hur du använder det du har delat. Mycket av den här dokumentationen följer riktlinjerna för publicering av DSC-resursmoduler av hög kvalitet.

Information om hur du publicerar ett paket i PowerShell-galleriet finns i Skapa och publicera ett paket.

Feedback om dessa riktlinjer välkomnas. Om du har feedback kan du öppna ärenden på vår GitHub-dokumentationslagringsplats.

Metodtips för publicering av paket

Följande metodtips är vad användarna av PowerShell-galleriet objekt säger är viktigt och listas i nominell prioritetsordning. Paket som följer dessa riktlinjer är mycket mer benägna att laddas ned och antas av andra.

  • Använda PSScriptAnalyzer
  • Inkludera dokumentation och exempel
  • Var lyhörd för feedback
  • Ange moduler i stället för skript
  • Ange länkar till en projektwebbplats
  • Tagga ditt paket med kompatibla PSEdition(er) och plattformar
  • Inkludera tester med dina moduler
  • Inkludera och/eller länka till licensvillkor
  • Signera din kod
  • Följ SemVer-riktlinjerna för versionshantering
  • Använd vanliga taggar, enligt beskrivningen i Common PowerShell-galleriet-taggar
  • Testa publicering med hjälp av en lokal lagringsplats
  • Använda PowerShellGet för att publicera

Var och en av dessa beskrivs kortfattat i avsnitten nedan.

Använda PSScriptAnalyzer

PSScriptAnalyzer är ett kostnadsfritt analysverktyg för statisk kod som fungerar med PowerShell-kod. PSScriptAnalyzer identifierar de vanligaste problemen som visas i PowerShell-kod och ofta en rekommendation för hur du löser problemet. Verktyget är enkelt att använda och kategoriserar problemen som Fel (allvarliga, måste åtgärdas), Varning (måste granskas och bör åtgärdas) och Information (värt att kolla in för bästa praxis). Alla paket som publiceras till PowerShell-galleriet genomsöks med PSScriptAnalyzer och eventuella fel rapporteras tillbaka till ägaren och måste åtgärdas.

Det bästa sättet är att köra Invoke-ScriptAnalyzer med -Recurse och -Severity Varning.

Granska resultaten och se till att:

  • Alla fel korrigeras eller åtgärdas i din dokumentation.
  • Alla varningar granskas och åtgärdas i förekommande fall.

Användare som laddar ned paket från PowerShell-galleriet uppmanas starkt att köra PSScriptAnalyzer och utvärdera alla fel och varningar. Det är mycket troligt att användarna kontaktar paketägarna om de ser att ett fel har rapporterats av PSScriptAnalyzer. Om det finns en övertygande anledning för ditt paket att behålla kod som har flaggats som ett fel lägger du till den informationen i dokumentationen för att undvika att behöva svara på samma fråga många gånger.

Inkludera dokumentation och exempel

Dokumentation och exempel är det bästa sättet att se till att användarna kan dra nytta av all delad kod.

Dokumentation är det mest användbara att ta med i paket som publicerats till PowerShell-galleriet. Användare kringgår vanligtvis paket utan dokumentation eftersom alternativet är att läsa koden för att förstå vad paketet är och hur det ska användas. Det finns flera artiklar om hur du tillhandahåller dokumentation med PowerShell-paket, inklusive:

  • Riktlinjer för att ge hjälp finns i Hjälp om att skriva cmdletar.
  • Skapa cmdlet-hjälp, vilket är den bästa metoden för powershell-skript, funktioner eller cmdletar. Om du vill ha information om hur du skapar cmdlet-hjälp börjar du med Hjälp om att skriva cmdletar. Information om hur du lägger till hjälp i ett skript finns i Om kommentarsbaserad hjälp.
  • Många moduler innehåller även dokumentation i textformat, till exempel MarkDown-filer. Detta kan vara särskilt användbart när det finns en projektwebbplats i GitHub, där Markdown är ett format som används mycket. Det bästa sättet är att använda Markdown med GitHub-smak.

Exempel visar användarna hur paketet är avsett att användas. Många utvecklare kommer att säga att de tittar på exempel före dokumentationen för att förstå hur man använder något. De bästa typerna av exempel visar grundläggande användning, plus ett simulerat realistiskt användningsfall, och koden är väl kommenterad. Exempel för moduler som publiceras till PowerShell-galleriet bör finnas i en exempelmapp under modulroten.

Ett bra mönster för exempel finns i PSDscResource-modulenExamples\RegistryResource under mappen . Det finns fyra exempel på användningsfall med en kort beskrivning överst i varje fil som dokumenterar vad som visas.

Hantera beroenden

Det är viktigt att ange moduler som modulen är beroende av i modulmanifestet. Detta gör att slutanvändaren inte behöver bekymra sig om att installera rätt versioner av moduler som du är beroende av. Om du vill ange beroende moduler bör du använda det modulfält som krävs i modulmanifestet. Då läses alla listade moduler in i den globala miljön innan du importerar modulen om de inte redan har lästs in. Vissa moduler kanske till exempel redan har lästs in av en annan modul. Det går också att ange en specifik version som ska läsas in med fältet RequiredVersion i stället för fältet ModuleVersion . När du använder ModuleVersion läses den senaste versionen in med minst den angivna versionen. När du inte använder fältet RequiredVersion är det viktigt att övervaka versionsuppdateringar till den nödvändiga modulen för att ange en viss version. Det är särskilt viktigt att vara medveten om eventuella icke-bakåtkompatibla ändringar som kan påverka användarupplevelsen i modulen.

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"})

Svara på feedback

Paketägare som svarar korrekt på feedback värderas högt av communityn. Användare som ger konstruktiv feedback är viktiga att svara på eftersom de är tillräckligt intresserade av paketet för att försöka förbättra det.

Det finns en feedbackmetod i PowerShell-galleriet:

  • Kontaktägare: På så sätt kan en användare skicka ett e-postmeddelande till paketägaren. Som paketägare är det viktigt att övervaka e-postadressen som används med PowerShell-galleriet paket och svara på problem som uppstår. Den enda nackdelen med den här metoden är att endast användaren och ägaren någonsin kommer att se kommunikationen, så ägaren kan behöva svara på samma fråga många gånger.

Ägare som svarar på feedback konstruktivt uppskattas av communityn. Använd möjligheten i rapporten för att begära mer information. Om det behövs anger du en lösning eller identifierar om en uppdatering åtgärdar ett problem.

Om olämpligt beteende observeras från någon av dessa kommunikationskanaler använder du funktionen Rapportera missbruk i PowerShell-galleriet för att kontakta galleriadministratörerna.

Moduler kontra skript

Att dela ett skript med andra användare är bra och ger andra exempel på hur de kan lösa problem som de kan ha. Problemet är att skript i PowerShell-galleriet är enskilda filer utan separat dokumentation, exempel och tester.

PowerShell-moduler har en mappstruktur som gör att flera mappar och filer kan ingå i paketet. Modulstrukturen gör det möjligt att inkludera de andra paket som vi listar som bästa praxis: cmdlet-hjälp, dokumentation, exempel och tester. Den största nackdelen är att ett skript i en modul måste exponeras och användas som en funktion. Information om hur du skapar en modul finns i Skriva en Windows PowerShell-modul.

Det finns situationer där ett skript ger en bättre upplevelse för användaren, särskilt med DSC-konfigurationer. Bästa praxis för DSC-konfigurationer är att publicera konfigurationen som ett skript med en tillhörande modul som innehåller dokument, exempel och tester. Skriptet visar den medföljande modulen med hjälp av RequiredModules = @(Name of the Module). Den här metoden kan användas med valfritt skript.

Fristående skript som följer de andra metodtipsen ger andra användare verkligt värde. Att tillhandahålla kommentarsbaserad dokumentation och en länk till en projektwebbplats rekommenderas starkt när du publicerar ett skript till PowerShell-galleriet.

En projektwebbplats är den plats där en utgivare kan interagera direkt med användarna av sina PowerShell-galleriet paket. Användare föredrar paket som tillhandahåller detta, eftersom det gör det möjligt för dem att få information om paketet enklare. Många paket i PowerShell-galleriet utvecklas i GitHub, andra tillhandahålls av organisationer med en dedikerad webbnärvaro. Var och en av dessa kan betraktas som en projektwebbplats.

Du lägger till en länk genom att inkludera ProjectURI i avsnittet PSData i manifestet på följande sätt:

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

När en ProjectURI anges innehåller PowerShell-galleriet en länk till projektwebbplatsen till vänster på paketsidan.

Tagga ditt paket med kompatibla PSEdition(er) och plattformar

Använd följande taggar för att visa för användarna vilka paket som fungerar bra med deras miljö:

  • PSEdition_Desktop: Paket som är kompatibla med Windows PowerShell
  • PSEdition_Core: Paket som är kompatibla med PowerShell 6 och senare
  • Windows: Paket som är kompatibla med Windows-operativsystemet
  • Linux: Paket som är kompatibla med Linux-operativsystem
  • MacOS: Paket som är kompatibla med Mac-operativsystemet

Genom att tagga paketet med kompatibla plattformar inkluderas det i gallerisökningsfilter i det vänstra fönstret i sökresultaten. Om du är värd för ditt paket på GitHub, när du taggar ditt paket, kan du också dra nytta av vårt PowerShell-galleriet kompatibilitetsskyddskompatibilitetssköldexempel.

Inkludera tester

Att inkludera tester med öppen källkod är viktigt för användarna, eftersom det ger dem garantier om vad du validerar och ger information om hur koden fungerar. Det gör också att användarna kan se till att de inte bryter mot dina ursprungliga funktioner om de ändrar koden så att den passar deras miljö.

Vi rekommenderar starkt att tester skrivs för att dra nytta av Pester-testramverket, som har utformats särskilt för PowerShell. Pester finns i GitHub, PowerShell-galleriet och levereras i Windows 10, Windows Server 2016, WMF 5.0 och WMF 5.1.

Pester-projektwebbplatsen i GitHub innehåller bra dokumentation om hur du skriver Pester-tester, från att komma igång till bästa praxis.

Målen för testtäckning anges i dokumentationen för resursmoduler av hög kvalitet, med 70 % enhetstestkod som rekommenderas.

Alla paket som publiceras i PowerShell-galleriet måste ange licensvillkoren eller vara bundna av licensen som ingår i användningsvillkoren under bilaga A. Det bästa sättet att ange en annan licens är att tillhandahålla en länk till licensen med hjälp av LicenseURI i PSData. Mer information finns i Paketmanifest och gallerigränssnitt.

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'

Signera koden

Kodsignering ger användarna den högsta säkerhetsnivån för vem som publicerade paketet, och att kopian av koden de skaffar är exakt vad utgivaren släppte. Mer information om kodsignering finns i Introduktion till kodsignering. PowerShell stöder validering av kodsignering via två primära metoder:

  • Signera skriptfiler
  • Katalogsignering av en modul

Att signera PowerShell-filer är en väletablerad metod för att säkerställa att koden som körs skapas av en tillförlitlig källa och inte har ändrats. Information om hur du signerar PowerShell-skriptfiler beskrivs i artikeln Om signering . I översikten kan en signatur läggas till i alla .PS1 filer som PowerShell verifierar när skriptet läses in. PowerShell kan begränsas med hjälp av cmdletar för körningsprinciper för att säkerställa användningen av signerade skript.

Katalogsigneringsmoduler är en funktion som läggs till i PowerShell i version 5.1. Så här signerar du en modul i artikeln Katalog-cmdletar . I översikten görs katalogsignering genom att skapa en katalogfil som innehåller ett hash-värde för varje fil i modulen och sedan signerar filen.

PowerShellGetPublish-Module, Install-Module, och Update-Module cmdletar kontrollerar signaturen för att säkerställa att den är giltig och bekräftar sedan att hash-värdet för varje paket matchar det som finns i katalogen. Save-Module validerar inte en signatur. Om en tidigare version av modulen är installerad på systemet Install-Module bekräftar att signeringsutfärdaren för den nya versionen matchar det som tidigare installerades. Install-Module och Update-Module använder signaturen för en .PSD1 fil om paketet inte är katalogsignerat. Katalogsignering fungerar med, men ersätter inte signeringsskriptfiler. PowerShell validerar inte katalogsignaturer vid inläsningen av modulen.

Följ SemVer-riktlinjerna för versionshantering

SemVer är en offentlig konvention som beskriver hur du strukturerar och ändrar en version så att ändringar enkelt kan tolkas. Versionen för paketet måste ingå i manifestdata.

  • Versionen ska struktureras som tre numeriska block avgränsade med punkter, som i 0.1.1 eller 4.11.192.
  • Versioner som börjar med 0 anger att paketet ännu inte är produktionsklart, och det första talet bör bara börja med 0 om det är det enda talet som används.
  • Ändringar i det första talet (1.9.9999 till 2.0.0) indikerar större och icke-bakåtkompatibla ändringar mellan versionerna.
  • Ändringar av det andra talet (1.1 till 1.2) indikerar ändringar på funktionsnivå, till exempel att lägga till nya cmdletar i en modul.
  • Ändringar i det tredje talet indikerar icke-bakåtkompatibla ändringar, till exempel nya parametrar, uppdaterade exempel eller nya tester.
  • När du listar versioner sorterar PowerShell versionerna som strängar, så 1.01.0 de behandlas som större än 1.001.0.

PowerShell skapades innan SemVer publicerades, så det ger stöd för de flesta men inte alla element i SemVer, särskilt:

  • Den stöder inte förhandsversionssträngar i versionsnummer. Detta är användbart när en utgivare vill leverera en förhandsversion av en ny huvudversion efter att ha angett en version 1.0.0. Detta stöds i en framtida version av cmdletarna PowerShell-galleriet och PowerShellGet.
  • PowerShell och PowerShell-galleriet tillåta versionssträngar med 1, 2 och 4 segment. Många tidiga moduler följde inte riktlinjerna och produktversioner från Microsoft innehåller bygginformation som ett fjärde block med siffror (till exempel 5.1.14393.1066). Ur versionssynpunkt ignoreras dessa skillnader.

Testa med en lokal lagringsplats

PowerShell-galleriet är inte utformat för att vara ett mål för testning av publiceringsprocessen. Det bästa sättet att testa publiceringsprocessen från slutpunkt till slutpunkt för PowerShell-galleriet är att konfigurera och använda din egen lokala lagringsplats. Detta kan göras på några sätt, till exempel:

  • Konfigurera en lokal PowerShell-galleriet-instans med hjälp av PS Private Gallery-projektet i GitHub. Det här förhandsgranskningsprojektet hjälper dig att konfigurera en instans av PowerShell-galleriet som du kan styra och använda för dina tester.
  • Konfigurera en intern Nuget-lagringsplats. Detta kräver mer arbete för att konfigurera, men har fördelen att verifiera några fler av kraven, särskilt validering av användning av en API-nyckel och huruvida beroenden finns i målet när du publicerar.
  • Konfigurera en filresurs som testlagringsplats. Det här är enkelt att konfigurera, men eftersom det är en filresurs sker inte de valideringar som anges ovan. En möjlig fördel i det här fallet är att filresursen inte kontrollerar den NÖDVÄNDIGA API-nyckeln, så du kan använda samma nyckel som du skulle använda för att publicera till PowerShell-galleriet.

Med någon av dessa lösningar använder Register-PSRepository du för att definiera en ny lagringsplats som du använder i parametern -Repository för Publish-Module.

Ytterligare en punkt om testpublicering: alla paket som du publicerar till PowerShell-galleriet kan inte tas bort utan hjälp från driftteamet, som bekräftar att inget är beroende av det paket som du vill publicera. Därför stöder vi inte PowerShell-galleriet som testmål och kontaktar alla utgivare som gör det.

Använda PowerShellGet för att publicera

Vi rekommenderar starkt att utgivare använder Publish-Module cmdletarna och Publish-Script när de arbetar med PowerShell-galleriet. PowerShellGet skapades för att undvika att komma ihåg viktig information om hur du installerar från och publicerar till PowerShell-galleriet. Ibland har utgivare valt att hoppa över PowerShellGet och använda NuGet-klienten eller PackageManagement-cmdletar i stället för Publish-Module. Det finns ett antal detaljer som lätt missas, vilket resulterar i en mängd olika supportförfrågningar.

Om det finns en anledning till att du inte kan använda Publish-Module eller Publish-Scriptkan du meddela oss. Ange ett problem i PowerShellGet GitHub-lagringsplatsen och ange den information som gör att du kan välja NuGet eller PackageManagement.

Den mest lyckade metoden vi har hittat för paket som publicerats i PowerShell-galleriet är följande:

  • Utför inledande utveckling på en projektwebbplats med öppen källkod. PowerShell-teamet använder GitHub.
  • Använd feedback från granskare och PowerShell Script Analyzer för att få koden till stabilt tillstånd.
  • Inkludera dokumentation så att andra vet hur du använder ditt arbete.
  • Testa publiceringsåtgärden med hjälp av en lokal lagringsplats.
  • Publicera en stabil version eller Alpha-version till PowerShell-galleriet, se till att inkludera dokumentationen och länka till projektwebbplatsen.
  • Samla in feedback och iterera om koden på projektwebbplatsen och publicera sedan stabila uppdateringar till PowerShell-galleriet.
  • Lägg till exempel och Pester-tester i projektet och modulen.
  • Bestäm om du vill kodsignera paketet.
  • När du känner att projektet är redo att användas i en produktionsmiljö publicerar du en 1.0.0 version till PowerShell-galleriet.
  • Fortsätt att samla in feedback och iterera din kod baserat på användarindata.