Vereiste richtlijnen voor de ontwikkeling
De volgende richtlijnen moeten worden gevolgd wanneer u uw cmdlets schrijft. Ze zijn 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
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 ontwerprichtlijn vindt die van toepassing is op uw situatie, bekijkt u de coderichtlijnen voor vergelijkbare richtlijnen.
Alleen goedgekeurde werkwoorden (RD01) gebruiken
De werkwoord die is opgegeven in het kenmerk Cmdlet moet afkomstig zijn van de herkende set werkwoorden die door Windows PowerShell. Het mag niet een van de verboden synoniemen zijn. Gebruik de constante tekenreeksen die zijn gedefinieerd door de volgende enumeraties om cmdlet-woorden op te geven:
Zie Cmdlet Verbs (Cmdlet-woorden) voor meer informatie over de goedgekeurde werkwoordnamen.
Gebruikers hebben een set detecteerbare en verwachte cmdlet-namen nodig. Gebruik de juiste werkwoord zodat de gebruiker snel kan beoordelen wat een cmdlet doet en de mogelijkheden van het systeem eenvoudig kan ontdekken. Met de volgende opdrachtregelopdracht haalt u bijvoorbeeld een lijst op met alle opdrachten op het systeem waarvan de naam met 'start' begint: 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 de bewerking .
Cmdlet-namen: tekens die niet kunnen worden gebruikt (RD02)
Gebruik geen van de volgende speciale tekens als u cmdlets een naam noemt.
| Teken | Name |
|---|---|
| # | nummerteken |
| , | Komma |
| () | Haakjes |
| {} | Accolades |
| [] | Haakjes |
| & | Ampersand |
| - | afbreekstreetine Opmerking: het koppelteken 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 |
| ^ | dakje |
| ; | Puntkomma |
| : | Dubbele punt |
| " | dubbele aanhalingstekens |
| ' | enkel aanhalingsteken |
| <> | Punthaken |
| | | verticale balk |
| ? | vraagteken |
| @ | bij teken |
| ` | terug tikken (grafaccent) |
| * | sterretje |
| % | Procentteken |
| + | Plusteken |
| = | is gelijk aan teken |
| ~ | Tilde |
Parametersnamen die niet kunnen worden gebruikt (RD03)
Windows PowerShell biedt een algemene set parameters voor alle cmdlets plus aanvullende parameters die worden toegevoegd in specifieke situaties. Bij het ontwerpen van uw eigen cmdlets kunt u de volgende namen niet gebruiken: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction en Verbose. Zie Algemene parameternamen voor meer informatie over deze parameters.
Ondersteuningsbevestigingsaanvragen (RD04)
Voor cmdlets die een bewerking uitvoeren die het systeem wijzigt, moeten ze de methode System.Management.Automation.Cmdlet.ShouldProcess* aanroepen om bevestiging aan te vragen en in speciale gevallen de methode System.Management.Automation.Cmdlet.ShouldContinue* aan te roepen. (De methode System.Management.Automation.Cmdlet.ShouldContinue* moet alleen worden aangeroepen nadat de methode System.Management.Automation.Cmdlet.ShouldProcess* is aangeroepen.)
Als u deze aanroepen wilt doen, moet de cmdlet opgeven dat deze ondersteuning biedt voor bevestigingsaanvragen door het trefwoord van SupportsShouldProcess het kenmerk Cmdlet in te stellen. Zie Cmdlet Attribute Declaratievoor meer informatie over het instellen van dit kenmerk.
Notitie
Als het kenmerk Cmdlet van de cmdlet-klasse aangeeft dat de cmdlet ondersteuning biedt voor aanroepen naar de methode System.Management.Automation.Cmdlet.ShouldProcess*, en de cmdlet de aanroep naar de methode System.Management.Automation.Cmdlet.ShouldProcess* niet kan doen, kan de gebruiker het systeem onverwacht wijzigen.
Gebruik de system.Management.Automation.Cmdlet.ShouldProcess*-methode voor systeemaanpassingen. Een gebruikersvoorkeur en WhatIf de parameter bepalen de methode System.Management.Automation.Cmdlet.ShouldProcess*. De aanroep System.Management.Automation.Cmdlet.ShouldContinue* voert daarentegen een extra controle uit op mogelijk gevaarlijke wijzigingen. Deze methode wordt niet beheerd door een gebruikersvoorkeur of de WhatIf parameter. Als uw cmdlet de methode System.Management.Automation.Cmdlet.ShouldContinue* aanroept, moet deze een parameter hebben die de aanroepen naar deze twee methoden omzeilt en die doorgaat met de Force bewerking. Dit is belangrijk omdat hiermee 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 methode System.Management.Automation.Cmdlet.ShouldContinue* aan voordat een reeks kritieke processen wordt gestopt, waaronder de processen Systeem, Winlogon en Spoolsv.
Zie Bevestiging aanvragen voor meer informatie over het ondersteunen van deze methoden.
Ondersteuning force parameter voor interactieve sessies (RD05)
Als uw cmdlet interactief wordt gebruikt, geeft u altijd een Force-parameter op om de interactieve acties te overschrijven, zoals prompts of het lezen van invoerregels). Dit is belangrijk omdat hiermee 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 gebruikt de objecten die naar de pijplijn worden geschreven. Om gebruikers te laten profiteren van de objecten die door elke cmdlet worden geretourneerd, moet u de geretourneerde objecten documenteren 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 Code-richtlijn vindt die van toepassing is op uw situatie, bekijkt u de ontwerprichtlijnen voor vergelijkbare richtlijnen.
Afgeleid van de cmdlet- of PSCmdlet-klassen (RC01)
Een cmdlet moet zijn afgeleid van de basisklasse System.Management.Automation.Cmdlet of System.Management.Automation.PSCmdlet. 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 worden aangeroepen. Cmdlets die zijn afgeleid van de klasse System.Management.Automation.PSCmdlet 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 Overzicht van cmdlet voor meer informatie over deze cmdlet-klassen.
Geef het kenmerk cmdlet (RC02) op
Als u wilt dat een cmdlet wordt herkend door Windows PowerShell, moet .NET Framework klasse zijn voorzien van het kenmerk Cmdlet. Met dit kenmerk worden de volgende functies van de cmdlet opgegeven.
Het werkwoord-en-zelfstandig naamwoordpaar dat de cmdlet identificeert.
De standaardparameterset die wordt gebruikt wanneer meerdere parametersets worden opgegeven. De standaardparameterset wordt gebruikt wanneer Windows PowerShell onvoldoende informatie heeft om te bepalen welke parameterset moet worden gebruikt.
Geeft aan of de cmdlet ondersteuning biedt voor aanroepen naar de methode System.Management.Automation.Cmdlet.ShouldProcess*. Met deze methode wordt een bevestigingsbericht weergegeven aan de gebruiker voordat de cmdlet een wijziging aan het systeem aan doet. Zie Bevestiging aanvragen voor meer informatie over hoe bevestigingsaanvragen worden gedaan.
Geef het impactniveau (of de ernst) aan van de actie die is gekoppeld aan het bevestigingsbericht. In de meeste gevallen moet de standaardwaarde Gemiddeld worden gebruikt. Zie Bevestiging aanvragen voor 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 declareeren van het kenmerk cmdlet.
Een invoerverwerkingsmethode (RC03) overschrijven
De cmdlet kan alleen deelnemen aan de Windows PowerShell-omgeving als deze ten minste een van de volgende invoerverwerkingsmethoden overschrijven.
System.Management.Automation.Cmdlet.BeginProcessing Deze methode wordt één keer aangeroepen en wordt gebruikt om voorverwerkingsfunctionaliteit te bieden.
System.Management.Automation.Cmdlet.ProcessRecord Deze methode wordt meerdere keren aangeroepen en wordt gebruikt om record-by-record-functionaliteit te bieden.
System.Management.Automation.Cmdlet.EndProcessing Deze methode wordt één keer aangeroepen en wordt gebruikt om naverwerkingsfunctionaliteit te bieden.
Geef het kenmerk OutputType (RC04) op
Het kenmerk OutputType (geïntroduceerd in Windows PowerShell 2.0) geeft het .NET Framework type op dat uw cmdlet retourneert naar de pijplijn. Door het uitvoertype van uw cmdlets op te geven, kunt u de objecten die door uw cmdlet worden geretourneerd beter detecteerbaar maken door andere cmdlets. Zie Declaratie van het Kenmerk OutputType voor meer informatie over het gebruik van de cmdlet-klasse met dit kenmerk.
Geen grepen behouden voor uitvoerobjecten (RC05)
Uw cmdlet mag geen grepen 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 ze worden gebruikt door een script. Als u de grepen voor de objecten behoudt, zijn twee entiteiten eigenaar van elk object, wat fouten veroorzaakt.
Fouten robuust verwerken (RC06)
Een beheeromgeving detecteert en maakt belangrijke wijzigingen aan het systeem dat u beheert. Daarom is het essentieel dat cmdlets fouten correct verwerken. Zie voor meer informatie over foutrecords Windows PowerShell Foutrapportage.
Wanneer een fout voorkomt dat een cmdlet nog meer records verwerkt, is het een eindfout. De cmdlet moet de methode System.Management.Automation.Cmdlet.ThrowTerminatingError* aanroepen die verwijst naar een System.Management.Automation.ErrorRecord-object. Als een uitzondering niet door de cmdlet wordt afgeslagen, Windows PowerShell runtime zelf een eindfout met minder informatie.
Voor een niet-beëindigingsfout die de bewerking niet stopt op de volgende record die afkomstig is van de pijplijn (bijvoorbeeld een record die wordt geproduceerd door een ander proces), moet de cmdlet de system.Management.Automation.Cmdlet.WriteError*-methode aanroepen die verwijst naar een System.Management.Automation.ErrorRecord-object. Een voorbeeld van een niet-beëindigingsfout is de fout die optreedt als een bepaald proces niet kan worden gestopt. Door de methode System.Management.Automation.Cmdlet.WriteError* aan te roepen, kan de gebruiker de aangevraagde acties consistent uitvoeren en de informatie behouden voor bepaalde acties die mislukken. Uw cmdlet moet elke record zo onafhankelijk mogelijk verwerken.
Voor het object System.Management.Automation.ErrorRecord waarnaar wordt verwezen door de methoden System.Management.Automation.Cmdlet.ThrowTerminatingError* en System.Management.Automation.Cmdlet.WriteError* is een uitzondering vereist. Volg de .NET Framework bij het bepalen van de uitzondering die moet worden gebruikt. Als de fout semantisch hetzelfde is als een bestaande uitzondering, gebruikt u die uitzondering of leidt u af van die uitzondering. Anders kunt u een nieuwe uitzonderings- of uitzonderingshiërarchie rechtstreeks afleiden van het type System.Exception.
Voor een System.Management.Automation.ErrorRecord-object is ook een foutcategorie vereist die fouten voor de gebruiker groeperen. De gebruiker kan fouten bekijken 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-enumeratie.
Als een cmdlet een nieuwe thread maakt, en als de code die in die thread wordt uitgevoerd een onverhandelde uitzondering veroorzaakt, zal Windows PowerShell de fout niet ondervangen en wordt het proces beëindigd.
Als een object code in de destructor heeft die een onverhandelde uitzondering veroorzaakt, Windows PowerShell de fout niet ondervangen en wordt het proces beëindigd. Dit gebeurt ook als een object Verwijderingsmethoden aanroept die een onverhandelde 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 is geïntroduceerd in Windows PowerShell 2.0. U kunt de -assemblies die uw cmdlet-klassen bevatten rechtstreeks als binaire modulebestanden gebruiken (dit is zeer nuttig bij het testen van uw cmdlets) of u kunt een modulemanifest maken dat verwijst naar de cmdlet-assemblies. (U kunt ook bestaande modules toevoegen wanneer u modules gebruikt.) Zie Writing a Windows PowerShell Module (Een module Windows PowerShell schrijven) voor meer informatie over modules.
Zie ook
Zeer aangeraden richtlijnen voor de ontwikkeling
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor