Dela via

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 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-galleripaket, 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.

Mer 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 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 riktlinjer 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 analysverktyg för statisk kod som fungerar med PowerShell-kod. PSScriptAnalyzer- identifierar de vanligaste problemen som visas i PowerShell-koden 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 i PowerShell-galleriet genomsöks med PSScriptAnalyzeroch 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 uppmanas 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 ett fel har 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 ge 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. Om du vill ha information om hur du skapar cmdlet-hjälp börjar du med Så här skriver du cmdlethjä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. Bästa praxis ä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 modulen PSDscResource 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 går också 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 ModuleVersionläses den senaste tillgängliga versionen in med minst den angivna versionen. När du inte använder fältet RequiredVersion är det viktigt att du övervakar 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: 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 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 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 när du taggar paketet också dra nytta av våra PowerShell-gallerikompatibilitetssköldarkompatibilitetsskö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 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 finns i GitHub, PowerShell-gallerietoch 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 med bästa praxis.

Målen för testtäckningen anges i dokumentationen resursmodul 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ändningsvillkor under Exhibit 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 Packages-manifestet och gallerigränssnittet.

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 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 beskrivs i artikeln Om signering. I översikten kan en signatur läggas till i alla .PS1 filer som PowerShell validerar när skriptet läses in. PowerShell kan begränsas med hjälp av Körningsprincip cmdletar för att säkerställa användning 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 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.

Cmdletarna PowerShellGetPublish-Module, Install-Moduleoch Update-Module kontrollerar signaturen för att säkerställa att den är giltig och bekräftar sedan att hashvärdet för varje paket matchar det som finns i katalogen. Save-Module validerar ingen signatur. Om en tidigare version av modulen är installerad i systemet bekräftar Install-Module att signeringsutfärdaren för den nya versionen matchar det som tidigare installerades. Install-Module och Update-Module använder 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 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) anger ä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 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 kommer att stödjas i en framtida version av PowerShell-galleriet och PowerShellGet-cmdletar.
  • 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 fjärde nummerblock (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-galleriinstans med hjälp av projektet privata PS-galleriet 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 test lagringsplats. 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 du Register-PSRepository 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 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 cmdletarna Publish-Module 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 i PowerShell-galleriet. Ibland har utgivare valt att hoppa över PowerShellGet- och använda NuGet-klienten eller PackageManagement cmdlets 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-Scriptkan du meddela oss. Ange ett problem i PowerShellGet- GitHub-lagringsplats 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.