Een cmdlet maken zonder parameters

Artikel
09/27/2021
8 minuten om te lezen

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

Notitie

Wanneer u cmdlets schrijft, worden de Windows PowerShell®-referentieassemblage's gedownload naar schijf (standaard C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Ze worden niet geïnstalleerd in de Global Assembly Cache (GAC).

De cmdlet een naam geven

De naam van een cmdlet bestaat uit een werkwoord dat de actie aangeeft die de cmdlet onderneemt en een zelfstandig naamwoord dat de items aangeeft waarop de cmdlet werkt. Omdat met deze voorbeeld-Get-Proc-cmdlet procesobjecten worden opgehaald, wordt het werkwoord 'Get' gebruikt, gedefinieerd door de system.Management.Automation.Verbscommon-enumeratie, 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 specifiek zelfstandig naamwoord. U kunt het beste een zelfstandig naamwoord met het voorvoegsel gebruiken met een verkorte versie van de productnaam. Een voorbeeld van een cmdlet-naam van dit type is " Get-SQLServer ".

Een werkwoord kiezen

Gebruik een werkwoord uit de set goedgekeurde cmdlet werkwoordnamen. Zie Cmdlet Werkwoordnamen voor meer informatie over de goedgekeurde cmdlet-woorden.

De cmdlet-klasse definiëren

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

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

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

U ziet dat voor de klassedefinitie het kenmerk System.Management.Automation.CmdletAttribute, met de syntaxis , wordt gebruikt om deze klasse als [Cmdlet(verb, noun, ...)] cmdlet te identificeren. Dit is het enige vereiste kenmerk voor alle cmdlets en het stelt de Windows PowerShell runtime in staat om deze correct aan te roepen. U kunt kenmerktrefwoorden zo nodig instellen om de klasse verder te declareer. Let erop dat de kenmerkdeclaratie voor onze getproccommand-voorbeeldklasse alleen de naamwoorden en werkwoordnamen voor de Get-Proc-cmdlet declareren.

Notitie

Voor alle Windows PowerShell kenmerkklassen komen de trefwoorden die u kunt instellen overeen met de eigenschappen van de kenmerkklasse.

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

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 basisklasse System.Management.Automation.PSCmdlet. Zie Creating a Cmdlet that Defines Parameter Sets (Een cmdlet maken die parametersets definieert) voor meer informatie over deze klasse.

Notitie

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

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

Een invoerverwerkingsmethode overschrijven

De klasse System.Management.Automation.Cmdlet biedt drie belangrijke invoerverwerkingsmethoden, waarvan ten minste één door de cmdlet moet worden overgenomen. Zie How Windows PowerShell Works (Hoe Windows PowerShell werkt) voor meer informatie over hoe Windows PowerShell verwerkt.

Voor alle typen invoer roept de Windows PowerShell System.Management.Automation.Cmdlet.BeginProcessing aan om verwerking mogelijk te maken. Als uw cmdlet een voorverwerking of installatie moet uitvoeren, kan dit worden doen 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.EndProcessing overschrijven. Een cmdlet kan bijvoorbeeld beide methoden overschrijven als alle invoer wordt verzameld met behulp van System.Management.Automation.Cmdlet.ProcessRecord en vervolgens als geheel werkt op de invoer in plaats van één element tegelijk, zoals de Sort-Object cmdlet dat doet.

Als uw cmdlet geen pijplijninvoer gebruikt, moet deze de methode System.Management.Automation.Cmdlet.EndProcessing overschrijven. Deze methode wordt vaak gebruikt in plaats van System.Management.Automation.Cmdlet.BeginProcessing wanneer de cmdlet niet kan worden gebruikt op één element tegelijk, zoals het geval is voor een sorteer-cmdlet.

Omdat deze voorbeeld-Get-Proc-cmdlet pijplijninvoer moet ontvangen, overschrijven ze 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. System.Management.Automation.Cmdlet.ProcessRecord overschrijven processen en schrijft ze naar de opdrachtregel met behulp van de system.Management.Automation.Cmdlet.WriteObject-methode.

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 om te onthouden over invoerverwerking

De standaardbron voor invoer is een expliciet object (bijvoorbeeld een tekenreeks) dat door de gebruiker wordt geleverd op de opdrachtregel. Zie Creating a Cmdlet to Process Command Line Input (Een cmdlet maken om opdrachtregelinvoer te verwerken) voor meer informatie.
Een invoerverwerkingsmethode kan ook invoer ontvangen van het uitvoerobject van een upstream-cmdlet in de pijplijn. Zie Creating a Cmdlet to Process Pipeline Input (Een cmdlet maken om pijplijninvoer te verwerken) voor meer informatie. Let erop dat uw cmdlet invoer kan ontvangen van een combinatie van opdrachtregel- en pijplijnbronnen.
De downstream-cmdlet retourneerde mogelijk niet lang of helemaal niet. Daarom mag de invoerverwerkingsmethode in uw cmdlet geen vergrendelingen hebben tijdens aanroepen naar System.Management.Automation.Cmdlet.WriteObject,met name vergrendelingen waarvoor het bereik verder gaat dan het cmdlet-exemplaar.

Belangrijk

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

Uw cmdlet kan objectvariabelen hebben om op te schonen wanneer de verwerking is voltooid (bijvoorbeeld als er een bestandsing handle wordt geopend in de system.Management.Automation.Cmdlet.BeginProcessing-methode en de greep geopend houdt voor gebruik door System.Management.Automation.Cmdlet.ProcessRecord). Het is belangrijk te onthouden dat de Windows PowerShell runtime niet altijd de methode System.Management.Automation.Cmdlet.EndProcessing aanroept, waarmee objectopschoning moet worden uitgevoerd.

System.Management.Automation.Cmdlet.EndProcessing kan bijvoorbeeld niet worden aangeroepen als de cmdlet halverwege wordt geannuleerd of als er een beëindigingsfout optreedt in een deel van de cmdlet. Daarom moet een cmdlet die objectopschoning 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 wordt geleverd door een andere cmdlet. Zie Extending Object Types and Formatting (Objecttypen uitbreiden en opmaak) voor 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 Windows PowerShell via Windows PowerShell module. Zie Cmdlets, providers en hosttoepassingen registreren voor 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 Get-Proc-cmdlet is klein, maar maakt nog steeds gebruik van de Windows PowerShell-runtime en een bestaand .NET-object, wat voldoende is om dit nuttig te maken. Laten we het testen om beter te begrijpen wat Get-Proc kunnen doen en hoe de uitvoer ervan kan worden gebruikt. Zie de Aan de slag met Windows PowerShell voor meer informatie over het gebruik van cmdlets vanaf de opdrachtregel.

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

get-proc