Vereiste richtlijnen voor de ontwikkeling
De volgende richtlijnen moeten worden gevolgd wanneer u uw cmdlets schrijft. Ze worden gescheiden in richtlijnen voor het ontwerpen van cmdlets en richtlijnen voor het schrijven van uw cmdlet-code. Als u deze richtlijnen niet volgt, kunnen uw cmdlets mislukken en hebben uw gebruikers mogelijk een slechte ervaring wanneer ze uw cmdlets gebruiken.
In dit onderwerp
Ontwerprichtlijnen
Coderichtlijnen
een RC03- (Input Processing Method) overschrijven
geef de RC04- (OutputType Attribute) op
Een Windows PowerShell-module gebruiken om uw cmdlets (RC07) te implementeren
Ontwerprichtlijnen
De volgende richtlijnen moeten worden gevolgd bij het ontwerpen van cmdlets om een consistente gebruikerservaring te garanderen tussen het gebruik van uw cmdlets en andere cmdlets. Wanneer u een ontwerprichtlijnen vindt die van toepassing is op uw situatie, moet u de coderichtlijnen voor vergelijkbare richtlijnen bekijken.
Alleen goedgekeurde werkwoorden gebruiken (RD01)
De werkwoord die is opgegeven in het kenmerk Cmdlet, moet afkomstig zijn van de herkende set werkwoorden die worden geleverd door Windows PowerShell. Het mag geen van de verboden synoniemen zijn. Gebruik de constante tekenreeksen die zijn gedefinieerd door de volgende opsommingen om cmdlet-werkwoorden op te geven:
Zie Cmdlet-werkwoordenvoor meer informatie over de goedgekeurde werkwoorden.
Gebruikers hebben een set detecteerbare en verwachte cmdlet-namen nodig. Gebruik het juiste werkwoord zodat de gebruiker een snelle evaluatie kan maken van wat een cmdlet doet en om eenvoudig de mogelijkheden van het systeem te ontdekken. Met de volgende opdrachtregelopdracht wordt bijvoorbeeld een lijst opgehaald met alle opdrachten op het systeem waarvan de namen beginnen met 'Start': Get-Command Start-*. Gebruik de zelfstandige naamwoorden in uw cmdlets om uw cmdlets te onderscheiden van andere cmdlets. Het zelfstandig naamwoord geeft de resource aan waarop de bewerking wordt uitgevoerd. De bewerking zelf wordt vertegenwoordigd door het werkwoord.
Cmdlet-namen: tekens die niet kunnen worden gebruikt (RD02)
Gebruik geen van de volgende speciale tekens wanneer u cmdlets noemt.
| Karakter | Naam |
|---|---|
| # | hekje |
| , | komma |
| () | haakjes |
| {} | bretels |
| [] | haakjes |
| & | ampersand |
| - | afbreekstreepje Opmerking: Het afbreekstreepje kan worden gebruikt om het werkwoord te scheiden van het zelfstandig naamwoord, maar kan niet worden gebruikt binnen het zelfstandig naamwoord of binnen het werkwoord. |
| / | slash-markering |
| \ | backslash |
| $ | dollarteken |
| ^ | Caret |
| ; | puntkomma |
| : | dikke darm |
| " | dubbele aanhalingsteken |
| ' | enkel aanhalingsteken |
| <> | Punthaken |
| | | verticale balk |
| ? | vraagteken |
| @ | apenstaart |
| ` | rugstreepje (accent grave) |
| * | sterretje |
| % | Procentteken |
| + | plusteken |
| = | gelijkteken |
| ~ | tilde |
Parametersnamen die niet kunnen worden gebruikt (RD03)
Windows PowerShell biedt een algemene set parameters voor alle cmdlets plus extra parameters die in specifieke situaties worden toegevoegd. Bij het ontwerpen van uw eigen cmdlets kunt u de volgende namen niet gebruiken: Bevestigen, Fouten opsporen, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction en Verbose. Zie Common Parameter Namesvoor meer informatie over deze parameters.
Ondersteuningsbevestigingsaanvragen (RD04)
Voor cmdlets die een bewerking uitvoeren die het systeem wijzigt, moeten ze de System.Management.Automation.Cmdlet.ShouldProcess* methode aanroepen om bevestiging aan te vragen en in speciale gevallen de methode System.Management.Automation.Cmdlet.ShouldContinue* aanroepen methode. (De methode System.Management.Automation.Cmdlet.ShouldContinue* moet alleen worden aangeroepen nadat de methode System.Management.Automation.Cmdlet.ShouldProcess* methode is aangeroepen.)
Als u deze aanroepen wilt uitvoeren, moet de cmdlet opgeven dat deze bevestigingsaanvragen ondersteunt door het SupportsShouldProcess trefwoord van het kenmerk Cmdlet in te stellen. Zie Declaratie van cmdlet-kenmerkvoor meer informatie over het instellen van dit kenmerk.
Notitie
Als het cmdlet-kenmerk van de cmdlet-klasse aangeeft dat de cmdlet aanroept naar de System.Management.Automation.Cmdlet.ShouldProcess* methode, en de cmdlet kan de aanroep naar de System.Management.Automation.Cmdlet.ShouldProcess* methode, de gebruiker kan het systeem onverwacht wijzigen.
Gebruik de System.Management.Automation.Cmdlet.ShouldProcess* methode voor systeemwijziging. Een gebruikersvoorkeur en de parameter WhatIf bepalen de methode System.Management.Automation.Cmdlet.ShouldProcess*. Daarentegen voert de System.Management.Automation.Cmdlet.ShouldContinue* aanroep een extra controle uit op mogelijk gevaarlijke wijzigingen. Deze methode wordt niet bepaald door een gebruikersvoorkeur of de parameter WhatIf. Als de cmdlet de methode System.Management.Automation.Cmdlet.ShouldContinue* aanroept, moet deze een Force parameter hebben waarmee de aanroepen naar deze twee methoden worden omzeild en de bewerking wordt uitgevoerd. Dit is belangrijk omdat uw cmdlet kan worden gebruikt in niet-interactieve scripts en hosts.
Als uw cmdlets deze aanroepen ondersteunen, kan de gebruiker bepalen of de actie daadwerkelijk moet worden uitgevoerd. De cmdlet Stop-Process roept bijvoorbeeld de System.Management.Automation.Cmdlet.ShouldContinue* methode aan voordat een set kritieke processen wordt gestopt, waaronder de processen System, Winlogon en Spoolsv.
Zie Bevestigingsaanvraagvoor meer informatie over het ondersteunen van deze methoden.
Ondersteuningsforceparameter voor interactieve sessies (RD05)
Als uw cmdlet interactief wordt gebruikt, moet u altijd een forceparameter opgeven om de interactieve acties te overschrijven, zoals prompts of leesregels voor invoer). Dit is belangrijk omdat uw cmdlet kan worden gebruikt in niet-interactieve scripts en hosts. De volgende methoden kunnen worden geïmplementeerd door een interactieve host.
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*
Documentuitvoerobjecten (RD06)
Windows PowerShell maakt gebruik van de objecten die naar de pijplijn worden geschreven. Als u wilt dat gebruikers profiteren van de objecten die door elke cmdlet worden geretourneerd, moet u de objecten documenteren die worden geretourneerd en moet u documenteren waarvoor de leden van deze geretourneerde objecten worden gebruikt.
Coderichtlijnen
De volgende richtlijnen moeten worden gevolgd bij het schrijven van cmdlet-code. Wanneer u een coderichtlijnen vindt die van toepassing is op uw situatie, moet u de ontwerprichtlijnen voor vergelijkbare richtlijnen bekijken.
Afgeleid van de cmdlet- of PSCmdlet-klassen (RC01)
Een cmdlet moet zijn afgeleid van de System.Management.Automation.Cmdlet of System.Management.Automation.PSCmdlet basisklasse. Cmdlets die zijn afgeleid van de klasse System.Management.Automation.Cmdlet zijn niet afhankelijk van de Windows PowerShell-runtime. Ze kunnen rechtstreeks vanuit elke Microsoft .NET Framework-taal worden aangeroepen. Cmdlets die zijn afgeleid van de System.Management.Automation.PSCmdlet-klasse, zijn afhankelijk van de Windows PowerShell-runtime. Daarom worden ze uitgevoerd binnen een runspace.
Alle cmdlet-klassen die u implementeert, moeten openbare klassen zijn. Zie Cmdlet Overviewvoor meer informatie over deze cmdlet-klassen.
Geef het cmdlet-kenmerk (RC02) op
Als u een cmdlet wilt herkennen door Windows PowerShell, moet de bijbehorende .NET Framework-klasse zijn voorzien van het cmdlet-kenmerk. Met dit kenmerk worden de volgende functies van de cmdlet opgegeven.
Het werkwoord-en-zelfstandig naamwoordpaar waarmee de cmdlet wordt geïdentificeerd.
De standaardparameterset die wordt gebruikt wanneer meerdere parametersets worden opgegeven. De standaardparameterset wordt gebruikt wanneer Windows PowerShell onvoldoende informatie heeft om te bepalen welke parameter moet worden gebruikt.
Geeft aan of de cmdlet aanroepen naar de System.Management.Automation.Cmdlet.ShouldProcess* methode ondersteunt. Met deze methode wordt een bevestigingsbericht weergegeven aan de gebruiker voordat de cmdlet een wijziging aanbrengt in het systeem. Zie Bevestigingsbevestiging aanvragenvoor meer informatie over hoe bevestigingsaanvragen worden gedaan.
Geef het impactniveau (of ernst) aan van de actie die is gekoppeld aan het bevestigingsbericht. In de meeste gevallen moet de standaardwaarde normaal worden gebruikt. Zie Bevestigingsbevestiging aanvragenvoor meer informatie over hoe het impactniveau van invloed is op de bevestigingsaanvragen die aan de gebruiker worden weergegeven.
Zie CmdletAttribute-declaratievoor meer informatie over het declareren van het cmdlet-kenmerk.
Een Input Processing Method (RC03) overschrijven
Als de cmdlet kan deelnemen aan de Windows PowerShell-omgeving, moet deze ten minste een van de volgende invoerverwerkingsmethodenoverschrijven.
System.Management.Automation.Cmdlet.BeginProcessing Deze methode wordt eenmalig aangeroepen en wordt gebruikt om preverwerkingsfunctionaliteit te bieden.
System.Management.Automation.Cmdlet.ProcessRecord Deze methode wordt meerdere keren aangeroepen en wordt gebruikt om record-by-recordfunctionaliteit te bieden.
System.Management.Automation.Cmdlet.EndProcessing Deze methode wordt eenmalig aangeroepen en wordt gebruikt om functionaliteit voor naverwerking te bieden.
Geef het OutputType-kenmerk (RC04) op
Het kenmerk OutputType (geïntroduceerd in Windows PowerShell 2.0) geeft het .NET Framework-type op dat door de cmdlet wordt geretourneerd naar de pijplijn. Door het uitvoertype van uw cmdlets op te geven, kunt u de objecten die door uw cmdlet worden geretourneerd, beter detecteren door andere cmdlets. Zie OutputType Attribute Declarationvoor meer informatie over het decoreren van de cmdlet-klasse met dit kenmerk.
Handgrepen niet behouden voor uitvoerobjecten (RC05)
Uw cmdlet mag geen ingangen bewaren voor de objecten die worden doorgegeven aan de methode System.Management.Automation.Cmdlet.WriteObject*. Deze objecten worden doorgegeven aan de volgende cmdlet in de pijplijn of worden gebruikt door een script. Als u de ingangen voor de objecten behoudt, zijn twee entiteiten eigenaar van elk object, wat fouten veroorzaakt.
Fouten robuust verwerken (RC06)
Een beheeromgeving detecteert en brengt belangrijke wijzigingen aan in het systeem dat u beheert. Daarom is het essentieel dat cmdlets fouten correct verwerken. Zie Windows PowerShell-foutenrapportagevoor meer informatie over foutrecords.
Wanneer een fout voorkomt dat een cmdlet meer records verwerkt, is het een afsluitfout. De cmdlet moet de System.Management.Automation.Cmdlet.ThrowTerminatingError* aanroepen methode die verwijst naar een System.Management.Automation.ErrorRecord-object. Als een uitzondering niet wordt onderschept door de cmdlet, genereert de Windows PowerShell-runtime zelf een afsluitfout die minder informatie bevat.
Voor een niet-afsluitfout die de bewerking niet stopt op de volgende record die afkomstig is van de pijplijn (bijvoorbeeld een record die is geproduceerd door een ander proces), moet de cmdlet de System.Management.Automation.Cmdlet.WriteError* aanroepen methode die verwijst naar een System.Management.Automation.ErrorRecord-object. Een voorbeeld van een niet-afsluitfout is de fout die optreedt als een bepaald proces niet kan worden gestopt. Als u de System.Management.Automation.Cmdlet.WriteError* methode aanroept, kan de gebruiker de aangevraagde acties consistent uitvoeren en de informatie bewaren voor bepaalde acties die mislukken. Uw cmdlet moet elke record zo onafhankelijk mogelijk verwerken.
Het System.Management.Automation.ErrorRecord object waarnaar wordt verwezen door de System.Management.Automation.Cmdlet.ThrowTerminatingError* en System.Management.Automation.Cmdlet.WriteError* methoden vereist een uitzondering in de kern. Volg de ontwerprichtlijnen van .NET Framework wanneer u de uitzondering bepaalt die u wilt gebruiken. Als de fout semantisch hetzelfde is als een bestaande uitzondering, gebruikt u die uitzondering of afgeleid van die uitzondering. Anders leidt u rechtstreeks een nieuwe uitzonderings- of uitzonderingshiërarchie af van het System.Exception type.
Voor een System.Management.Automation.ErrorRecord-object is ook een foutcategorie vereist waarmee fouten voor de gebruiker worden gegroepeerd. De gebruiker kan fouten weergeven op basis van de categorie door de waarde van de $ErrorView shell-variabele in te stellen op CategoryView. De mogelijke categorieën worden gedefinieerd door de System.Management.Automation.ErrorCategory opsomming.
Als een cmdlet een nieuwe thread maakt en als de code die in die thread wordt uitgevoerd, een onverwerkte uitzondering genereert, wordt de fout niet onderschekt en wordt het proces beëindigd.
Als een object code bevat in de destructor die een niet-verwerkte uitzondering veroorzaakt, wordt de fout niet onderschekt en wordt het proces beëindigd. Dit gebeurt ook als een object methoden verwijderen aanroept die een niet-verwerkte uitzondering veroorzaken.
Een Windows PowerShell-module gebruiken om uw cmdlets (RC07) te implementeren
Maak een Windows PowerShell-module om uw cmdlets te verpakken en te implementeren. Ondersteuning voor modules wordt geïntroduceerd in Windows PowerShell 2.0. U kunt de assembly's die uw cmdlet-klassen rechtstreeks als binaire modulebestanden bevatten gebruiken (dit is erg handig bij het testen van uw cmdlets) of u kunt een modulemanifest maken dat verwijst naar de cmdlet-assembly's. (U kunt ook bestaande moduleassembly's toevoegen wanneer u modules gebruikt.) Zie Een Windows PowerShell-module schrijvenvoor meer informatie over modules.
Zie ook
sterk aangemoedigde ontwikkelingsrichtlijnen
