Geadviseerde richtlijnen voor de ontwikkeling

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

Ontwerprichtlijnen

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

Ondersteuning voor een InputObject-parameter (AD01)

Omdat Windows PowerShell rechtstreeks met Microsoft .NET Framework-objecten werkt, is een .NET Framework-object vaak 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 voorbeeld-cmdlet Stop-Proc in de zelfstudie StopProc definieert bijvoorbeeld een InputObject parameter van het type Proces dat ondersteuning biedt voor de invoer van de pijplijn. De gebruiker kan een set procesobjecten ophalen, bewerken om de exacte objecten te selecteren die moeten worden gestopt en deze vervolgens rechtstreeks doorgeven aan de Stop-Proc cmdlet.

Ondersteuning voor de parameter Force (AD02)

Af en toe moet een cmdlet de gebruiker beschermen tegen het uitvoeren van een aangevraagde bewerking. Een dergelijke cmdlet moet ondersteuning bieden voor een forceparameter , zodat de gebruiker deze beveiliging kan overschrijven als de gebruiker machtigingen heeft om de bewerking uit te voeren.

De cmdlet Remove-Item verwijdert bijvoorbeeld normaal gesproken geen bestand met het kenmerk Alleen-lezen. Deze cmdlet ondersteunt echter een forceparameter , zodat een gebruiker het verwijderen van een alleen-lezen bestand kan afdwingen. Als de gebruiker al gemachtigd is 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 niet gemachtigd is 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 om referenties weer te geven. Deze parameter moet van het type System.Management.Automation.PSCredential zijn en moet worden gedefinieerd met behulp van een referentiekenmerkdeclaratie. Deze ondersteuning vraagt de gebruiker automatisch om de gebruikersnaam, het wachtwoord of voor beide wanneer er niet rechtstreeks een volledige referentie wordt opgegeven. Zie Declaratie van referentiekenmerk voor meer informatie over het kenmerk Referentie.

Ondersteuning voor coderingsparameters (AD04)

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

Test-cmdlets moeten een Booleaanse waarde retourneren (AD05)

Cmdlets die tests uitvoeren op hun resources, moeten een System.Boolean-type retourneren aan de pijplijn, 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, moet u de ontwerprichtlijnen voor vergelijkbare richtlijnen bekijken.

Naamconventies voor cmdlet-klassen volgen (AC01)

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

Een cmdlet definiëren in de juiste naamruimte

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

Geef de cmdlet-klasse een naam die overeenkomt met de cmdlet-naam

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

Als er geen pijplijninvoer wordt overschreven, overschrijft u de Methode BeginProcessing (AC02)

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 kan 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 hun verwerking te starten.

Stopaanvragen afhandelen overschrijven de StopProcessing-methode (AC03)

Overschrijf de methode System.Management.Automation.Cmdlet.StopProcessing zodat uw cmdlet stopsignaal kan verwerken. Het duurt lang voordat sommige cmdlets hun bewerking voltooien en ze laten lang doorschakelen tussen aanroepen naar de Windows PowerShell-runtime, bijvoorbeeld wanneer de cmdlet de thread blokkeert in langlopende RPC-aanroepen. Dit omvat cmdlets die aanroepen uitvoeren naar de methode System.Management.Automation.Cmdlet.WriteObject , naar de methode System.Management.Automation.Cmdlet.WriteError en naar andere feedbackmechanismen die lang kunnen duren. In deze gevallen moet de gebruiker mogelijk een stopsignaal naar deze cmdlets verzenden.

De IDisposable Interface (AC04) implementeren

Als uw cmdlet objecten bevat die niet zijn verwijderd (naar de pijplijn geschreven) door de methode System.Management.Automation.Cmdlet.ProcessRecord , is voor uw cmdlet mogelijk extra objectverwijdering vereist. Als uw cmdlet bijvoorbeeld een bestandsgreep opent in de methode System.Management.Automation.Cmdlet.BeginProcessing en de ingang openhoudt voor gebruik door de methode System.Management.Automation.Cmdlet.ProcessRecord , moet deze ingang aan het einde van de verwerking worden gesloten.

De Windows PowerShell-runtime roept niet altijd de methode System.Management.Automation.Cmdlet.EndProcessing 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 afsluitfout optreedt in een deel van de cmdlet. Daarom moet de .NET Framework-klasse voor een cmdlet waarvoor objectopruiming is vereist, het volledige interfacepatroon System.IDisposable 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.

Serialisatievriendelijke parametertypen (AC05) gebruiken

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

Primitieve typen:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 en UInt64.
• Booleaanse waarde, Guid, Byte[], TimeSpan, DateTime, Uri en Version.
• Teken, tekenreeks, XmlDocument.

Ingebouwde rehydratabeltypen:

• 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)

Bij het verwerken van gevoelige gegevens wordt altijd het gegevenstype System.Security.SecureString gebruikt. Dit kan pijplijninvoer bevatten voor parameters, evenals het retourneren van gevoelige gegevens aan de pijplijn.

Hoewel .NET het gebruik van SecureString voor nieuwe ontwikkeling aanbeveelt, blijft PowerShell ondersteuning bieden voor de SecureString-klasse voor achterwaartse compatibiliteit. Het gebruik van een SecureString is nog steeds veiliger dan het gebruik van een tekenreeks zonder opmaak. PowerShell is nog steeds afhankelijk van het Type SecureString om te voorkomen dat de inhoud per ongeluk beschikbaar wordt in de console of in logboeken. Gebruik SecureString zorgvuldig, omdat deze eenvoudig kan worden geconverteerd naar een tekenreeks zonder opmaak. Zie de system.Security.SecureString-klassedocumentatie voor een volledige discussie over het gebruik van SecureString.

Zie ook

Vereiste richtlijnen voor ontwikkeling

sterk aangemoedigde ontwikkelingsrichtlijnen

Een Windows PowerShell-cmdlet schrijven