Een cmdlet maken zonder parameters

In deze sectie wordt beschreven hoe u een cmdlet maakt die informatie ophaalt van de lokale computer zonder parameters en vervolgens de informatie naar de pijplijn schrijft. De cmdlet die hier wordt beschreven, is een Get-Proc cmdlet die informatie over de processen van de lokale computer ophaalt en die informatie vervolgens weergeeft op de opdrachtregel.

Notitie

Houd er rekening mee dat bij het schrijven van cmdlets de Windows PowerShell-referentieassembly's® op schijf worden gedownload (standaard bij C:\Program Files\Reference Assembly's\Microsoft\WindowsPowerShell\v1.0). Ze worden niet geïnstalleerd in de Global Assembly Cache (GAC).

De cmdlet een naam geven

Een cmdlet-naam bestaat uit een werkwoord dat de actie aangeeft die de cmdlet uitvoert en een zelfstandig naamwoord dat de items aangeeft waarop de cmdlet werkt. Omdat deze voorbeeld-Get-Proc cmdlet procesobjecten ophaalt, wordt de term 'Get' gebruikt, gedefinieerd door de System.Management.Automation.VerbsCommon opsomming en het zelfstandig naamwoord Proc om aan te geven dat de cmdlet werkt op procesitems.

Gebruik bij het benoemen van cmdlets geen van de volgende tekens: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Een zelfstandig naamwoord kiezen

Kies een zelfstandig naamwoord dat specifiek is. U kunt het beste een enkel zelfstandig naamwoord gebruiken dat is voorafgegaan door een verkorte versie van de productnaam. Een voorbeeld van de cmdlet-naam van dit type is 'Get-SQLServer'.

Een werkwoord kiezen

U moet een werkwoord gebruiken uit de set goedgekeurde cmdlet-werkwoordnamen. Zie Cmdlet Verb Namesvoor meer informatie over de goedgekeurde cmdlet-werkwoorden.

De cmdlet-klasse definiëren

Zodra u een cmdlet-naam hebt gekozen, definieert u een .NET-klasse om de cmdlet te implementeren. Dit is de klassedefinitie voor deze voorbeeld-Get-Proc cmdlet:

[Cmdlet(VerbsCommon.Get, "Proc")]
  public class GetProcCommand : Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Zoals u ziet, wordt het kenmerk System.Management.Automation.CmdletAttribute, met de syntaxis [Cmdlet(verb, noun, ...)], gebruikt om deze klasse als cmdlet te identificeren. Dit is het enige vereiste kenmerk voor alle cmdlets en stelt de Windows PowerShell-runtime in staat om ze correct aan te roepen. U kunt kenmerktrefwoorden zo nodig instellen om de klasse verder te declareren. Houd er rekening mee dat de kenmerkdeclaratie voor de GetProcCommand-klasse alleen de naamwoord- en werkwoordnamen voor de Get-Proc-cmdlet declareert.

Notitie

Voor alle Windows PowerShell-kenmerkklassen zijn de trefwoorden die u kunt instellen, overeenkomen met de eigenschappen van de kenmerkklasse.

Wanneer u de klasse van de cmdlet een naam geeft, is het een goed idee om de naam van de cmdlet in de klassenaam weer te geven. Hiervoor gebruikt u het formulier 'VerbNounCommand' en vervangt u 'Werkwoord' en 'Zelfstandig naamwoord' door het werkwoord en zelfstandig naamwoord dat in de naam van de cmdlet wordt gebruikt. Zoals wordt weergegeven in de vorige klassedefinitie, definieert de voorbeeld-Get-Proc cmdlet een klasse met de naam GetProcCommand, die is afgeleid van de System.Management.Automation.Cmdlet basisklasse.

Belangrijk

Als u een cmdlet wilt definiëren die rechtstreeks toegang heeft tot de Windows PowerShell-runtime, moet uw .NET-klasse worden afgeleid van de System.Management.Automation.PSCmdlet basisklasse. Zie Een cmdlet maken die parametersetsdefinieert voor meer informatie over deze klasse.

Notitie

De klasse voor een cmdlet moet expliciet als openbaar worden gemarkeerd. Klassen die niet als openbaar zijn gemarkeerd, worden standaard ingesteld op intern en worden niet gevonden door de Windows PowerShell-runtime.

Windows PowerShell maakt gebruik van de Microsoft.PowerShell.Commands naamruimte voor de bijbehorende cmdlet-klassen. Het is raadzaam om uw cmdlet-klassen in een opdrachtnaamruimte van uw API-naamruimte te plaatsen, bijvoorbeeld xxx.PS. Opdrachten.

Een invoerverwerkingsmethode overschrijven

De System.Management.Automation.Cmdlet klasse biedt drie belangrijke invoerverwerkingsmethoden, waarvan ten minste één moet worden overschreven door uw cmdlet. Zie Hoe Windows PowerShell werktvoor meer informatie over hoe Windows PowerShell records verwerkt.

Voor alle typen invoer roept de Windows PowerShell-runtime System.Management.Automation.Cmdlet.BeginProcessing aan om verwerking mogelijk te maken. Als uw cmdlet een aantal voorverwerking of installatie moet uitvoeren, kan dit door deze methode te overschrijven.

Notitie

Windows PowerShell gebruikt de term 'record' om de set parameterwaarden te beschrijven die worden opgegeven wanneer een cmdlet wordt aangeroepen.

Als uw cmdlet pijplijninvoer accepteert, moet deze de methode System.Management.Automation.Cmdlet.ProcessRecord en eventueel de methode System.Management.Automation.Cmdlet.EndProcess ing overschrijven. Een cmdlet kan bijvoorbeeld beide methoden overschrijven als deze alle invoer verzamelt met behulp van System.Management.Automation.Cmdlet.ProcessRecord en vervolgens werkt op de invoer als geheel in plaats van één element tegelijk, zoals de Sort-Object cmdlet wel doet.

Als uw cmdlet geen pijplijninvoer accepteert, moet deze de methode System.Management.Automation.Cmdlet.EndProcessing overschrijven. Houd er rekening mee dat deze methode vaak wordt gebruikt in plaats van System.Management.Automation.Cmdlet.BeginProcessing wanneer de cmdlet niet op één element tegelijk kan werken, zoals het geval is bij een sorteer-cmdlet.

Omdat deze voorbeeld-Get-Proc cmdlet pijplijninvoer moet ontvangen, overschrijft deze de methode System.Management.Automation.Cmdlet.ProcessRecord en worden de standaard implementaties gebruikt voor System.Management.Automation.Cmdlet.BeginProcessing en System.Management.Automation.Cmdlet.EndProcessing. De System.Management.Automation.Cmdlet.ProcessRecord overschrijven haalt processen op en schrijft deze naar de opdrachtregel met behulp van de methode System.Management.Automation.Cmdlet.WriteObject.

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}

Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Dingen die u moet onthouden over invoerverwerking

De standaardbron voor invoer is een expliciet object (bijvoorbeeld een tekenreeks) dat wordt geleverd door de gebruiker op de opdrachtregel. Zie Een cmdlet maken voor het verwerken van opdrachtregelinvoervoor meer informatie.
Een invoerverwerkingsmethode kan ook invoer ontvangen van het uitvoerobject van een upstream-cmdlet in de pijplijn. Zie Een cmdlet maken voor het verwerken van pijplijninvoervoor meer informatie. Houd er rekening mee dat uw cmdlet invoer kan ontvangen van een combinatie van opdrachtregel- en pijplijnbronnen.
De downstream-cmdlet retourneert mogelijk niet lang of helemaal niet. Daarom mag de invoerverwerkingsmethode in uw cmdlet geen vergrendelingen bevatten tijdens aanroepen naar System.Management.Automation.Cmdlet.WriteObject, met name vergrendelingen waarvoor het bereik buiten het cmdlet-exemplaar valt.

Belangrijk

Cmdlets mogen nooit System.Console.Writeline* of het equivalent daarvan aanroepen.

Uw cmdlet kan objectvariabelen hebben om op te schonen wanneer de verwerking is voltooid (bijvoorbeeld als er een bestandsgreep wordt geopend in de System.Management.Automation.Cmdlet.BeginProcessing methode en de ingang geopend blijft voor gebruik door System.Management.Automation.Cmdlet.ProcessRecord). Het is belangrijk te onthouden dat de Windows PowerShell-runtime niet altijd de System.Management.Automation.Cmdlet.EndProcessing methode aanroept, die objectopruiming moet uitvoeren.

System.Management.Automation.Cmdlet.EndProcessing kan bijvoorbeeld niet worden aangeroepen als de cmdlet halverwege wordt geannuleerd of als er een afsluitfout optreedt in een deel van de cmdlet. Daarom moet een cmdlet waarvoor objectopruiming is vereist, het volledige System.IDisposable patroon implementeren, inclusief de finalizer, zodat de runtime zowel System.Management.Automation.Cmdlet.EndProcessing als System.IDisposable.Dispose* aan het einde van de verwerking kan aanroepen.

Codevoorbeeld

Zie GetProcessSample01 Samplevoor de volledige C#-voorbeeldcode.

Objecttypen en -opmaak definiëren

Windows PowerShell geeft informatie door tussen cmdlets met behulp van .NET-objecten. Daarom moet een cmdlet mogelijk een eigen type definiëren of moet de cmdlet mogelijk een bestaand type uitbreiden dat door een andere cmdlet wordt geleverd. Zie Objecttypen en Opmaak uitbreidenvoor meer informatie over het definiëren van nieuwe typen of het uitbreiden van bestaande typen.

De cmdlet bouwen

Nadat u een cmdlet hebt geïmplementeerd, moet u deze registreren bij Windows PowerShell via een Windows PowerShell-module. Zie Cmdlets, providers en hosttoepassingen registrerenvoor meer informatie over het registreren van cmdlets.

De cmdlet testen

Wanneer uw cmdlet is geregistreerd bij Windows PowerShell, kunt u deze testen door deze uit te voeren op de opdrachtregel. De code voor onze voorbeeld-Get-Proc cmdlet is klein, maar maakt nog steeds gebruik van de Windows PowerShell-runtime en een bestaand .NET-object, wat voldoende is om het nuttig te maken. Laten we het testen om beter te begrijpen wat Get-Proc kan doen en hoe de uitvoer ervan kan worden gebruikt. Zie de Aan de slag met Windows PowerShellvoor meer informatie over het gebruik van cmdlets vanaf de opdrachtregel.

Start Windows PowerShell en haal de huidige processen op de computer op.

Get-Proc