Dela via

Riktlinjer och metodtips för PowerShellGallery-publicering

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 antas i stor utsträckning och ger användarna ett högt värde, baserat på hur PowerShell-galleriet hanterar manifestdata och på feedback från ett stort antal PowerShell-gallerianvä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ättring av koden med feedback från inledande granskare och Powershell Script Analyzer, versionshantering av modulen, dokumentation, tester och exempel på hur du använder det du har delat. En stor del 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 till PowerShell-galleriet finns i Skapa och publicera ett paket.

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

Metodtips för publicering av paket

Följande metodtips är vad användarna av PowerShell-galleriobjekt säger är viktigt och visas 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 Vanliga PowerShell-galleritaggar
  • 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 verktyg för analys av statisk kod som fungerar på PowerShell-kod. PSScriptAnalyzer identifierar de vanligaste problemen som visas i PowerShell-kod och ofta en rekommendation för hur du åtgärdar 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 hjälp av 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 tillämpliga fall.

Användare som laddar ned paket från PowerShell-galleriet rekommenderas starkt att köra PSScriptAnalyzer och utvärdera alla fel och varningar. Det är mycket troligt att användarna kontaktar paketägare om de ser att det finns ett fel som rapporterats av PSScriptAnalyzer. Om det finns en övertygande anledning för ditt paket att behålla kod som flaggas 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 i 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 tillhandahålla hjälp finns i Så här skriver du cmdlet-hjälp.
  • Skapa cmdlet-hjälp, vilket är den bästa metoden för alla PowerShell-skript, funktioner eller cmdletar. Information om hur du skapar cmdlet-hjälp finns i Så här skriver du cmdlet-hjälp. 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 GitHub-smaksatt Markdown.

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 på moduler som publiceras i PowerShell-galleriet bör finnas i en exempelmapp under modulroten.

Ett bra mönster för exempel finns i PSDscResource-modulen under mappen Examples\RegistryResource . Det finns fyra exempelanvändningsfall med en kort beskrivning överst i varje fil som dokumenterar det som demonstreras.

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 obligatoriska modulfältet i modulmanifestet. Detta läser in alla listade moduler i den globala miljön innan du importerar modulen om de inte redan har lästs in. Vissa moduler kan till exempel redan ha lästs in av en annan modul. Det är också möjligt att ange en specifik version som ska läsas in med hjälp av fältet RequiredVersion i stället för fältet ModuleVersion . När du använder ModuleVersion läser den in den senaste versionen som är tillgänglig med minst den angivna versionen. När du inte använder fältet RequiredVersion är det viktigt att övervaka versionsuppdateringar till den modul som krävs för att ange en specifik 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: Detta gör att en användare kan skicka ett e-postmeddelande till paketägaren. Som paketägare är det viktigt att övervaka e-postadressen som används med PowerShell-galleripaketen 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 det finns olämpligt beteende från någon av dessa kommunikationskanaler använder du funktionen Rapportmissbruk 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. 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 metodtips: 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. Det bästa sättet 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 en lista över den tillhörande 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 verkliga värden till andra användare. 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-galleripaket. Användarna föredrar paket som tillhandahåller detta, eftersom det gör att de enklare kan få information om paketet. 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 tillhandahålls 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 demonstrera 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 ditt paket med kompatibla plattformar inkluderas det i gallerisökningsfilter i den vänstra rutan i sökresultaten. Om du är värd för ditt paket på GitHub kan du också dra nytta av vårt exempel på kompatibilitetssköldar för PowerShell-galleriet kompatibilitetssköldar.

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 din kod fungerar. Det gör det också möjligt för användare att se till att de inte bryter dina ursprungliga funktioner om de ändrar din kod så att den passar deras miljö.

Vi rekommenderar starkt att tester skrivs för att dra nytta av Pester-testramverket, som har utformats specifikt för PowerShell. Pester är tillgängligt 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 resursmodulen av hög kvalitet, där testkodstäckning på 70% enheter rekommenderas.

Alla paket som publiceras till 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 ange 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 din kod

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 i allmänhet finns i Introduktion till kodsignering. PowerShell stöder validering av kodsignering via två primära metoder:

  • Signeringsskriptfiler
  • Katalogsignering av en modul

Att signera PowerShell-filer är en väletablerad metod för att säkerställa att koden som körs har skapats av en tillförlitlig källa och inte har ändrats. Information om hur du signerar PowerShell-skriptfiler finns 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 cmdletarna 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. Hur du signerar en modul beskrivs i artikeln Catalog Cmdlets . 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 signera filen.

PowerShellGetPublish-Module, Install-Moduleoch Update-Module cmdlets 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 kommer du att bekräfta att signeringsutfärdaren för den nya versionen matchar det som tidigare installerats. Install-Module och Update-Module kommer att använda signaturen på en .PSD1 fil om paketet inte är katalogsignerat. Katalogsignering fungerar med, men ersätter inte signeringsskriptfiler. PowerShell validerar inte katalogsignaturer vid modulens inläsningstid.

Följ SemVer-riktlinjerna för versionshantering

SemVer är en offentlig konvention som beskriver hur man strukturerar och ändrar en version för att möjliggöra enkel tolkning av ändringar. 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 numret bör bara börja med 0 om det är det enda numret som används.
  • Ändringar i det första talet (1.9.9999 till 2.0.0) anger större och icke-bakåtkompatibla ändringar mellan versionerna.
  • Ändringar av det andra numret (1.1 till 1.2) anger ändringar på funktionsnivå, till exempel att lägga till nya cmdlets 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 tillhandahållit en version 1.0.0. Detta kommer att stödjas i en framtida version av PowerShell-galleriet och PowerShellGet-cmdlets .
  • PowerShell och PowerShell-galleriet tillåter 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 4:e block med siffror (till exempel 5.1.14393.1066). Från versionssynpunkt ignoreras dessa skillnader.

Testa med en lokal lagringsplats

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

  • Konfigurera en lokal PowerShell Gallery 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 API-nyckel som krävs, 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 databas, som du använder i -Repository parametern för Publish-Module.

Ytterligare en punkt om testpublicering: alla paket som du publicerar i 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 hjälpa dig 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-cmdletarna i stället för Publish-Module. Det finns ett antal detaljer som lätt missas, vilket resulterar i en mängd olika supportbegäranden.

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

Den mest framgångsrika 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 koden på projektwebbplatsen och publicera sedan stabila uppdateringar i 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.