Starkt rekommenderade riktlinjer för utveckling

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

Designriktlinjer

Följande rikt linjer bör följas när du utformar cmdlets för att säkerställa en konsekvent användar upplevelse mellan att använda dina cmdletar och andra cmdletar. När du hittar en design rikt linje som gäller din situation bör du titta närmare på kod rikt linjerna för liknande rikt linjer.

Använd ett angivet Substantiv för ett cmdlet-namn (SD01)

Substantiv som används i cmdlet-namn måste vara särskilt så att användaren kan identifiera dina cmdletar. Prefix för generiska substantiv som "Server" med en förkortad version av produkt namnet. Om t. ex. ett substantiv refererar till en server som kör en instans av Microsoft SQL Server, använder du ett substantiv som "SQLServer". Kombinationen av vissa Substantiv och den korta listan över godkända verb gör det möjligt för användaren att snabbt upptäcka och förutse funktioner samtidigt som du undviker duplicering mellan cmdlet-namn.

För att förbättra användar upplevelsen ska 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-processs. Det är bäst att följa den här regeln för alla cmdlet-namn, även om en cmdlet förmodligen fungerar på mer än ett objekt.

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

Använd Pascal-fall för parameter namn. Med andra ord skriver du in den första bokstaven i verbet och alla termer som används i substantivet. Exempel: "Clear-ItemProperty".

Rikt linjer för parameter design (SD03)

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

Använd standard parameter namn

Din cmdlet ska använda standard parameter namn så att användaren snabbt kan fastställa vad en viss parameter innebär. Om ett mer särskilt namn krävs, Använd ett standard parameter namn och ange sedan ett mer särskilt namn som alias. Till exempel Get-Service har cmdleten en parameter som har ett generiskt namn ( Name ) och ett mer särskilt alias ( ServiceName ). Båda villkoren kan användas för att ange parametern.

Mer information om parameter namn och deras data typer finns i rikt linjer för cmdlet-parameter namn och funktioner.

Använd singular parameter namn

Undvik att använda plural-namn 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.

Plural-parameter namn ska endast användas i de fall där parameterns värde alltid är ett värde för flera element. I dessa fall bör cmdleten verifiera att flera element anges och cmdleten ska visa en varning till användaren om flera element inte anges.

Använd Pascal-fall för parameter namn

Använd Pascal-fall för parameter namn. Med andra ord skriver du in den första bokstaven i varje ord i parameter namnet, inklusive den första bokstaven i namnet. Parameter namnet använder till exempel ErrorAction rätt Skift läge. Följande parameter namn använder felaktig kapitalisering:

  • 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äknings typ (eller Använd en befintlig uppräknings typ) som anger giltiga värden. Använd sedan uppräknings typen för att skapa en parameter av den typen.

  • Lägg till attributet ValidateSet i parameter deklarationen. Mer information om det här attributet finns i ValidateSet Attribute-deklaration.

Använd standard typer för parametrar

Använd standard typer för parametrar där det är möjligt för att säkerställa konsekvens med andra cmdletar. Mer information om vilka typer som ska användas för olika parametrar finns i standard parameter namn och typer. Det här avsnittet innehåller länkar till flera avsnitt som beskriver namn och .NET Framework typer för grupper med standard parametrar, t. ex. "aktivitets parametrar".

Använd Strongly-Typed .NET Framework typer

Parametrar ska definieras som .NET Framework typer för att ge bättre parameter validering. Till exempel ska parametrar som är begränsade till ett värde från en uppsättning värden definieras som en uppräknings typ. För att stödja ett Uniform Resource Identifier (URI)-värde definierar du parametern som en system. URI -typ. Undvik grundläggande sträng parametrar för alla fält med fri Forms egenskaper.

Använd konsekventa parameter typer

Använd alltid samma parameter typ när samma parameter används av flera cmdletar. Om parametern till exempel Process är en system. Int16 -typ för en cmdlet ska du inte göra Process parametern för en annan cmdlet: en system. Uint16 -typ.

Parametrar som tar sant och falskt

Om parametern bara tar true och false definierar du parametern som Type system. Management. Automation. SwitchParameter. En växel parameter behandlas som true när den anges i ett kommando. Om parametern inte ingår i ett kommando, anses värdet för parametern vara i Windows PowerShell false . Definiera inte booleska parametrar.

Om parametern behöver särskilja mellan tre värden: $true, $false och "ospecificerad", definierar du en parameter av typen Nullable <bool> . Behovet av ett tredje, "Ospecificerat" värde inträffar vanligt vis när cmdleten kan ändra en Boolean-egenskap för ett objekt. I det här fallet "Ospecificerat" innebär att egenskapens aktuella värde inte ändras.

Stöd mat ris för parametrar

Användare måste ofta utföra samma åtgärd mot flera argument. För dessa användare ska en cmdlet acceptera en matris som parameter indata 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 strängarna som identifierar namnen på de processer som ska hämtas.

Stöd för parametern PassThru

Som standard fungerar många cmdlets som ändrar systemet, till exempel cmdleten Stop process , som "Sinks" för objekt och returnerar inte ett resultat. Denna cmdlet ska implementera PassThru parametern för att tvinga cmdleten att returnera ett objekt. När PassThru parametern anges returnerar cmdleten ett objekt genom att använda ett anrop till metoden system. Management. Automation. cmdlet. WriteObject . Följande kommando stoppar till exempel processen Calc och skickar den resulterande processen till pipelinen.

Stop-Process calc -passthru

I de flesta fall ska Lägg till, ange och nya cmdletar ha stöd för en PassThru parameter.

Stöd parameter uppsä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ärds målet. En process kan till exempel identifieras med sitt namn, med dess identifierare eller av ett process objekt. Cmdleten ska ha stöd för alla rimliga representationer av sina mål. Normalt uppfyller cmdleten detta krav genom att ange uppsättningar med parametrar (kallas parameter uppsättningar) som fungerar tillsammans. En enskild parameter kan tillhöra valfritt antal parameter uppsättningar. Mer information om parameter uppsättningar finns i cmdlet parameter Sets.

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

När parameter uppsättningar används definieras standard parameter uppsättningen av cmdlet -attributet. Standard parameter uppsättningen bör innehålla de parametrar som troligen används i en interaktiv Windows PowerShell-session. Mer information om hur du deklarerar cmdlet -attributet finns i CmdletAttribute-deklaration.

Ge feedback till användaren (SD04)

Använd rikt linjerna 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 runtime kan en användare ange hur utdata ska hanteras från varje anrop till- Write metoden genom att ange en inställnings variabel. Användaren kan ange flera variabler, 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. Till exempel ska en cmdlet anropa den här metoden om cmdleten är på väg att skriva över en skrivskyddad fil.

En cmdlet ska anropa metoden system. Management. Automation. cmdlet. WriteVerbose när användaren behöver information om vad cmdleten gör. Till exempel ska en-cmdlet 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 ska anropa metoden system. Management. Automation. cmdlet. WriteDebug när en utvecklare eller en produkt support tekniker 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 Debug parametern visar båda uppsättningarna med information.

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örlopps rapportering via periodiska anrop till metoden system. Management. Automation. cmdlet. WriteProgress .

Använd värd gränssnitten

Ibland måste en cmdlet kommunicera direkt med användaren i stället för genom att använda de olika Skriv-eller-metoderna 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 kommunikations typer, inklusive typerna PromptForChoice, prompt och WriteLine/ReadLine. På den mest specifika nivån ger det också olika sätt att läsa och skriva enskilda nycklar och att hantera buffertar.

Såvida inte en cmdlet är särskilt utformad för att generera ett grafiskt användar grä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 är utformad för att generera ett grafiskt användar gränssnitt är cmdleten out-GridView .

Anteckning

Cmdletar ska inte använda system. Console -API: et.

Skapa en hjälp fil för cmdlet (SD05)

Skapa en Help.xml-fil som innehåller information om cmdleten för varje cmdlet-sammansättning. Den här informationen innehåller en beskrivning av cmdleten, beskrivningar av cmdletens parametrar, exempel på cmdlet: en, med mera.

Kod rikt linjer

Följande rikt linjer bör följas när du kodar cmdletar för att säkerställa en konsekvent användar upplevelse mellan att använda dina cmdletar och andra cmdletar. När du hittar en kod rikt linje som gäller för din situation bör du läsa rikt linjerna för utformning av liknande rikt linjer.

Kodnings parametrar (SC01)

Definiera en parameter genom att deklarera en offentlig egenskap för cmdlet-klassen som är dekorerad med attributet parameter . Parametrarna behöver inte vara statiska medlemmar i den härledda .NET Frameworks klassen för cmdleten. Mer information om hur du deklarerar attributet parameter finns i deklaration av parameter attribut.

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

Windows PowerShell-sökvägen är mekanismen för att normalisera åtkomst till namn områden. När du tilldelar en 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 angiven 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 gör det möjligt för användaren att ange en fil eller en data källa, bör den definiera en parameter av typen system. String. Om mer än en enhet stöds måste typen vara en matris. Namnet på parametern ska vara Path , med ett alias för PSPath . Dessutom Path ska parametern ha stöd för jokertecken. Om det inte krävs stöd för jokertecken definierar du en LiteralPath parameter.

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

Om data som-cmdlet: en läser eller skriver bara är en uppsättning strängar i stället för en fil, ska cmdleten använda providerns innehålls information ( 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 metoder gör det möjligt för andra data lager att delta i läsning och skrivning av data.

Stöd för jokertecken

En cmdlet måste ha stöd för jokertecken om det är möjligt. Stöd för jokertecken förekommer 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: Stop-proc- cmdleten från StopProc- självstudien definierar till exempel en Name parameter för att hantera strängar som representerar process namn. 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 vanligt vis en matris. Ibland är det inte meningsfullt att stödja en matris eftersom användaren bara kan använda ett enda objekt i taget. Till exempel behöver cmdleten set-location inte stöd för en matris eftersom användaren bara anger en enda plats. I den här instansen stöder cmdlet: en fortfarande jokertecken, men den framtvingar matchning till en enda plats.

Mer information om mönster med jokertecken finns i stödjande jokertecken i cmdlet-parametrar.

Definiera objekt

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

Definiera standard medlemmar

Definiera standard medlemmar för att utöka en objekt typ i en anpassad Types.ps1XML-fil (Använd Windows PowerShell-Types.ps1XML-fil som mall). Standard medlemmar definieras av en nod med namnet PSStandardMembers. Dessa definitioner gör det möjligt för andra cmdletar och Windows PowerShell-körningsmiljön att arbeta med ditt objekt på ett konsekvent sätt.

Definiera ObjectMembers som ska användas som parametrar

Om du skapar ett objekt för en cmdlet bör du se till att dess medlemmar mappar direkt till parametrarna för de cmdletar som ska använda den. 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 cmdlets ofta saknar vissa viktiga eller praktiska medlemmar som krävs av skript utvecklaren eller användaren. De medlemmar som saknas kan vara särskilt viktiga för att visa och för att skapa rätt medlems namn 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 namngivnings konvention: <Your_Product_Name>.Types.ps1XML.

Du kan till exempel lägga till en Mode skript egenskap i typen system. io. fileinfo för att visa attributen för en fil tydligare. Dessutom kan du lägga till en Count aliasresurspost till system. mat ris typen för att tillåta konsekvent användning av egenskaps namnet (i stället för Length ).

Implementera IComparable-gränssnittet

Implementera ett system. IComparable -gränssnitt på alla utgående objekt. Detta gör att utmatnings objekt enkelt kan skickas till olika sorterings-och analys-cmdletar.

Uppdatera visnings information

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

Support bra definierade pipeline-inmatare (SC02)

Implementera mitt i en pipeline

Implementera en cmdlet förutsatt att den kommer att anropas från mitten av en pipeline (det vill säga andra cmdlets skapar indata eller förbrukar utdata). Du kan till exempel anta att Get-Process cmdleten, eftersom den genererar data, endast används som första cmdlet i en pipeline. Men eftersom den här cmdleten är avsedd för mitten av en pipeline, tillåter den här cmdleten tidigare cmdletar eller data i pipelinen att ange vilka processer som ska hämtas.

Stöd för ininformation från pipelinen

I varje parameter uppsättning för en cmdlet inkluderar du minst en parameter som stöder indatamängden från pipelinen. Stöd för pipeline-indata gör att användaren kan hämta data eller objekt, skicka dem till rätt parameter uppsättning och skicka resultaten direkt till en-cmdlet.

En parameter accepterar ininformation från pipelinen om attributet parameter innehåller ValueFromPipeline nyckelordet, ValueFromPipelineByPropertyName nyckelordet eller båda nyckelorden i dess deklaration. Om ingen av parametrarna i en parameter uppsättning har stöd för ValueFromPipeline eller ValueFromPipelineByPropertyName , kan cmdleten inte meningsfullt placeras efter en annan cmdlet eftersom den ignorerar alla pipeline-inflöden.

Stöd för metoden ProcessRecord

Om du vill acceptera alla poster från föregående cmdlet i pipelinen måste din cmdlet 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.

Skriv 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 cmdletar som tar emot objekten som indata kommer sedan att kunna bearbeta, Visa eller bearbeta och visa utdata utan fördröjning. En cmdlet som genererar utdata en i taget bör anropa metoden system. Management. Automation. cmdlet. WriteObject . En cmdlet som genererar utdata i batchar (till exempel eftersom ett underliggande API returnerar en matris med utgående objekt) bör anropa metoden system. Management. Automation. cmdlet. WriteObject med dess andra parameter inställd på true .

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

Som standard är Windows PowerShell inte Skift läges känsligt. Men eftersom det behandlar flera befintliga system, bevarar Windows PowerShell Skift läge för enkel drift och kompatibilitet. Om ett tecken i versaler anges med versaler, så behåller Windows PowerShell det med versala bokstäver. För att system ska fungera bra måste en cmdlet följa denna konvention. Om möjligt bör det köras på ett skift läges okänsligt sätt. Det bör dock behålla det ursprungliga fallet för cmdletar som sker senare i ett kommando eller i pipelinen.

Se även

Obligatoriska riktlinjer för utveckling

Rekommenderade riktlinjer för utveckling

Skriva en Windows PowerShell-cmdlet