Zeer aangeraden richtlijnen voor de ontwikkeling

In deze sectie worden richtlijnen beschreven die u moet volgen wanneer u uw cmdlets schrijft. Ze worden gescheiden in richtlijnen voor het ontwerpen van cmdlets en richtlijnen voor het schrijven van uw cmdlet-code. U kunt merken dat deze richtlijnen niet van toepassing zijn voor elk scenario. Als ze echter van toepassing zijn en u deze richtlijnen niet volgt, hebben uw gebruikers mogelijk een slechte ervaring wanneer ze uw cmdlets gebruiken.

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.

Een specifiek zelfstandig naamwoord gebruiken voor een cmdlet-naam (SD01)

Zelfstandige naamwoorden die worden gebruikt in de naamgeving van cmdlets moeten zeer specifiek zijn, zodat de gebruiker uw cmdlets kan detecteren. Voeg aan algemene zelfstandige naamwoorden, zoals 'server', een verkorte versie van de productnaam toe. Als een zelfstandig naamwoord bijvoorbeeld verwijst naar een server waarop een exemplaar van Microsoft SQL Server wordt uitgevoerd, gebruikt u een zelfstandig naamwoord zoals 'SQLServer'. De combinatie van specifieke zelfstandige naamwoorden en de korte lijst met goedgekeurde werkwoorden stelt de gebruiker in staat om snel functionaliteit te detecteren en te anticiperen terwijl duplicatie tussen cmdlet-namen wordt vermeden.

Om de gebruikerservaring te verbeteren, moet het zelfstandig naamwoord dat u kiest voor een cmdlet-naam enkelvoudige naam zijn. Gebruik bijvoorbeeld de naam Get-Process in plaats van Get-Processes. U kunt deze regel het beste volgen voor alle cmdlet-namen, zelfs wanneer een cmdlet waarschijnlijk op meer dan één item reageert.

Pascal Case gebruiken voor cmdlet-namen (SD02)

Gebruik Pascal-hoofdletters voor parameternamen. Met andere woorden, gebruik hoofdletters voor de eerste letter van het werkwoord en alle termen die als zelfstandig naamwoord worden gebruikt. Bijvoorbeeld 'Clear-ItemProperty'.

Richtlijnen voor parameterontwerp (SD03)

Een cmdlet heeft parameters nodig die de gegevens ontvangen waarop deze moet worden uitgevoerd en parameters die informatie aangeven die wordt gebruikt om de kenmerken van de bewerking te bepalen. Een cmdlet kan bijvoorbeeld een Name parameter hebben die gegevens van de pijplijn ontvangt en de cmdlet kan een Force parameter hebben om aan te geven dat de cmdlet kan worden gedwongen om de bewerking uit te voeren. Er is geen limiet voor het aantal parameters dat door een cmdlet kan worden gedefinieerd.

Standaardparameternamen gebruiken

Uw cmdlet moet standaardparameternamen gebruiken, zodat de gebruiker snel kan bepalen wat een bepaalde parameter betekent. Als een specifiekere naam is vereist, gebruikt u een standaardparameternaam en geeft u vervolgens een specifiekere naam op als alias. De Get-Service cmdlet heeft bijvoorbeeld een parameter met een algemene naam (Name) en een specifiekere alias (ServiceName). Beide termen kunnen worden gebruikt om de parameter op te geven.

Zie de richtlijnen voor parameternaam en functionaliteit voor cmdlets voor meer informatie over parameternamen en hun gegevenstypen.

Enkelvoudige parameternamen gebruiken

Vermijd het gebruik van meervoudsnamen voor parameters waarvan de waarde één element is. Dit omvat parameters die matrices of lijsten aannemen, omdat de gebruiker mogelijk een matrix of lijst met slechts één element levert.

Namen van meervoudparameters mogen alleen worden gebruikt in gevallen waarin de waarde van de parameter altijd een waarde met meerdere elementen is. In deze gevallen moet de cmdlet controleren of er meerdere elementen zijn opgegeven en moet de cmdlet een waarschuwing voor de gebruiker weergeven als er niet meerdere elementen worden opgegeven.

Pascal Case gebruiken voor parameternamen

Gebruik Pascal-hoofdletters voor parameternamen. Met andere woorden, gebruik hoofdletters voor de eerste letter van elk woord in de naam van de parameter, inclusief de eerste letter van de naam. De parameternaam ErrorAction gebruikt bijvoorbeeld het juiste hoofdlettergebruik. De volgende parameternamen maken gebruik van onjuist hoofdlettergebruik:

• errorAction
• erroraction

Parameters die een lijst met opties nemen

Er zijn twee manieren om een parameter te maken waarvan de waarde kan worden geselecteerd uit een set opties.

• Definieer een opsommingstype (of gebruik een bestaand opsommingstype) waarmee de geldige waarden worden opgegeven. Gebruik vervolgens het opsommingstype om een parameter van dat type te maken.

• Voeg het kenmerk ValidateSet toe aan de parameterdeclaratie. Zie De declaratie van het kenmerk ValidateSet voor meer informatie over dit kenmerk.

Standaardtypen gebruiken voor parameters

Gebruik waar mogelijk standaardtypen voor parameters om consistentie met andere cmdlets te garanderen. Zie Standard Cmdlet Parameter Names and Types voor meer informatie over de typen die moeten worden gebruikt voor verschillende parameters. Dit onderwerp bevat koppelingen naar verschillende onderwerpen waarin de namen en .NET Framework-typen worden beschreven voor groepen standaardparameters, zoals de activiteitsparameters.

Strongly-Typed .NET Framework-typen gebruiken

Parameters moeten worden gedefinieerd als .NET Framework-typen om een betere parametervalidatie te bieden. Parameters die zijn beperkt tot één waarde uit een set waarden, moeten bijvoorbeeld worden gedefinieerd als een opsommingstype. Als u een URI-waarde (Uniform Resource Identifier) wilt ondersteunen, definieert u de parameter als een Type System.Uri . Vermijd eenvoudige tekenreeksparameters behalve voor vrije-vorm teksteigenschappen.

Consistente parametertypen gebruiken

Wanneer dezelfde parameter door meerdere cmdlets wordt gebruikt, gebruikt u altijd hetzelfde parametertype. Als de Process parameter bijvoorbeeld een System.Int16-type is voor één cmdlet, moet u de Process parameter voor een andere cmdlet niet een Type System.Uint16 maken.

Parameters die waar en onwaar kunnen aannemen

Als uw parameter alleen true en false aanneemt, definieert u de parameter als van het type System.Management.Automation.SwitchParameter. Een [switch] parameter wordt behandeld als true wanneer deze wordt opgegeven in een opdracht. Als de parameter niet is opgenomen in een opdracht, beschouwt Windows PowerShell de waarde van de parameter als false. Definieer geen Booleaanse parameters.

Als uw parameter onderscheid moet maken tussen drie waarden: $true, $false en 'niet opgegeven', definieert u een parameter van het type Nullable<bool>. De noodzaak van een 3e, niet-opgegeven waarde treedt meestal op wanneer de cmdlet een Booleaanse eigenschap van een object kan wijzigen. In dit geval betekent 'ongespecificeerd' dat de huidige waarde van de eigenschap niet wordt gewijzigd.

Ondersteuning van arrays voor parameters

Vaak moeten gebruikers dezelfde bewerking uitvoeren op basis van meerdere argumenten. Voor deze gebruikers moet een cmdlet een matrix accepteren als parameterinvoer, zodat een gebruiker de argumenten in de parameter kan doorgeven als een Windows PowerShell-variabele. De cmdlet Get-Process gebruikt bijvoorbeeld een matrix voor de tekenreeksen waarmee de namen van de processen worden geïdentificeerd die moeten worden opgehaald.

Ondersteuning voor de parameter PassThru

Veel cmdlets die het systeem wijzigen, zoals de cmdlet Stop-Process cmdlet, fungeren standaard als 'sinks' voor objecten en retourneren geen resultaat. Deze cmdlet zou de PassThru parameter moeten implementeren om de cmdlet te dwingen een object te retourneren. Wanneer de PassThru parameter is opgegeven, retourneert de cmdlet een object met behulp van een aanroep naar de methode System.Management.Automation.Cmdlet.WriteObject . Met de volgende opdracht wordt bijvoorbeeld de Calc (CalculatorApp.exe) gestopt en wordt het resulterende proces doorgegeven aan de pijplijn.

Stop-Process -Name CalculatorApp -PassThru

In de meeste gevallen moeten cmdlets Add, Set en New een PassThru parameter ondersteunen.

Ondersteuningsparametersets

Een cmdlet is bedoeld om één doel te bereiken. Er is echter vaak meer dan één manier om de bewerking of het bewerkingsdoel te beschrijven. Een proces kan bijvoorbeeld worden geïdentificeerd door de naam, de id of een procesobject. De cmdlet moet alle redelijke representaties van de doelstellingen ondersteunen. Normaal gesproken voldoet de cmdlet aan deze vereiste door parametersets, aangeduid als parametersets, op te geven die samenwerken. Eén parameter kan deel uitmaken van een willekeurig aantal parametersets. Zie Cmdlet-parametersets voor meer informatie over parametersets.

Wanneer u parametersets opgeeft, stelt u slechts één parameter in de set in op ValueFromPipeline. Zie ParameterAttribute-declaratie voor meer informatie over het declareren van het parameterkenmerk.

Wanneer parametersets worden gebruikt, wordt de standaardparameterset gedefinieerd door het kenmerk Cmdlet . De standaardparameterset moet de parameters bevatten die waarschijnlijk worden gebruikt in een interactieve Windows PowerShell-sessie. Zie CmdletAttribute-declaratie voor meer informatie over het declareren van het cmdlet-kenmerk.

Feedback geven aan de gebruiker (SD04)

Gebruik de richtlijnen in deze sectie om feedback te geven aan de gebruiker. Met deze feedback kan de gebruiker op de hoogte zijn van wat er in het systeem gebeurt en betere administratieve beslissingen nemen.

Met de Windows PowerShell-runtime kan een gebruiker opgeven hoe uitvoer moet worden verwerkt van elke aanroep naar de methode Write door een voorkeursvariabele in te stellen. De gebruiker kan verschillende voorkeursvariabelen instellen, waaronder een variabele die bepaalt of het systeem informatie moet weergeven en een variabele die bepaalt of het systeem een query op de gebruiker moet uitvoeren voordat er verdere actie wordt ondernomen.

Ondersteuning voor de methoden WriteWarning, WriteVerbose en WriteDebug

Een cmdlet moet de methode System.Management.Automation.Cmdlet.WriteWarning aanroepen wanneer de cmdlet op het punt staat een bewerking uit te voeren die mogelijk een onbedoeld resultaat heeft. Een cmdlet moet bijvoorbeeld deze methode aanroepen als de cmdlet op het punt staat een alleen-lezenbestand te overschrijven.

Een cmdlet moet de methode System.Management.Automation.Cmdlet.WriteVerbose aanroepen wanneer de gebruiker wat details nodig heeft over wat de cmdlet doet. Een cmdlet moet deze informatie bijvoorbeeld aanroepen als de auteur van de cmdlet denkt dat er scenario's zijn waarvoor mogelijk meer informatie nodig is over wat de cmdlet doet.

De cmdlet moet de methode System.Management.Automation.Cmdlet.WriteDebug aanroepen wanneer een ontwikkelaar of productondersteuningstechnicus moet begrijpen wat de cmdlet-bewerking heeft beschadigd. Het is niet nodig dat de cmdlet de methode System.Management.Automation.Cmdlet.WriteDebug in dezelfde code aanroept die de methode System.Management.Automation.Cmdlet.WriteVerbose aanroept omdat de Debug parameter beide gegevenssets presenteert.

Ondersteuning voor WriteProgress voor bewerkingen die lang duren

Cmdlet-bewerkingen die lang duren en die niet op de achtergrond kunnen worden uitgevoerd, moeten de voortgangsrapportage ondersteunen via periodieke aanroepen naar de methode System.Management.Automation.Cmdlet.WriteProgress .

De hostinterfaces gebruiken

Af en toe moet een cmdlet rechtstreeks communiceren met de gebruiker in plaats van de verschillende methoden Schrijven of Moeten te gebruiken die worden ondersteund door de klasse System.Management.Automation.Cmdlet . In dit geval moet de cmdlet zijn afgeleid van de klasse System.Management.Automation.PSCmdlet en de eigenschap System.Management.Automation.PSCmdlet.Host* gebruiken. Deze eigenschap ondersteunt verschillende communicatieniveaus, waaronder de typen PromptForChoice, Prompt en WriteLine/ReadLine. Op het meest specifieke niveau biedt het ook manieren om afzonderlijke sleutels te lezen en schrijven en om buffers af te handelen.

Tenzij een cmdlet specifiek is ontworpen om een grafische gebruikersinterface (GUI) te genereren, mag deze de host niet omzeilen met behulp van de eigenschap System.Management.Automation.PSCmdlet.Host* . Een voorbeeld van een cmdlet die is ontworpen om een GUI te genereren, is de cmdlet Out-GridView.

Een Help-bestand voor cmdlets maken (SD05)

Maak voor elke cmdlet-assembly een Help.xml-bestand met informatie over de cmdlet. Deze informatie bevat een beschrijving van de cmdlet, beschrijvingen van de parameters van de cmdlet, voorbeelden van het gebruik van de cmdlet en meer.

Coderichtlijnen

De volgende richtlijnen moeten worden gevolgd bij het coderen van cmdlets om een consistente gebruikerservaring te garanderen tussen het gebruik van uw cmdlets en andere cmdlets. Wanneer u een coderichtlijn vindt die van toepassing is op uw situatie, moet u ook een ontwerprichtlijn voor vergelijkbare gevallen bekijken.

Coderingsparameters (SC01)

Definieer een parameter door een openbare eigenschap van de cmdlet-klasse te declareren die is ingericht met het kenmerk Parameter . Parameters hoeven geen statische leden te zijn van de afgeleide .NET Framework-klasse voor de cmdlet. Zie Parameterkenmerkdeclaratie voor meer informatie over het declareren van het parameterkenmerk.

Ondersteuning voor Windows PowerShell-paden

Het Windows PowerShell-pad is het mechanisme voor het normaliseren van de toegang tot naamruimten. Wanneer u een Windows PowerShell-pad toewijst aan een parameter in de cmdlet, kan de gebruiker een aangepast station definiëren dat fungeert als een snelkoppeling naar een specifiek pad. Wanneer een gebruiker een dergelijk station aanwijst, kunnen opgeslagen gegevens, zoals gegevens in het Register, op een consistente manier worden gebruikt.

Als de gebruiker met de cmdlet een bestand of gegevensbron kan opgeven, moet deze een parameter van het type System.String definiëren. Als meer dan één station wordt ondersteund, moet het type een array zijn. De naam van de parameter moet zijn Path, met een alias van PSPath. Daarnaast moet de Path parameter jokertekens ondersteunen. Als ondersteuning voor jokertekens niet vereist is, definieert u een LiteralPath parameter.

Als de gegevens die de cmdlet leest of schrijft een bestand moeten zijn, moet de cmdlet Windows PowerShell-padinvoer accepteren en moet de cmdlet de eigenschap System.Management.Automation.SessionState.Path gebruiken om de Windows PowerShell-paden te vertalen naar paden die door het bestandssysteem worden herkend. De specifieke mechanismen omvatten de volgende methoden:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Als de gegevens die de cmdlet leest of schrijft slechts een reeks tekenreeksen is in plaats van een bestand, moet de cmdlet de inhoudsgegevens van de provider (Content lid) gebruiken om te lezen en schrijven. Deze informatie wordt verkregen via de eigenschap System.Management.Automation.Provider.CmdletProvider.InvokeProvider . Met deze mechanismen kunnen andere gegevensarchieven deelnemen aan het lezen en schrijven van gegevens.

Ondersteuning voor jokertekens

Een cmdlet moet indien mogelijk jokertekens ondersteunen. Ondersteuning voor jokertekens vindt plaats op veel plaatsen in een cmdlet (met name wanneer een parameter een tekenreeks gebruikt om één object uit een set objecten te identificeren). De voorbeeld-cmdlet Stop-Proc uit de StopProc-zelfstudie definieert bijvoorbeeld een Name parameter voor het afhandelen van tekenreeksen die procesnamen vertegenwoordigen. Deze parameter ondersteunt jokertekens, zodat de gebruiker eenvoudig de processen kan opgeven die moeten worden gestopt.

Wanneer ondersteuning voor jokertekens beschikbaar is, produceert een cmdlet-bewerking meestal een matrix. Af en toe is het niet zinvol om een matrix te ondersteunen, omdat de gebruiker slechts één item tegelijk kan gebruiken. De cmdlet Set-Location hoeft bijvoorbeeld geen matrix te ondersteunen omdat de gebruiker slechts één locatie instelt. In dit geval ondersteunt de cmdlet nog steeds jokertekens, maar dwingt de oplossing tot één locatie.

Zie Ondersteunende jokertekens in cmdlet-parameters voor meer informatie over jokertekenpatronen.

Objecten definiëren

Deze sectie bevat richtlijnen voor het definiëren van objecten voor cmdlets en voor het uitbreiden van bestaande objecten.

Standaardleden definiëren

Definieer standaardleden om een objecttype uit te breiden in een aangepast Types.ps1xml-bestand (gebruik het Windows PowerShell Types.ps1xml-bestand als sjabloon). Standaardleden worden gedefinieerd door een knooppunt met de naam PSStandardMembers. Met deze definities kunnen andere cmdlets en de Windows PowerShell-runtime op een consistente manier met uw object werken.

Objectmembers definiëren die moeten worden gebruikt als parameters

Als u een object voor een cmdlet ontwerpt, moet u ervoor zorgen dat de leden rechtstreeks worden toegewezen aan de parameters van de cmdlets die het object gaan gebruiken. Met deze mapping kan het object eenvoudig naar de pijplijn worden verzonden en van de ene cmdlet naar de andere worden doorgegeven.

Bestaande .NET Framework-objecten die worden geretourneerd door cmdlets ontbreken vaak enkele belangrijke of handige leden die nodig zijn voor de scriptontwikkelaar of gebruiker. Deze ontbrekende leden kunnen met name belangrijk zijn voor weergave en voor het maken van de juiste lidnamen, zodat het object correct kan worden doorgegeven aan de pijplijn. Maak een aangepast Types.ps1xml-bestand om deze vereiste leden te documenteren. Wanneer u dit bestand maakt, raden we de volgende naamconventie aan: <Your_Product_Name>. Types.ps1xml.

U kunt bijvoorbeeld een Mode scripteigenschap toevoegen aan het type System.IO.FileInfo om de kenmerken van een bestand duidelijker weer te geven. Daarnaast kunt u een Count aliaseigenschap toevoegen aan het type System.Array om het consistente gebruik van die eigenschapsnaam toe te staan (in plaats van Length).

De IComparable Interface implementeren

Implementeer een System.IComparable-interface op alle uitvoerobjecten. Hierdoor kunnen de uitvoerobjecten eenvoudig worden doorgesluisd naar verschillende sorteer- en analyse-cmdlets.

Weergave-informatie bijwerken

Als de weergave voor een object niet de verwachte resultaten levert, maakt u een aangepaste <YourProductName>. Format.ps1xml-bestand voor dat object.

Ondersteuning voor goed gedefinieerde pijplijninvoer (SC02)

Implementatie voor het middengedeelte van een pijplijn

Implementeer een cmdlet ervan uitgaande dat deze wordt aangeroepen vanuit het midden van een pijplijn (dat wil zeggen, andere cmdlets verwerken de invoer of produceren de uitvoer ervan). U kunt er bijvoorbeeld van uitgaan dat de Get-Process cmdlet, omdat deze gegevens genereert, alleen wordt gebruikt als de eerste cmdlet in een pijplijn. Aangezien deze cmdlet is ontworpen voor gebruik in het midden van een pijplijn, maakt deze cmdlet het mogelijk voor eerdere cmdlets of gegevens in de pijplijn om de processen op te geven die moeten worden opgehaald.

Ondersteuning voor invoer van de pijplijn

Neem in elke parameterset voor een cmdlet ten minste één parameter op die ondersteuning biedt voor invoer van de pijplijn. Met ondersteuning voor pijplijninvoer kan de gebruiker gegevens of objecten ophalen, naar de juiste parameterset verzenden en de resultaten rechtstreeks doorgeven aan een cmdlet.

Een parameter accepteert invoer van de pijplijn als het kenmerk Parameter het ValueFromPipeline trefwoord, het ValueFromPipelineByPropertyName kenmerk trefwoord of beide trefwoorden in de declaratie bevat. Als geen van de parameters in een parameterset trefwoorden ValueFromPipeline of ValueFromPipelineByPropertyName ondersteunt, kan de cmdlet niet zinvol na een andere cmdlet worden geplaatst omdat het alle pijplijninvoer negeert.

De methode ProcessRecord ondersteunen

Als u alle records van de voorgaande cmdlet in de pijplijn wilt accepteren, moet uw cmdlet de methode System.Management.Automation.Cmdlet.ProcessRecord implementeren. Windows PowerShell roept deze methode meerdere keren aan, één keer voor elke record die naar uw cmdlet wordt verzonden.

Eén record schrijven naar de pijplijn (SC03)

Wanneer een cmdlet objecten retourneert, moet de cmdlet de objecten onmiddellijk schrijven wanneer ze worden gegenereerd. De cmdlet zou ze niet moeten vasthouden om ze in een gecombineerde array te bufferen. De cmdlets die de objecten als invoer ontvangen, kunnen vervolgens de uitvoerobjecten zonder vertraging verwerken en/of weergeven. Een cmdlet die uitvoerobjecten één voor één genereert, moet de methode System.Management.Automation.Cmdlet.WriteObject aanroepen. Een cmdlet waarmee uitvoerobjecten in batches worden gegenereerd (bijvoorbeeld omdat een onderliggende API een matrix met uitvoerobjecten retourneert) moet de methode System.Management.Automation.Cmdlet.WriteObject aanroepen met de tweede parameter ingesteld op true.

Cmdlets maken Case-Insensitive en Case-Preserving (SC04)

Standaard is Windows PowerShell zelf niet hoofdlettergevoelig. Omdat het echter om veel bestaande systemen gaat, behoudt Windows PowerShell het geval voor eenvoudiger gebruik en compatibiliteit. Met andere woorden, als een teken wordt opgegeven in hoofdletters, Windows PowerShell het in hoofdletters bewaart. Voor een goed functionerende systemen moet een cmdlet deze conventie volgen. Indien mogelijk moet deze op een niet-hoofdlettergevoelige manier werken. Het moet echter het oorspronkelijke geval behouden voor cmdlets die zich later in een opdracht of in de pijplijn voordoen.

Zie ook

Vereiste ontwikkelingsrichtlijnen

Richtlijnen voor adviesontwikkeling

Een Windows PowerShell-cmdlet schrijven