Anteckning
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Följande riktlinjer måste följas 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. Om du inte följer dessa riktlinjer kan dina cmdletar misslyckas och användarna kan ha en dålig upplevelse när de använder dina cmdletar.
I det här avsnittet
Designriktlinjer
Kodriktlinjer
Designriktlinjer
Följande riktlinjer måste 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 endast godkända verb (RD01)
Verbet som anges i cmdlet-attributet 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 de godkända verbnamnen 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 kan göra en snabb bedömning av 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 cmdletar för att skilja dina cmdletar från andra cmdletar. Substantivet anger den resurs 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 namnger cmdletar ska du inte använda något av följande specialtecken.
| Karaktär | Namn |
|---|---|
| # | taltecken |
| , | komma |
| () | parentes |
| {} | hängslen |
| [] | Parentes |
| & | et-tecken |
| - | bindestreck Obs! Bindestrecket kan användas för att skilja verbet från substantivet, men det kan inte användas i substantiv eller inom verbet. |
| / | snedstreck |
| \ | omvänt snedstreck |
| $ | dollartecken |
| ^ | Caret |
| ; | semikolon |
| : | kolon |
| " | dubbla citattecken |
| ' | enkelt citattecken |
| <> | Vinkelparenteser |
| | | lodrät stapel |
| ? | frågetecken |
| @ | snabel-a |
| ` | tillbaka tick (grav accent) |
| * | asterisk |
| % | procenttecken |
| + | plustecken |
| = | likhetstecken |
| ~ | tilde |
Parameternamn som inte kan användas (RD03)
Windows PowerShell tillhandahåller en gemensam uppsättning parametrar för alla cmdletar plus ytterligare parametrar som läggs till i specifika situationer. När du utformar egna cmdletar 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.
Begäranden om supportbekräftelse (RD04)
För cmdletar som utför en åtgärd som ändrar systemet bör de anropa System.Management.Automation.Cmdlet.ShouldProcess* metod 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* ska anropas först efter att metoden System.Management.Automation.Cmdlet.ShouldProcess* anropas.)
För att göra dessa anrop måste cmdleten ange att den stöder bekräftelsebegäranden genom att ange nyckelordet SupportsShouldProcess för cmdlet-attributet. Mer information om hur du anger det här attributet finns i Cmdlet-attributdeklaration.
Anmärkning
Om cmdlet-attributet för cmdlet-klassen anger att cmdleten stöder anrop till System.Management.Automation.Cmdlet.ShouldProcess*-metoden, och cmdleten inte kan anropa System.Management.Automation.Cmdlet.ShouldProcess*-metoden, kan användaren oväntat ändra systemet.
Använd metoden System.Management.Automation.Cmdlet.ShouldProcess* för alla systemändringar. En användarinställning och parametern WhatIf 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 någon användarinställning eller parametern WhatIf. Om din cmdlet anropar metoden System.Management.Automation.Cmdlet.ShouldContinue* bör den ha en Force parameter som kringgår anropen till dessa två metoder och som fortsätter med åtgärden. Detta är viktigt eftersom det gör att din cmdlet kan användas i icke-interaktiva skript och värdar.
Om dina cmdletar stöder dessa anrop kan användaren avgöra om åtgärden verkligen ska utföras. Cmdleten Stop-Process anropar till exempel 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.
Stöd force-parameter för interaktiva sessioner (RD05)
Om din cmdlet används interaktivt anger du alltid en Force-parameter för att åsidosätta de interaktiva åtgärderna, till exempel uppmaningar eller 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 till.
Kodriktlinjer
Följande riktlinjer måste följas när du skriver cmdlet-kod. När du hittar en kodguide som gäller för din situation bör du titta på designriktlinjerna för liknande riktlinjer.
Härled från cmdlet- eller PSCmdlet-klasserna (RC01)
En cmdlet måste härledas från antingen System.Management.Automation.Cmdlet eller System.Management.Automation.PSCmdlet basklass. Cmdletar som härleds från System.Management.Automation.Cmdlet-klassen är inte beroende av Windows PowerShell-körningen. De kan anropas direkt från vilket Microsoft .NET Framework-språk som helst. Cmdletar som härleds från klassen System.Management.Automation.PSCmdlet beror på Windows PowerShell-körningen. Därför körs de inom ett körningsutrymme.
Alla cmdlet-klasser som du implementerar måste vara offentliga klasser. Mer information om dessa cmdlet-klasser finns i Cmdlet Overview.
Ange cmdletattributet (RC02)
För att en cmdlet ska kunna identifieras av Windows PowerShell måste dess .NET Framework-klass dekoreras med cmdlet-attributet. Det här attributet anger följande funktioner i cmdleten.
Verb-och-substantivparet 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 till användaren innan cmdleten ändrar systemet. Mer information om hur bekräftelsebegäranden görs finns i Begära bekräftelse.
Ange påverkansnivån (eller allvarlighetsgraden) för den åtgärd som är associerad med bekräftelsemeddelandet. I de flesta fall ska standardvärdet medium användas. Mer information om hur påverkansnivå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 Declaration.
Åsidosätt en indatabearbetningsmetod (RC03)
För att cmdleten ska kunna delta i Windows PowerShell-miljön måste den åsidosätta minst en av följande indatabearbetningsmetoder.
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-för-post-funktioner.
System.Management.Automation.Cmdlet.EndProcessing Den här metoden anropas en gång och används för att tillhandahålla efterbearbetningsfunktioner.
Ange attributet OutputType (RC04)
Attributet OutputType (introducerades i Windows PowerShell 2.0) anger den .NET Framework-typ som cmdleten returnerar till pipelinen. Genom att ange utdatatypen för dina cmdletar gör du objekten som returneras av cmdleten mer identifierbara av andra cmdletar. Mer information om hur du dekorerar cmdlet-klassen med det här attributet finns i OutputType Attribute Declaration.
Behåll inte referenser till utdataobjekt (RC05)
Cmdleten bör inte behålla några referenser till de objekt 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 cmdletar hanterar fel korrekt. Mer information om felposter finns i Windows PowerShell-felrapportering.
När ett fel hindrar en cmdlet från att fortsätta 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 av cmdleten genererar Själva Windows PowerShell-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 skapats av en annan process) måste cmdleten anropa System.Management.Automation.Cmdlet.WriteError* metod 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 inte kan stoppas. 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 vissa åtgärder som misslyckas. Din cmdlet ska hantera varje post så oberoende som möjligt.
System.Management.Automation.ErrorRecord objekt som refereras av System.Management.Automation.Cmdlet.ThrowTerminatingError* och System.Management.Automation.Cmdlet.WriteError* metoder kräver ett undantag i grunden. Följ designriktlinjerna för .NET Framework när du fastställer undantaget som ska användas. Om felet är semantiskt detsamma som ett befintligt undantag använder du det undantaget eller härleder från det undantaget. Annars härleder du en ny undantags- eller undantagshierarki direkt från System.Exception typ.
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 shell-variabeln till CategoryView. Möjliga kategorier definieras av System.Management.Automation.ErrorCategory uppräkning.
Om en cmdlet skapar en ny tråd, och om koden som körs i den tråden genererar ett ohanterat undantag, kommer Windows PowerShell inte att fånga upp felet och avsluta processen.
Om ett objekt har kod i sin destruktor som orsakar ett ohanterat undantag, kommer Windows PowerShell inte att fånga upp felet och avsluta processen. Detta inträffar också om ett objekt anropar Dispose-metoder som orsakar ett ohanterat undantag.
Använda en Windows PowerShell-modul för att distribuera dina cmdletar (RC07)
Skapa en Windows PowerShell-modul för att paketera och distribuera dina cmdletar. Stöd för moduler introduceras i Windows PowerShell 2.0. Du kan använda de sammansättningar som innehåller dina cmdlet-klasser direkt som binära modulfiler (detta är mycket användbart när du testar dina cmdletar), eller så kan du skapa ett modulmanifest som refererar till cmdlet-sammansättningarna. (Du kan också lägga till befintliga snapin-sammansättningar när du använder moduler.) Mer information om moduler finns i Skriva en Windows PowerShell-modul.
Se även
starkt uppmuntrade riktlinjer för utveckling
Samarbeta med oss på GitHub
Källan för det här innehållet finns på GitHub, där du även kan skapa och granska ärenden och pull-begäranden. Se vår deltagarguide för mer information.
