Zeer aangeraden richtlijnen voor de ontwikkeling

  • Artikel

In deze sectie worden de richtlijnen beschreven die u moet volgen wanneer u uw cmdlets schrijft. Ze zijn gescheiden in richtlijnen voor het ontwerpen van cmdlets en richtlijnen voor het schrijven van uw cmdlet-code. Mogelijk zijn deze richtlijnen niet van toepassing op elk scenario. Als ze echter wel 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 voor een consistente gebruikerservaring 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.

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 vinden. Voorvoegsel algemene zelfstandige naamwoorden zoals 'server' met een verkorte versie van de productnaam. Als een zelfstandig naamwoord bijvoorbeeld verwijst naar een server met een exemplaar van Microsoft SQL Server, 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 ontdekken en te anticiperen terwijl duplicatie tussen cmdlet-namen wordt voorkomen.

Om de gebruikerservaring te verbeteren, moet het zelfstandige naamwoord dat u kiest voor de naam van een cmdlet enkelvoudig 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 zal reageren.

Gebruik Pascal Case voor cmdlet-namen (SD02)

Gebruik de parameternamen in het geval van Parameters. Met andere woorden, gebruik in hoofdletters de eerste letter van het werkwoord en alle termen die in het zelfstandig naamwoord worden gebruikt. Bijvoorbeeld Clear-ItemProperty.

Richtlijnen voor het ontwerpen van parameters (SD03)

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

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 een specifiekere naam op als alias. De cmdlet heeft bijvoorbeeld een parameter met een algemene Get-Service naam ( ) en een Name specifiekere alias ( ServiceName ). Beide termen kunnen worden gebruikt om de parameter op te geven.

Zie Cmdlet Parameter Name and Functionality Guidelines (Richtlijnen voor cmdlet-parameternamen en -functionaliteit)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 nemen omdat de gebruiker mogelijk een matrix of lijst met slechts één element oplevert.

Meervoudsparameternamen moeten alleen worden gebruikt in gevallen waarin de waarde van de parameter altijd een waarde met meerdere elementen is. In dergelijke gevallen moet de cmdlet controleren of er meerdere elementen zijn opgegeven en moet de cmdlet een waarschuwing weergeven voor de gebruiker als er geen meerdere elementen zijn opgegeven.

Parameternamen gebruiken in Parametercase

Gebruik de parameternamen in het geval van Parameters. Met andere woorden, hoofdletters van de eerste letter van elk woord in de parameternaam, met inbegrip van de eerste letter van de naam. De parameternaam maakt bijvoorbeeld gebruik ErrorAction van het juiste hoofdlettergebruik. De volgende parameternamen gebruiken een onjuist hoofdlettergebruik:

  • errorAction
  • erroraction

Parameters die een lijst met opties maken

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

  • Definieer een type enumeratie (of gebruik een bestaand type enumeratie) dat de geldige waarden specificeert. Gebruik vervolgens het type enumeratie om een parameter van dat type te maken.

  • Voeg het kenmerk ValidateSet toe aan de parameterdeclaratie. Zie ValidateSet Attribute Declaratievoor meer informatie over dit kenmerk.

Standaardtypen gebruiken voor parameters

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

Strongly-Typed .NET Framework gebruiken

Parameters moeten worden gedefinieerd als .NET Framework voor betere parametervalidatie. Parameters die zijn beperkt tot één waarde uit een set waarden, moeten bijvoorbeeld worden gedefinieerd als een type enumeratie. Ter ondersteuning van een URI-waarde (Uniform Resource Identifier) definieert u de parameter als een System.URI-type. Vermijd eenvoudige tekenreeksparameters voor alle teksteigenschappen, behalve vrije tekst.

Consistente parametertypen gebruiken

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

Parameters die waar en onwaar zijn

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

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

Ondersteunings matrices voor parameters

Gebruikers moeten vaak dezelfde bewerking uitvoeren voor meerdere argumenten. Voor deze gebruikers moet een cmdlet een matrix accepteren als parameterinvoer, zodat een gebruiker de argumenten kan doorgeven aan de parameter als een Windows PowerShell variabele. De cmdlet Get-Process maakt bijvoorbeeld gebruik van een matrix voor de tekenreeksen die de namen identificeren van de processen die moeten worden opgehaald.

Ondersteuning voor de Parameter PassThru

Veel cmdlets die het systeem wijzigen, zoals de cmdlet Stop-Process, fungeren standaard als 'sinks' voor objecten en retourneren geen resultaat. Deze cmdlet moet de parameter implementeren om af te dwingen dat de PassThru cmdlet een -object retourneert. Wanneer de parameter is opgegeven, retourneert de cmdlet een -object met behulp van een aanroep naar de PassThru methode System.Management.Automation.Cmdlet.WriteObject. Met de volgende opdracht stopt u bijvoorbeeld het Calc-proces en geeft u het resultaatproces door aan de pijplijn.

Stop-Process calc -passthru

In de meeste gevallen moeten de 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 aangeduid met de naam, de id of een procesobject. De cmdlet moet alle redelijke representaties van de doelen ondersteunen. Normaal gesproken voldoet de cmdlet aan deze vereiste door sets parameters (aangeduid als parametersets) op te geven die samen worden gebruikt. Eén parameter kan deel uitmaken van een groot aantal parametersets. Zie Cmdlet Parameter Setsvoor meer informatie over parametersets.

Wanneer u parametersets opgeeft, stelt u slechts één parameter in de set in op ValueFromPipeline. Zie ParameterAttribute-declaratievoor meer informatie over het declareerken van het kenmerk Parameter.

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 declareeren van het kenmerk CmdletAttribute.

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 zich bewust zijn van wat er in het systeem gebeurt en betere beheerbeslissingen nemen.

Met Windows PowerShell runtime kan een gebruiker opgeven hoe de uitvoer van elke aanroep van de methode moet worden verwerkt door Write 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 moet uitvoeren op de gebruiker voordat 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 deze methode bijvoorbeeld 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 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 weten wat de cmdlet-bewerking heeft beschadigd. Het is niet nodig dat de cmdlet de methode System.Management.Automation.Cmdlet.WriteDebug aanroept in dezelfde code die de methode System.Management.Automation.Cmdlet.WriteVerbose aanroept, omdat de parameter beide Debug gegevenssets bevat.

Ondersteuning voor WriteProgress voor bewerkingen die lang duren

Cmdlet-bewerkingen die lang duren en die niet op de achtergrond kunnen worden uitgevoerd, moeten ondersteuning bieden voor voortgangsrapportage 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 schrijf- of should-methoden te gebruiken die worden ondersteund door de klasse System.Management.Automation.Cmdlet. In dit geval moet de cmdlet worden 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 te werken met buffers.

Tenzij een cmdlet speciaal 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 Out-GridView-cmdlet.

Notitie

Cmdlets mogen de System.Console-API niet gebruiken.

Een Help-bestand voor cmdlet maken (SD05)

Maak voor elke cmdlet-assembly een Help.xml 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 voor een consistente gebruikerservaring tussen het gebruik van uw cmdlets en andere cmdlets. Wanneer u een coderichtlijn vindt die van toepassing is op uw situatie, moet u de ontwerprichtlijnen voor vergelijkbare richtlijnen bekijken.

Coderingsparameters (SC01)

Definieer een parameter door een openbare eigenschap van de cmdlet-klasse te declareren die is voorzien van het kenmerk Parameter. Parameters moeten geen statische leden zijn van de afgeleide .NET Framework klasse voor de cmdlet. Zie Declaratie van parameterkenmerken voor meer informatie over het declareerkenmerk Parameterkenmerk.

Ondersteuning voor Windows PowerShell paden

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

Als uw cmdlet toestaat dat de gebruiker een bestand of een gegevensbron opgeeft, moet deze een parameter van het type System.String definiëren. Als meer dan één station wordt ondersteund, moet het type een matrix zijn. De naam van de parameter moet Path zijn, met een alias van PSPath . Daarnaast moet de Path parameter jokertekens ondersteunen. Als ondersteuning voor jokertekens niet is vereist, 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 om te zetten in paden die door het bestandssysteem worden herkend. De specifieke mechanismen omvatten de volgende methoden:

Als de gegevens die de cmdlet leest of schrijft, slechts een set tekenreeksen zijn in plaats van een bestand, moet de cmdlet de inhoudsinformatie van de provider (lid) gebruiken om te lezen en Content schrijven. Deze informatie wordt verkregen van de eigenschap System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Met deze mechanismen kunnen andere gegevensopslagen 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 nodig heeft om één object uit een set objecten te identificeren). De voorbeeld-cmdlet uit de StopProc-zelfstudie definieert bijvoorbeeld een parameter voor het afhandelen van tekenreeksen Stop-Proc die Name 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. Soms 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 wordt de oplossing op één locatie gedwongen.

Zie ondersteunende jokertekens in cmdlet-parametersvoor 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 bestand Windows PowerShell Types.ps1xml als sjabloon). Standaardleden worden gedefinieerd door een knooppunt met de naam PSStandardMembers. Met deze definities kunnen andere cmdlets en Windows PowerShell 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 ervan rechtstreeks worden weergegeven aan de parameters van de cmdlets die het zullen gebruiken. Met deze toewijzing kan het object eenvoudig naar de pijplijn worden verzonden en van de ene cmdlet naar de andere worden doorgegeven.

Bestaande objecten .NET Framework 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 script-eigenschap toevoegen aan het Mode type System.IO.FileInfo om de kenmerken van een bestand duidelijker weer te geven. Daarnaast kunt u een alias-eigenschap toevoegen aan het type System.Array om het consistente gebruik van die eigenschapsnaam Count toe te staan (in plaats van Length ).

De IComparable Interface implementeren

Implementeert een System.IComparable-interface op alle uitvoerobjecten. Hierdoor kunnen de uitvoerobjecten eenvoudig worden doorspijpt naar verschillende cmdlets voor sorteren en analyseren.

Weergave-informatie bijwerken

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

Ondersteuning voor goed gedefinieerde pijplijninvoer (SC02)

Implementeren voor het midden van een pijplijn

Implementeert een cmdlet ervan uitgaande dat deze wordt aangeroepen vanuit het midden van een pijplijn (dat wil zeggen dat andere cmdlets de invoer produceren of de uitvoer ervan verbruiken). U kunt er bijvoorbeeld van uitgaan dat de cmdlet, omdat deze gegevens genereert, alleen wordt gebruikt als de eerste Get-Process cmdlet in een pijplijn. Omdat deze cmdlet echter is ontworpen voor het midden van een pijplijn, staat deze cmdlet eerdere cmdlets of gegevens in de pijplijn toe 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 invoer van de pijplijn ondersteunt. Ondersteuning voor pijplijninvoer stelt de gebruiker in staat om gegevens of objecten op te halen, ze naar de juiste parameterset te verzenden en de resultaten rechtstreeks door te geven aan een cmdlet.

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

Ondersteuning voor de ProcessRecord-methode

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, eenmaal voor elke record die naar uw cmdlet wordt verzonden.

Enkele records schrijven naar de pijplijn (SC03)

Wanneer een cmdlet objecten retourneert, moet de cmdlet de objecten onmiddellijk schrijven wanneer ze worden gegenereerd. De cmdlet mag ze niet in de buffer plaatsen om ze te bufferen in een gecombineerde matrix. De cmdlets die de objecten als invoer ontvangen, kunnen de uitvoerobjecten vervolgens zonder vertraging verwerken, weergeven of verwerken en weergeven. Een cmdlet waarmee uitvoerobjecten één voor één worden gegenereerd, moet de methode System.Management.Automation.Cmdlet.WriteObject aanroepen. Een cmdlet die uitvoerobjecten in batches genereert (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 Case-Insensitive en Case-Preserving (SC04)

Standaard is Windows PowerShell niet-casegevoelig. Omdat er echter veel bestaande systemen worden gebruikt, blijven Windows PowerShell voor betere werking en compatibiliteit behouden. Met andere woorden, als een teken wordt opgegeven in hoofdletters, Windows PowerShell in hoofdletters. Een cmdlet moet deze conventie volgen om systemen goed te laten werken. Indien mogelijk moet deze op een niet-casegevoelige manier werken. Het oorspronkelijke geval moet echter behouden blijven voor cmdlets die later in een opdracht of in de pijplijn plaatsvinden.

Zie ook

Vereiste richtlijnen voor de ontwikkeling

Geadviseerde richtlijnen voor de ontwikkeling

Een Windows PowerShell-cmdlet schrijven