Obligatoriska riktlinjer för utveckling
Följande riktlinjer måste följas 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. Om du inte följer dessa riktlinjer kan cmdletarna misslyckas och användarna kan få en dålig upplevelse när de använder dina cmdlets.
I det här avsnittet
Designriktlinjer
Riktlinjer för kod
Designriktlinjer
Följande riktlinjer måste 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 endast godkända verb (RD01)
Verbet som anges i attributet Cmdlet måste komma från den identifierade uppsättningen verb som tillhandahålls av Windows PowerShell. Det får inte vara en av de förbjudna synonymerna. Använd de konstanta strängar som definieras av följande uppräkningar för att ange cmdlet-verb:
Mer information om godkända verbnamn finns i Cmdlet Verbs.
Användarna behöver en uppsättning identifieringsbara och förväntade cmdlet-namn. Använd lämpligt verb så att användaren snabbt kan bedöma vad en cmdlet gör och för att enkelt identifiera systemets funktioner. Följande kommandoradskommando hämtar till exempel en lista över alla kommandon i systemet vars namn börjar med "start": get-command start-* . Använd substantiven i dina cmdlets för att skilja dina cmdlets från andra cmdlets. Substantivet anger resursen som åtgärden ska utföras på. Själva åtgärden representeras av verbet .
Cmdlet-namn: Tecken som inte kan användas (RD02)
När du namn-cmdlets ska du inte använda något av följande specialtecken.
| Tecken | Name |
|---|---|
| # | nummertecken |
| , | Komma |
| () | Parenteser |
| {} | Hängslen |
| [] | Parentes |
| & | Ampersand |
| - | bindestreck Obs! Bindestreck kan användas för att separera verbet från substantivet, men det kan inte användas inom substantivet eller i verbet. |
| / | snedstreck |
| \ | omsnedstreck |
| $ | dollartecken |
| ^ | cirkumflex |
| ; | Semikolon |
| : | Kolon |
| " | dubbelt citattecken |
| ' | enkelt citattecken |
| <> | Vinkelparenteser |
| | | lodrätt fält |
| ? | frågetecken |
| @ | vid inloggning |
| ` | back tick (accent accent) |
| * | asterisk |
| % | procenttecken |
| + | Plustecknet |
| = | likhetstecken |
| ~ | Tilde |
Parameternamn som inte kan användas (RD03)
Windows PowerShell en gemensam uppsättning parametrar för alla cmdlets plus ytterligare parametrar som läggs till i specifika situationer. När du skapar egna cmdlets kan du inte använda följande namn: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction och Verbose. Mer information om dessa parametrar finns i Vanliga parameternamn.
Supportbekräftelsebegäranden (RD04)
För cmdlets som utför en åtgärd som ändrar systemet bör de anropa metoden System.Management.Automation.Cmdlet.ShouldProcess* för att begära bekräftelse och i särskilda fall anropa metoden System.Management.Automation.Cmdlet.ShouldContinue*. (Metoden System.Management.Automation.Cmdlet.ShouldContinue* bör endast anropas efter att metoden System.Management.Automation.Cmdlet.ShouldProcess* har anropats.)
För att göra dessa anrop måste cmdleten ange att den stöder bekräftelsebegäranden genom att ange SupportsShouldProcess nyckelordet för attributet Cmdlet. Mer information om hur du anger det här attributet finns i Cmdlet Attribute Declaration.
Anteckning
Om cmdlet-attributet för cmdlet-klassen anger att cmdleten stöder anrop till metoden System.Management.Automation.Cmdlet.ShouldProcess* och cmdleten inte kan göra anropet till metoden System.Management.Automation.Cmdlet.ShouldProcess* kan användaren ändra systemet oväntat.
Använd metoden System.Management.Automation.Cmdlet.ShouldProcess* för eventuella systemändringar. En användarpreferens och WhatIf parametern styr metoden System.Management.Automation.Cmdlet.ShouldProcess*. Däremot utför anropet System.Management.Automation.Cmdlet.ShouldContinue* ytterligare en kontroll av potentiellt farliga ändringar. Den här metoden styrs inte av användarpreferenser eller WhatIf parametern . Om cmdleten anropar metoden System.Management.Automation.Cmdlet.ShouldContinue* bör den ha en parameter som kringgår anropen till dessa två metoder och som fortsätter med Force åtgärden. Detta är viktigt eftersom det gör att din cmdlet kan användas i icke-interaktiva skript och värdar.
Om dina cmdlets stöder dessa anrop kan användaren avgöra om åtgärden faktiskt ska utföras. Till exempel anropar cmdleten Stop-Process metoden System.Management.Automation.Cmdlet.ShouldContinue* innan den stoppar en uppsättning kritiska processer, inklusive processerna System, Winlogon och Spoolsv.
Mer information om hur du stöder dessa metoder finns i Begära bekräftelse.
Support Force-parameter för interaktiva sessioner (RD05)
Om din cmdlet används interaktivt anger du alltid en Force-parameter för att åsidosätta interaktiva åtgärder, till exempel prompter eller läsning av indatarader). Detta är viktigt eftersom det gör att din cmdlet kan användas i icke-interaktiva skript och värdar. Följande metoder kan implementeras av en interaktiv värd.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.Pshostuserinterface.PromptForChoice
System.Management.Automation.Host.Ihostuisupportsmultiplechoiceselection.PromptForChoice
System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*
System.Management.Automation.Host.Pshostuserinterface.ReadLine*
System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*
Dokumentutdataobjekt (RD06)
Windows PowerShell använder de objekt som skrivs till pipelinen. För att användarna ska kunna dra nytta av de objekt som returneras av varje cmdlet måste du dokumentera de objekt som returneras och du måste dokumentera vad medlemmarna i de returnerade objekten används för.
Riktlinjer för kod
Följande riktlinjer måste följas när du skriver cmdlet-kod. 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.
Härled från cmdlet- eller PSCmdlet-klasser (RC01)
En cmdlet måste komma från antingen basklassen System.Management.Automation.Cmdlet eller System.Management.Automation.PSCmdlet. Cmdlets som härleds från klassen System.Management.Automation.Cmdlet är inte beroende Windows PowerShell körningskörningen. De kan anropas direkt från alla Microsoft-.NET Framework språk. Cmdlets som härleds från klassen System.Management.Automation.PSCmdlet beror på Windows PowerShell körningen. Därför körs de inom ett runspace.
Alla cmdlet-klasser som du implementerar måste vara offentliga klasser. Mer information om dessa cmdlet-klasser finns i Cmdlet-översikt.
Ange cmdlet-attributet (RC02)
För att en cmdlet ska identifieras av Windows PowerShell måste dess .NET Framework vara prydad med cmdlet-attributet. Det här attributet anger följande funktioner i cmdleten .
Det verb-och-substantivpar som identifierar cmdleten.
Standardparameteruppsättningen som används när flera parameteruppsättningar anges. Standardparameteruppsättningen används när Windows PowerShell inte har tillräckligt med information för att avgöra vilken parameter som ska användas.
Anger om cmdleten stöder anrop till metoden System.Management.Automation.Cmdlet.ShouldProcess*. Den här metoden visar ett bekräftelsemeddelande för användaren innan cmdleten gör en ändring i systemet. Mer information om hur bekräftelsebegäranden görs finns i Begära bekräftelse.
Ange effektnivå (eller allvarlighetsgrad) för åtgärden som är associerad med bekräftelsemeddelandet. I de flesta fall bör standardvärdet Medel användas. Mer information om hur effektnivån påverkar bekräftelsebegäranden som visas för användaren finns i Begära bekräftelse.
Mer information om hur du deklarerar cmdlet-attributet finns i CmdletAttribute-deklaration.
Åsidosätta en indatabearbetningsmetod (RC03)
För att cmdleten ska kunna delta i Windows PowerShell måste den åsidosätta minst en av följande metoder för indatabearbetning.
System.Management.Automation.Cmdlet.BeginProcessing Den här metoden anropas en gång och används för att tillhandahålla förbearbetningsfunktioner.
System.Management.Automation.Cmdlet.ProcessRecord Den här metoden anropas flera gånger och används för att tillhandahålla post-efter-post-funktioner.
System.Management.Automation.Cmdlet.EndProcessing Den här metoden anropas en gång och används för att tillhandahålla funktioner efter bearbetningen.
Ange attributet OutputType (RC04)
Attributet OutputType (introducerades i Windows PowerShell 2.0) anger .NET Framework typ som cmdleten returnerar till pipelinen. Genom att ange utdatatypen för dina cmdlets gör du objekten som returneras av cmdleten mer identifieringsbara av andra cmdlets. Mer information om hur du avskriver cmdlet-klassen med det här attributet finns i Deklaration av attributet OutputType.
Behåll inte referenser till utdataobjekt (RC05)
Din cmdlet bör inte behålla några referenser till objekten som skickas till metoden System.Management.Automation.Cmdlet.WriteObject*. Dessa objekt skickas till nästa cmdlet i pipelinen, eller så används de av ett skript. Om du behåller handtagen till objekten äger två entiteter varje objekt, vilket orsakar fel.
Hantera fel robust (RC06)
En administrationsmiljö identifierar och gör viktiga ändringar i det system som du administrerar. Därför är det viktigt att cmdletarna hanterar fel korrekt. Mer information om felposter finns i Windows PowerShell Felrapportering.
När ett fel förhindrar att en cmdlet fortsätter att bearbeta fler poster är det ett avslutande fel. Cmdleten måste anropa metoden System.Management.Automation.Cmdlet.ThrowTerminatingError* som refererar till ett System.Management.Automation.ErrorRecord-objekt. Om ett undantag inte fångas upp av cmdleten Windows PowerShell själva körningen ett avslutande fel som innehåller mindre information.
För ett icke-avslutande fel som inte stoppar åtgärden på nästa post som kommer från pipelinen (till exempel en post som produceras av en annan process) måste cmdleten anropa metoden System.Management.Automation.Cmdlet.WriteError* som refererar till ett System.Management.Automation.ErrorRecord-objekt. Ett exempel på ett icke-avslutande fel är det fel som inträffar om en viss process misslyckas. Genom att anropa metoden System.Management.Automation.Cmdlet.WriteError* kan användaren konsekvent utföra de begärda åtgärderna och behålla informationen för specifika åtgärder som misslyckas. Din cmdlet bör hantera varje post så oberoende som möjligt.
Objektet System.Management.Automation.ErrorRecord som refereras till av metoderna System.Management.Automation.Cmdlet.ThrowTerminatingError* och System.Management.Automation.Cmdlet.WriteError* kräver ett undantag i grunden. Följ .NET Framework när du bestämmer vilket undantag som ska användas. Om felet är semantiskt samma som ett befintligt undantag använder du det undantaget eller härleder från det undantaget. Annars kan du härleda en ny undantags- eller undantagshierarki direkt från typen System.Exception.
Ett System.Management.Automation.ErrorRecord-objekt kräver också en felkategori som grupperar fel för användaren. Användaren kan visa fel baserat på kategorin genom att ange värdet för $ErrorView gränssnittsvariabeln till CategoryView. Möjliga kategorier definieras av uppräkningen System.Management.Automation.ErrorCategory.
Om en cmdlet skapar en ny tråd, och om koden som körs i den tråden kastar ett ohanterat undantag, kommer Windows PowerShell inte att fånga upp felet och avslutar processen.
Om ett objekt har kod i sin destructor som orsakar ett ohanterat undantag Windows PowerShell inte att fånga upp felet och avslutar processen. Detta inträffar också om ett objekt anropar metoder för att ta bort som orsakar ett ohanterat undantag.
Använda en Windows PowerShell modul för att distribuera dina cmdlets (RC07)
Skapa en Windows PowerShell-modul för att paketera och distribuera dina cmdlets. Stöd för moduler introduceras i Windows PowerShell 2.0. Du kan använda sammansättningar som innehåller dina cmdlet-klasser direkt som binära modulfiler (detta är mycket användbart när du testar dina cmdlets), eller så kan du skapa ett modulmanifest som refererar till cmdlet-sammansättningarna. (Du kan också lägga till befintliga snapin-moduler när du använder moduler.) Mer information om moduler finns i Skriva en Windows PowerShell Modul.
Se även
Starkt rekommenderade riktlinjer för utveckling
Feedback
Skicka och visa feedback för