Starkt rekommenderade riktlinjer för utveckling

Artikel
10/07/2021

I det här avsnittet beskrivs riktlinjer som du bör följa när du skriver dina cmdlets. De är indelade i riktlinjer för att utforma cmdlets och riktlinjer för att skriva din cmdlet-kod. Du kanske upptäcker att dessa riktlinjer inte gäller för alla scenarier. Men om de gäller och du inte följer dessa riktlinjer kan användarna få en dålig upplevelse när de använder dina cmdlets.

Designriktlinjer

Följande riktlinjer bör följas när du utformar cmdlets för att säkerställa en konsekvent användarupplevelse mellan att använda dina cmdlets och andra cmdlets. När du hittar en designriktlinjer som gäller för din situation bör du titta på riktlinjerna för Kod för liknande riktlinjer.

Använd ett specifikt substantiv för ett cmdlet-namn (SD01)

Substantiv som används i cmdlet-namngivning måste vara mycket specifika så att användaren kan identifiera dina cmdlets. Prefixet generiska substantiv som "server" med en förkortad version av produktnamnet. Om ett substantiv till exempel refererar till en server som kör en instans av Microsoft SQL Server använder du ett substantiv som "SQLServer". Kombinationen av specifika substantiv och den korta listan över godkända verb gör det möjligt för användaren att snabbt identifiera och förutse funktioner samtidigt som du undviker duplicering mellan cmdlet-namn.

För att förbättra användarupplevelsen bör substantivet som du väljer för ett cmdlet-namn vara singular. Använd till exempel namnet i Get-Process stället för Get-Processes . Det är bäst att följa den här regeln för alla cmdlet-namn, även om en cmdlet sannolikt kommer att agera på fler än ett objekt.

Använd Pascal-fall för cmdlet-namn (SD02)

Använd Pascal-case för parameternamn. Med andra ord versalerar du den första bokstaven i verbet och alla termer som används i substantivet. Exempel: "Clear-ItemProperty".

Riktlinjer för parameterdesign (SD03)

En cmdlet behöver parametrar som tar emot de data som den måste arbeta med, samt parametrar som anger information som används för att fastställa egenskaperna för åtgärden. En cmdlet kan till exempel ha en parameter som tar emot data från pipelinen, och cmdleten kan ha en parameter som indikerar att cmdleten kan tvingas Name Force att utföra åtgärden. Det finns ingen gräns för hur många parametrar som en cmdlet kan definiera.

Använd standardparameternamn

Din cmdlet bör använda standardparameternamn så att användaren snabbt kan avgöra vad en viss parameter innebär. Om ett mer specifikt namn krävs använder du ett standardparameternamn och anger sedan ett mer specifikt namn som alias. Get-ServiceCmdleten har till exempel en parameter som har ett allmänt namn ( Name ) och ett mer specifikt alias ( ServiceName ). Båda termerna kan användas för att ange parametern.

Mer information om parameternamn och deras datatyper finns i Cmdlet Parameter Name and Functionality Guidelines (Riktlinjer för cmdlet-parameternamn och funktioner).

Använda singular parameternamn

Undvik att använda pluralnamn för parametrar vars värde är ett enda element. Detta inkluderar parametrar som tar matriser eller listor eftersom användaren kan ange en matris eller lista med endast ett element.

Pluralparameternamn bör endast användas i de fall där värdet för parametern alltid är ett värde med flera element. I dessa fall bör cmdleten verifiera att flera element har angetts och cmdleten ska visa en varning för användaren om flera element inte anges.

Använda Pascal-case för parameternamn

Använd Pascal-case för parameternamn. Med andra ord, versalisera den första bokstaven i varje ord i parameternamnet, inklusive den första bokstaven i namnet. Parameternamnet använder till exempel ErrorAction rätt versaler. Följande parameternamn använder felaktig versalisering:

errorAction
erroraction

Parametrar som tar en lista med alternativ

Det finns två sätt att skapa en parameter vars värde kan väljas från en uppsättning alternativ.

Definiera en uppräkningstyp (eller använd en befintlig uppräkningstyp) som anger giltiga värden. Använd sedan uppräkningstypen för att skapa en parameter av den typen.
Lägg till attributet ValidateSet i parameterdeklarationen. Mer information om det här attributet finns i ValidateSet Attribute Declaration.

Använda standardtyper för parametrar

Använd standardtyper för parametrar där det är möjligt för att säkerställa konsekvens med andra cmdlets. Mer information om vilka typer som ska användas för olika parametrar finns i Parameternamn och typer för Standard-cmdlet. Det här avsnittet innehåller länkar till flera ämnen som beskriver namn och .NET Framework för grupper av standardparametrar, till exempel "aktivitetsparametrar".

Använda Strongly-Typed .NET Framework typer

Parametrar ska definieras som .NET Framework för att ge bättre parametervalidering. Till exempel ska parametrar som är begränsade till ett värde från en uppsättning värden definieras som en uppräkningstyp. För att stödja Uniform Resource Identifier (URI) definierar du parametern som en System.Uri-typ. Undvik grundläggande strängparametrar för alla egenskaper utom friformstext.

Använda konsekventa parametertyper

När samma parameter används av flera cmdlets ska du alltid använda samma parametertyp. Om parametern till exempel är en System.Int16-typ för en cmdlet ska du inte göra parametern för en annan Process cmdlet till en Process System.Uint16-typ.

Parametrar som tar true och false

Om parametern bara tar true och false definierar du parametern som typen System.Management.Automation.SwitchParameter. En switch-parameter behandlas som true när den anges i ett kommando. Om parametern inte ingår i ett kommando Windows PowerShell att värdet för parametern är false . Definiera inte booleska parametrar.

Om parametern behöver skilja mellan 3 värden: $true, $false och "ospecificerade" definierar du en parameter av typen <bool> Nullbar. Behovet av ett tredje, ospecificerat värde inträffar vanligtvis när cmdleten kan ändra en boolesk egenskap för ett objekt. I det här fallet innebär "ospecificerade" att egenskapens aktuella värde inte ändras.

Stödmatriser för parametrar

Ofta måste användarna utföra samma åtgärd mot flera argument. För dessa användare bör en cmdlet acceptera en matris som parameterindata så att en användare kan skicka argumenten till parametern som en Windows PowerShell variabel. Till exempel använder cmdleten Get-Process en matris för de strängar som identifierar namnen på de processer som ska hämtas.

Stöd för PassThru-parametern

Som standard fungerar många cmdlets som ändrar systemet, till exempel cmdleten Stop-Process, som "mottagare" för objekt och returnerar inget resultat. Dessa cmdlet bör implementera PassThru parametern för att tvinga cmdleten att returnera ett objekt. När parametern anges returnerar cmdleten ett -objekt med hjälp av ett anrop till metoden PassThru System.Management.Automation.Cmdlet.WriteObject. Följande kommando stoppar till exempel Calc-processen och skickar den resulterande processen till pipelinen.

Stop-Process calc -passthru

I de flesta fall bör cmdletarna Add, Set och New ha stöd för en PassThru parameter.

Stöd för parameteruppsättningar

En cmdlet är avsedd att uppnå ett enda syfte. Det finns dock ofta mer än ett sätt att beskriva åtgärden eller åtgärdsmålet. En process kan till exempel identifieras med dess namn, dess identifierare eller av ett processobjekt. Cmdleten bör ha stöd för alla rimliga representationer av dess mål. Normalt uppfyller cmdleten detta krav genom att ange uppsättningar med parametrar (kallas parameteruppsättningar) som fungerar tillsammans. En enda parameter kan tillhöra val av antal parameteruppsättningar. Mer information om parameteruppsättningar finns i Cmdlet Parameter Sets.

När du anger parameteruppsättningar anger du bara en parameter i uppsättningen till ValueFromPipeline. Mer information om hur du deklarerar parameterattributet finns i ParameterAttribute-deklaration.

När parameteruppsättningar används definieras standardparameteruppsättningen av attributet Cmdlet. Standardparameteruppsättningen bör innehålla de parametrar som troligen kommer att användas i en interaktiv Windows PowerShell session. Mer information om hur du deklarerar attributet Cmdlet finns i CmdletAttribute Declaration.

Ge feedback till användaren (SD04)

Använd riktlinjerna i det här avsnittet för att ge feedback till användaren. Den här feedbacken gör att användaren kan vara medveten om vad som händer i systemet och fatta bättre administrativa beslut.

Med Windows PowerShell kan en användare ange hur utdata ska hanteras från varje anrop till metoden Write genom att ange en inställningsvariabel. Användaren kan ange flera inställningsvariabler, inklusive en variabel som avgör om systemet ska visa information och en variabel som avgör om systemet ska fråga användaren innan ytterligare åtgärder vidtas.

Stöd för metoderna WriteWarning, WriteVerbose och WriteDebug

En cmdlet bör anropa metoden System.Management.Automation.Cmdlet.WriteWarning när cmdleten är på väg att utföra en åtgärd som kan ha ett oavsiktligt resultat. En cmdlet bör till exempel anropa den här metoden om cmdleten är på väg att skriva över en skrivskyddad fil.

En cmdlet bör anropa metoden System.Management.Automation.Cmdlet.WriteVerbose när användaren behöver mer information om vad cmdleten gör. En cmdlet bör till exempel anropa den här informationen om cmdlet-författaren anser att det finns scenarier som kan kräva mer information om vad cmdleten gör.

Cmdleten bör anropa metoden System.Management.Automation.Cmdlet.WriteDebug när en utvecklare eller produktsupporttekniker måste förstå vad som har skadat cmdlet-åtgärden. Det är inte nödvändigt för cmdleten att anropa metoden System.Management.Automation.Cmdlet.WriteDebug i samma kod som anropar metoden System.Management.Automation.Cmdlet.WriteVerbose eftersom parametern visar båda informationsuppsättningarna. Debug

Stöd för WriteProgress för åtgärder som tar lång tid

Cmdlet-åtgärder som tar lång tid att slutföra och som inte kan köras i bakgrunden bör ha stöd för förloppsrapportering via periodiska anrop till metoden System.Management.Automation.Cmdlet.WriteProgress.

Använda värdgränssnitten

Ibland måste en cmdlet kommunicera direkt med användaren i stället för med hjälp av de olika metoderna Write eller Should som stöds av klassen System.Management.Automation.Cmdlet. I det här fallet ska cmdleten härledas från klassen System.Management.Automation.PSCmdlet och använda egenskapen System.Management.Automation.PSCmdlet.Host*. Den här egenskapen stöder olika nivåer av kommunikationstyp, inklusive typerna PromptForChoice, Prompt och WriteLine/ReadLine. På den mest specifika nivån finns också sätt att läsa och skriva enskilda nycklar och hantera buffertar.

Såvida inte en cmdlet är särskilt utformad för att generera ett grafiskt användargränssnitt (GUI), bör den inte kringgå värden med hjälp av egenskapen System.Management.Automation.PSCmdlet.Host*. Ett exempel på en cmdlet som har utformats för att generera ett grafiskt användargränssnitt är out-GridView-cmdleten.

Anteckning

Cmdlets bör inte använda System.Console-API:et.

Skapa en cmdlet-hjälpfil (SD05)

För varje cmdlet-sammansättning skapar du Help.xml som innehåller information om cmdleten. Den här informationen innehåller en beskrivning av cmdleten, beskrivningar av cmdletens parametrar, exempel på cmdletens användning med mera.

Riktlinjer för kod

Följande riktlinjer bör följas när du kodar cmdlets för att säkerställa en konsekvent användarupplevelse mellan att använda dina cmdlets och andra cmdlets. När du hittar en kodriktlinjer som gäller för din situation bör du titta på riktlinjerna för design för liknande riktlinjer.

Kodningsparametrar (SC01)

Definiera en parameter genom att deklarera en offentlig egenskap för cmdlet-klassen som är prydad med attributet Parameter. Parametrar behöver inte vara statiska medlemmar i den härledda .NET Framework för cmdleten. Mer information om hur du deklarerar parameterattributet finns i Deklaration av parameterattribut.

Stöd för Windows PowerShell sökvägar

Den Windows PowerShell sökvägen är mekanismen för att normalisera åtkomsten till namnområden. När du tilldelar Windows PowerShell sökväg till en parameter i cmdleten kan användaren definiera en anpassad "enhet" som fungerar som en genväg till en specifik sökväg. När en användare anger en sådan enhet kan lagrade data, till exempel data i registret, användas på ett konsekvent sätt.

Om cmdleten tillåter att användaren anger en fil eller en datakälla ska den definiera en parameter av typen System.String. Om mer än en enhet stöds ska typen vara en matris. Namnet på parametern ska vara Path , med PSPath aliaset . Dessutom bör Path parametern ha stöd för jokertecken. Om stöd för jokertecken inte krävs definierar du en LiteralPath parameter.

Om de data som cmdleten läser eller skriver måste vara en fil ska cmdleten acceptera indata för Windows PowerShell-sökvägen och cmdleten ska använda egenskapen System.Management.Automation.Sessionstate.Path för att översätta Windows PowerShell-sökvägarna till sökvägar som filsystemet känner igen. De specifika mekanismerna omfattar följande metoder:

Om de data som cmdleten läser eller skriver bara är en uppsättning strängar i stället för en fil, bör cmdleten använda providerns innehållsinformation (medlem) för att läsa Content och skriva. Den här informationen hämtas från egenskapen System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Dessa mekanismer gör att andra datalager kan delta i läsning och skrivning av data.

Stöd för jokertecken

En cmdlet ska ha stöd för jokertecken om det är möjligt. Stöd för jokertecken finns på många platser i en cmdlet (särskilt när en parameter tar en sträng för att identifiera ett objekt från en uppsättning objekt). Stop-ProcExempel-cmdleten från StopProc Tutorial definierar till exempel en Name parameter för att hantera strängar som representerar processnamn. Den här parametern stöder jokertecken så att användaren enkelt kan ange vilka processer som ska stoppas.

När det finns stöd för jokertecken skapar en cmdlet-åtgärd vanligtvis en matris. Ibland är det inte meningsfullt att stödja en matris eftersom användaren kanske bara använder ett enskilt objekt i taget. Till exempel behöver cmdleten Set-Location inte ha stöd för en matris eftersom användaren bara anger en enda plats. I det här fallet stöder cmdleten fortfarande jokertecken, men den tvingar upplösning till en enda plats.

Mer information om jokerteckenmönster finns i Stöd för jokertecken i cmdletparametrar.

Definiera objekt

Det här avsnittet innehåller riktlinjer för att definiera objekt för cmdlets och för att utöka befintliga objekt.

Definiera standardmedlemmar

Definiera standardmedlemmar för att utöka en objekttyp i en anpassad Types.ps1xml-fil (använd filen Windows PowerShell Types.ps1xml som mall). Standardmedlemmar definieras av en nod med namnet PSStandardMembers. Dessa definitioner tillåter att andra cmdlets och Windows PowerShell-körningen fungerar med ditt -objekt på ett konsekvent sätt.

Definiera ObjectMembers som ska användas som parametrar

Om du utformar ett objekt för en cmdlet ska du se till att dess medlemmar mappar direkt till parametrarna för de cmdlets som ska använda den. Den här mappningen gör att objektet enkelt kan skickas till pipelinen och skickas från en cmdlet till en annan.

Redan .NET Framework objekt som returneras av cmdlets saknar ofta några viktiga eller praktiska medlemmar som krävs av skriptutvecklaren eller användaren. Dessa saknade medlemmar kan vara särskilt viktiga för visning och för att skapa rätt medlemsnamn så att objektet kan skickas korrekt till pipelinen. Skapa en anpassad Types.ps1xml-fil för att dokumentera dessa obligatoriska medlemmar. När du skapar den här filen rekommenderar vi följande namngivningskonvention: <Your_Product_Name>. Types.ps1xml.

Du kan till exempel lägga till en skriptegenskap till typen Mode System.IO.FileInfo för att visa attributen för en fil tydligare. Dessutom kan du lägga till en aliasegenskap till typen System.Array för att tillåta konsekvent användning Count av egenskapsnamnet (i stället för Length ).

Implementera IComparable-gränssnittet

Implementera ett System.IComparable-gränssnitt för alla utdataobjekt. På så sätt kan utdataobjekt enkelt ledas till olika cmdlets för sortering och analys.

Uppdatera visningsinformation

Om visningen för ett objekt inte ger det förväntade resultatet skapar du en anpassad <YourProductName> . Format.ps1xml-fil för objektet.

Stöd för väldefinierade pipelineindata (SC02)

Implementera för mitten av en pipeline

Implementera en cmdlet som förutsätter att den anropas från mitten av en pipeline (det vill säga att andra cmdlet:ar producerar dess indata eller använder dess utdata). Du kan till exempel anta att cmdleten, eftersom den genererar data, endast används som den Get-Process första cmdleten i en pipeline. Men eftersom denna cmdlet är utformad för mitten av en pipeline, tillåter denna cmdlet att tidigare cmdlets eller data i pipelinen anger vilka processer som ska hämtas.

Stöd för indata från pipelinen

Inkludera minst en parameter som stöder indata från pipelinen i varje parameteruppsättning för en cmdlet. Med stöd för pipelineindata kan användaren hämta data eller objekt, skicka dem till rätt parameteruppsättning och skicka resultaten direkt till en cmdlet.

En parameter tar emot indata från pipelinen om attributet Parameter innehåller nyckelordet, nyckelordsattributet ValueFromPipeline eller båda ValueFromPipelineByPropertyName nyckelorden i deklarationen. Om ingen av parametrarna i en parameteruppsättning stöder nyckelorden eller kan cmdleten inte placeras på ett meningsfullt sätt efter en annan cmdlet eftersom den ignorerar ValueFromPipeline ValueFromPipelineByPropertyName alla pipelineindata.

Stöd för ProcessRecord-metoden

Om du vill acceptera alla poster från föregående cmdlet i pipelinen måste cmdleten implementera metoden System.Management.Automation.Cmdlet.ProcessRecord. Windows PowerShell anropar den här metoden flera gånger, en gång för varje post som skickas till din cmdlet.

Skriva enskilda poster till pipelinen (SC03)

När en cmdlet returnerar objekt ska cmdleten skriva objekten direkt när de genereras. Cmdleten bör inte innehålla dem för att buffra dem i en kombinerad matris. De cmdlets som tar emot objekten som indata kommer sedan att kunna bearbeta, visa eller bearbeta och visa utdataobjekten utan fördröjning. En cmdlet som genererar utdataobjekt ett i taget bör anropa metoden System.Management.Automation.Cmdlet.WriteObject. En cmdlet som genererar utdataobjekt i batchar (till exempel eftersom ett underliggande API returnerar en matris med utdataobjekt) bör anropa metoden System.Management.Automation.Cmdlet.WriteObject med den andra parametern inställd på true .

Skapa cmdlets Case-Insensitive och Case-Preserving (SC04)

Som standard Windows PowerShell sig själv inte är icke-känslig. Men eftersom den hanterar många befintliga system, Windows PowerShell bevarar det här fallet för enkel drift och kompatibilitet. Om ett tecken med andra ord anges med versaler behåller Windows PowerShell det med versaler. För att system ska fungera bra måste en cmdlet följa den här konventionen. Om möjligt bör den fungera på ett icke-icke-känsligt sätt. Det bör dock bevara det ursprungliga fallet för cmdlets som inträffar senare i ett kommando eller i pipelinen.

Se även

Obligatoriska riktlinjer för utveckling

Rekommenderade riktlinjer för utveckling

Skriva en Windows PowerShell-cmdlet