Geadviseerde richtlijnen voor de ontwikkeling

In deze sectie worden richtlijnen beschreven die u moet overwegen om te zorgen voor een goede ontwikkeling en gebruikerservaring. Soms zijn ze van toepassing en soms niet.

Ontwerprichtlijnen

De volgende richtlijnen moeten worden overwogen bij het ontwerpen van cmdlets. Wanneer u een ontwerprichtlijn vindt die van toepassing is op uw situatie, bekijkt u de coderichtlijnen voor vergelijkbare richtlijnen.

Ondersteuning voor een InputObject Parameter (AD01)

Omdat Windows PowerShell rechtstreeks met Microsoft .NET Framework-objecten werkt, is er vaak een .NET Framework-object beschikbaar dat exact overeenkomt met het type dat de gebruiker nodig heeft om een bepaalde bewerking uit te voeren. InputObject is de standaardnaam voor een parameter die een dergelijk object als invoer gebruikt. De Stop-Proc voorbeeld-cmdlet in de StopProc-zelfstudie definieert bijvoorbeeld een parameter van het type Proces die ondersteuning biedt voor de InputObject invoer van de pijplijn. De gebruiker kan een set procesobjecten krijgen, deze bewerken om de exacte objecten te selecteren die moeten worden gestopt en deze vervolgens rechtstreeks aan de Stop-Proc cmdlet doorgeven.

Ondersteuning voor de Force Parameter (AD02)

Af en toe moet een cmdlet de gebruiker beschermen tegen het uitvoeren van een aangevraagde bewerking. Een dergelijke cmdlet moet een parameter Force ondersteunen zodat de gebruiker die beveiliging kan overschrijven als de gebruiker machtigingen heeft om de bewerking uit te voeren.

De cmdlet Remove-Item verwijdert bijvoorbeeld normaal gesproken geen alleen-lezenbestand. Deze cmdlet ondersteunt echter een forceerparameter, zodat een gebruiker het verwijderen van een alleen-lezen bestand kan forceer. Als de gebruiker al toestemming heeft om het kenmerk alleen-lezen te wijzigen en de gebruiker het bestand verwijdert, vereenvoudigt het gebruik van de parameter Force de bewerking. Als de gebruiker echter geen machtiging heeft om het bestand te verwijderen, heeft de parameter Force geen effect.

Referenties verwerken via Windows PowerShell (AD03)

Een cmdlet moet een Credential parameter definiëren die referenties vertegenwoordigt. Deze parameter moet van het type System.Management.Automation.PSCredential zijn en moet worden gedefinieerd met behulp van de declaratie van het kenmerk Referentie. Deze ondersteuning vraagt de gebruiker automatisch om de gebruikersnaam, het wachtwoord of voor beide wanneer een volledige referentie niet rechtstreeks wordt opgegeven. Zie Declaratie van referentiekenmerken voor meer informatie over het kenmerk Referentie.

Ondersteuning voor coderingsparameters (AD04)

Als uw cmdlet tekst leest of schrijft naar of van een binaire vorm, zoals het schrijven naar of lezen van een bestand in een bestandssysteem, moet uw cmdlet een coderingsparameter hebben die aangeeft hoe de tekst in binaire vorm wordt gecodeerd.

Test-cmdlets moeten een Booleaanse (AD05) retourneren

Cmdlets die tests uitvoeren op hun resources, moeten een System.Booleaanse type aan de pijplijn retourneren, zodat ze kunnen worden gebruikt in voorwaardelijke expressies.

Coderichtlijnen

De volgende richtlijnen moeten worden overwogen bij het schrijven van cmdlet-code. Wanneer u een richtlijn vindt die van toepassing is op uw situatie, bekijkt u de Ontwerprichtlijnen voor vergelijkbare richtlijnen.

Cmdlet Class Naming Conventions (AC01) volgen

Door de standaardnaamconventarisaties te volgen, maakt u uw cmdlets beter vindbaar en helpt u de gebruiker precies te begrijpen wat de cmdlets doen. Deze praktijk is met name belangrijk voor andere ontwikkelaars die Windows PowerShell omdat cmdlets openbare typen zijn.

Een cmdlet definiëren in de juiste naamruimte

Normaal gesproken definieert u de klasse voor een cmdlet in .NET Framework naamruimte die '. Opdrachten' voor de naamruimte die het product vertegenwoordigt waarin de cmdlet wordt uitgevoerd. Cmdlets die zijn opgenomen in de Windows PowerShell worden bijvoorbeeld gedefinieerd in de Microsoft.PowerShell.Commands naamruimte.

De cmdlet-klasse een naam geven die overeen komt met de cmdlet-naam

Wanneer u de .NET Framework-klasse die een cmdlet implementeert, noemt u de klasse "", waarbij u de tijdelijke aanduidingen en vervangt door het werkwoord en zelfstandig naamwoord dat wordt gebruikt voor de naam van de <Verb><Noun><Command> <Verb> <Noun> cmdlet. De cmdlet Get-Process wordt bijvoorbeeld geïmplementeerd door een klasse met de naam GetProcessCommand .

Als geen pijplijninvoer de methode BeginProcessing (AC02) overschrijven

Als uw cmdlet geen invoer van de pijplijn accepteert, moet de verwerking worden geïmplementeerd in de methode System.Management.Automation.Cmdlet.BeginProcessing. Met deze methode kunnen Windows PowerShell de volgorde tussen cmdlets behouden. De eerste cmdlet in de pijplijn retourneert altijd de objecten voordat de resterende cmdlets in de pijplijn de kans krijgen om de verwerking te starten.

Stopaanvragen verwerken: overschrijven de methode StopProcessing (AC03)

Overschrijven de methode System.Management.Automation.Cmdlet.StopProcessing zodat uw cmdlet het stopsignaal kan verwerken. Sommige cmdlets duren lang om hun bewerking te voltooien en ze laten lange tijd tussen aanroepen naar de Windows PowerShell-runtime gaan, bijvoorbeeld wanneer de cmdlet de thread blokkeert in langlopende RPC-aanroepen. Dit omvat cmdlets die de methode System.Management.Automation.Cmdlet.WriteObject aanroepen naar de methode System.Management.Automation.Cmdlet.WriteError en naar andere feedbackmechanismen die lang kunnen duren. In dergelijke gevallen moet de gebruiker mogelijk een stopsignaal naar deze cmdlets verzenden.

Implementeert u de IDisposable Interface (AC04)

Als uw cmdlet objecten heeft die niet zijn verwijderd (geschreven naar de pijplijn) door de methode System.Management.Automation.Cmdlet.ProcessRecord, moet uw cmdlet mogelijk extra objecten verwijderen. Als uw cmdlet bijvoorbeeld een bestandsing handle opent in de methode System.Management.Automation.Cmdlet.BeginProcessing en de greep geopend houdt voor gebruik door de methode System.Management.Automation.Cmdlet.ProcessRecord, moet deze handle aan het einde van de verwerking worden gesloten.

De Windows PowerShell roept niet altijd de system.Management.Automation.Cmdlet.EndProcessing-methode aan. De methode System.Management.Automation.Cmdlet.EndProcessing kan bijvoorbeeld niet worden aangeroepen als de cmdlet halverwege de bewerking wordt geannuleerd of als er een eindfout optreedt in een deel van de cmdlet. Daarom moet de .NET Framework-klasse voor een cmdlet die objectopschoning vereist, het volledige System.IDisposable-interfacepatroon implementeren, inclusief de finalizer, zodat de Windows PowerShell-runtime zowel de system.Management.Automation.Cmdlet.EndProcessing- als System.IDisposable.Dispose*-methoden aan het einde van de verwerking kan aanroepen.

Gebruik serialisatievriendelijke parametertypen (AC05)

Gebruik ter ondersteuning van het uitvoeren van uw cmdlet op externe computers typen die eenvoudig kunnen worden geseraliseerd op de clientcomputer en vervolgens op de servercomputer worden gerehydrateerd. De volgende typen zijn serialisatievriendelijk.

Primitieve typen:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 en UInt64.

• Booleaanse, Guid, Byte[], TimeSpan, DateTime, URI en Version.

• Char, String, XmlDocument.

Ingebouwde rehydrateerbare typen:

• PSPrimitiveDictionary

• SwitchParameter

• PSListModifier

• PSCredential

• IPAddress, MailAddress

• Cultureinfo

• X509Certificate2, X500DistinguishedName

• DirectorySecurity, FileSecurity, RegistrySecurity

Andere typen:

• SecureString

• Containers (lijsten en woordenlijsten van het bovenstaande type)

SecureString gebruiken voor gevoelige gegevens (AC06)

Gebruik bij het verwerken van gevoelige gegevens altijd het gegevenstype System.Security.Securestring. Dit kan pijplijninvoer voor parameters zijn, maar ook het retourneren van gevoelige gegevens naar de pijplijn.

Zie ook

Vereiste richtlijnen voor de ontwikkeling

Zeer aangeraden richtlijnen voor de ontwikkeling

Een Windows PowerShell-cmdlet schrijven