Starkt rekommenderade riktlinjer för utveckling

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

Designriktlinjer

Följande riktlinjer bör följas när du utformar cmdletar för att säkerställa en konsekvent användarupplevelse mellan att använda dina cmdletar och andra cmdletar. När du hittar en designguide 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 cmdletnamn (SD01)

Substantiv som används i cmdlet-namngivning måste vara mycket specifika så att användaren kan identifiera dina cmdletar. Förse 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 det substantiv som du väljer för ett cmdlet-namn vara singular. Använd till exempel namnet Get-Process i 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 Pascalskift för Cmdlet-namn (SD02)

Använd Pascal-fall för parameternamn. Med andra ord, versalera den första bokstaven i verbet och alla termer som används i substantiv. Exempel: "Clear-ItemProperty".

Riktlinjer för parameterdesign (SD03)

En cmdlet behöver parametrar som tar emot de data som den måste använda och parametrar som anger information som används för att fastställa åtgärdens egenskaper. En cmdlet kan till exempel ha en Name parameter som tar emot data från pipelinen, och cmdleten kan ha en Force parameter som anger att cmdleten kan tvingas utföra sin åtgärd. Det finns ingen gräns för antalet parametrar som en cmdlet kan definiera.

Använda 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 ett alias. Cmdleten Get-Service 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-parameternamn och riktlinjer för funktioner.

Använd singulara 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 kontrollera att flera element har angetts, och cmdleten bör visa en varning för användaren om flera element inte tillhandahålls.

Använd Pascal Case för parameternamn

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

• 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-attributdeklaration.

Använda standardtyper för parametrar

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

Använda Strongly-Typed .NET Framework-typer

Parametrar bör definieras som .NET Framework-typer för att ge bättre parameterverifiering. Parametrar som är begränsade till ett värde från en uppsättning värden bör till exempel definieras som en uppräkningstyp. Om du vill ha stöd för ett URI-värde (Uniform Resource Identifier) definierar du parametern som en System.Uri-typ . Undvik grundläggande strängparametrar för alla utom textegenskaper i fritt format.

Använda konsekventa parametertyper

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

Parametrar som tar sant och falskt

Om din parameter endast tar true och false, definiera parametern som typen System.Management.Automation.SwitchParameter. En växelparameter behandlas som true när den anges i ett kommando. Om parametern inte ingår i ett kommando anser Windows PowerShell att värdet för parametern är false. Definiera inte booleska parametrar.

Om parametern behöver skilja mellan tre värden: $true, $false och "ospecificerad" definierar du en parameter av typen Nullable<bool>. Behovet av ett tredje, "ospecificerat" värde uppstår vanligtvis när cmdlet kan ändra en boolesk egenskap hos ett objekt. I det här fallet innebär "ospecificerad" att egenskapens nuvarande värde inte ändras.

Stödmatriser för parametrar

Användare måste ofta 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. Get-Process-cmdleten använder till exempel 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 cmdletar som ändrar systemet, till exempel cmdleten Stop-Process , som "mottagare" för objekt och returnerar inte något resultat. Dessa cmdletar bör implementera parametern PassThru för att tvinga cmdleten att returnera ett objekt. När parametern PassThru har angetts returnerar cmdleten ett objekt med hjälp av ett anrop till metoden System.Management.Automation.Cmdlet.WriteObject . Följande kommando stoppar till exempel Calc (CalculatorApp.exe) och skickar den resulterande processen till pipelinen.

Stop-Process -Name CalculatorApp -PassThru

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

Stödparameteruppsättningar

En cmdlet är avsedd att utföra 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 stödja alla rimliga sätt att representera sina mål. Normalt uppfyller cmdleten det här kravet genom att ange uppsättningar med parametrar (kallas parameteruppsättningar) som fungerar tillsammans. En enskild parameter kan tillhöra valfritt antal parameteruppsättningar. Mer information om parameteruppsättningar finns i Cmdlet-parameteruppsättningar.

När du anger parameteruppsättningar anger du endast 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 cmdlet-attributet . Standardparameteruppsättningen bör innehålla de parametrar som mest sannolikt kommer att användas i en interaktiv Windows PowerShell-session. Mer information om hur du deklarerar cmdlet-attributet finns i CmdletAttribute-deklarationen.

Ge feedback till användaren (SD04)

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

Windows PowerShell-körtiden gör att en användare kan specificera hur utdata från varje anrop till Write-metoden ska hanteras 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 ska 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 håller på att skriva över en skrivskyddad fil.

En cmdlet ska anropa metoden System.Management.Automation.Cmdlet.WriteVerbose när användaren behöver lite 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 att cmdleten anropar metoden System.Management.Automation.Cmdlet.WriteDebug i samma kod som anropar metoden System.Management.Automation.Cmdlet.WriteVerbose eftersom parametern Debug presenterar båda informationsuppsättningarna.

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 "Write" eller "Should"-metoderna som stöds av klassen System.Management.Automation.Cmdlet. I det här fallet bör 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 det också sätt att läsa och skriva enskilda nycklar och hantera buffertar.

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

Skapa en cmdlet-hjälpfil (SD05)

För varje cmdlet-sammansättning skapar du en Help.xml fil 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.

Kodriktlinjer

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

Kodningsparametrar (SC01)

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

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

Windows PowerShell-sökvägen är mekanismen för normalisering av åtkomst till namnområden. När du tilldelar en Windows PowerShell-sökväg till en parameter i cmdlet 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 din cmdlet tillåter att användaren anger en fil eller en datakälla bör den definiera en parameter av typen System.String. Om fler än en enhet stöds ska typen vara en matris. Namnet på parametern ska vara Path, med aliaset PSPath. Dessutom bör parametern Path 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 bör 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:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

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 providerinnehållsinformationen (Content medlem) för att läsa och skriva. Den här informationen hämtas från egenskapen System.Management.Automation.Provider.CmdletProvider.InvokeProvider . Dessa mekanismer gör det möjligt för andra datalager att delta i läsning och skrivning av data.

Stöd för jokertecken

En cmdlet bör ha stöd för jokertecken om 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). Exempel-cmdleten Stop-Proc från StopProc-självstudien 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 stöd för jokertecken är tillgängligt 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. Cmdleten Set-Location behöver till exempel inte ha stöd för en matris eftersom användaren endast anger en enda plats. I det här fallet stöder cmdleten fortfarande jokertecken, men den tvingar fram en lösning till en enda plats.

Mer information om mönster med jokertecken finns i Stöd för jokertecken i Cmdlet-parametrar.

Definiera objekt

Det här avsnittet innehåller riktlinjer för att definiera objekt för cmdletar 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 Windows PowerShell Types.ps1xml-filen som mall). Standardmedlemmar definieras av en nod med namnet PSStandardMembers. Med dessa definitioner kan andra cmdletar och Windows PowerShell-körningen fungera med objektet på ett konsekvent sätt.

Definiera ObjectMembers som ska användas som parametrar

Om du utformar ett objekt för en cmdlet kontrollerar du att dess medlemmar mappas direkt till parametrarna för de cmdletar som ska använda det. Med den här mappningen kan objektet enkelt skickas till pipelinen och skickas från en cmdlet till en annan.

Befintliga .NET Framework-objekt som returneras av cmdletar saknar ofta några viktiga eller praktiska medlemmar som krävs av skriptutvecklaren eller användaren. Dessa medlemmar som saknas 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 de nödvändiga medlemmarna. 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 Mode skriptegenskap i typen System.IO.FileInfo för att visa attributen för en fil tydligare. Dessutom kan du lägga till en Count aliasegenskap i typen System.Array för att tillåta konsekvent användning av egenskapsnamnet Length(i stället för ).

Implementera IComparable-gränssnittet

Implementera ett System.IComparable-gränssnitt på alla utdataobjekt. På så sätt kan utdataobjekten enkelt skickas till olika sorterings- och analys-cmdletar.

Uppdatera visningsinformation

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

Stöd för väl definierade pipeline-indata (SC02)

Implementera i mitten av en pipeline

Implementera en cmdlet förutsatt att den anropas från mitten av en pipeline (dvs. andra cmdletar kommer att producera sina indata eller förbruka dess utdata). Du kan till exempel anta att cmdleten Get-Process eftersom den genererar data, endast kan användas som den första cmdleten i en pipeline. Men eftersom denna cmdlet är utformad för mitten av en pipeline tillåter den här cmdleten att tidigare cmdletar eller data i pipelinen anger vilka processer som ska hämtas.

Stöd för indata från pipelinen

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

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

Stöd för Metoden ProcessRecord

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 datapost som skickas till din cmdlet.

Skriva enskilda poster till pipelinen (SC03)

När en cmdlet returnerar objekt bör cmdleten skriva objekten direkt när de genereras. Cmdleten ska inte behålla dem för att buffra dem till en kombinerad matris. De cmdletar som tar emot objekten som indata kan sedan bearbeta, visa eller bearbeta och visa utdataobjekten utan fördröjning. En cmdlet som genererar utdataobjekt en i taget ska 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) ska anropa metoden System.Management.Automation.Cmdlet.WriteObject med den andra parametern inställd på true.

Gör cmdletar Case-Insensitive och Case-Preserving (SC04)

Som standard är själva Windows PowerShell inte skiftlägeskänsligt. Men eftersom det hanterar många befintliga system bevarar Windows PowerShell skiftläge för enkel användning och kompatibilitet. Med andra ord, om ett tecken 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 skiftlägesokänsligt sätt. Det bör dock bevara det ursprungliga fallet för cmdletar som inträffar senare i ett kommando eller i pipelinen.

Se även

nödvändiga riktlinjer för utveckling

riktlinjer för rådgivande utveckling

Skriva en Windows PowerShell-cmdlet