Vytvoření rutiny bez parametrů

Tato část popisuje, jak vytvořit rutinu, která načítá informace z místního počítače bez použití parametrů, a pak zapíše informace do kanálu. Zde popsaná rutina je rutina Get-Proc, která načte informace o procesech místního počítače a pak tyto informace zobrazí na příkazovém řádku.

Poznámka:

Mějte na paměti, že při psaní rutin se referenční sestavení prostředí Windows PowerShell® stáhnou na disk (ve výchozím nastavení je to C:\Program Files\Reference Assemblyes\Microsoft\WindowsPowerShell\v1.0). Nejsou nainstalovány v globální mezipaměti sestavení (GAC).

Pojmenování rutiny

Název rutiny se skládá z příkazu, který označuje akci, kterou rutina provede, a podstatné jméno označující položky, na které rutina působí. Vzhledem k tomu, že tato ukázková Get-Proc rutina načítá objekty procesu, používá příkaz "Get", definovaný System.Management.Automation.VerbsCommon výčtu a podstatné jméno "Proc" označuje, že rutina pracuje s položkami procesu.

Při pojmenování rutin nepoužívejte žádný z následujících znaků: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Volba podstatného jména

Měli byste zvolit podstatné jméno, které je specifické. Nejlepší je použít jednodávné jméno s předponou zkrácené verze názvu produktu. Příklad názvu rutiny tohoto typu je "Get-SQLServer".

Výběr příkazu

Měli byste použít příkaz ze sady schválených názvů příkazů rutin. Další informace o schválených příkazech rutin najdete v tématu Názvy sloves rutin.

Definování třídy rutiny

Jakmile zvolíte název rutiny, definujte třídu .NET pro implementaci rutiny. Tady je definice třídy pro tuto ukázkovou Get-Proc rutinu:

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

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

Všimněte si, že před definicí třídy se atribut System.Management.Automation.CmdletAttribute s syntaxí [Cmdlet(verb, noun, ...)]slouží k identifikaci této třídy jako rutiny. Toto je jediný povinný atribut pro všechny rutiny a umožňuje, aby modul runtime Windows PowerShellu volal správně. V případě potřeby můžete nastavit klíčová slova atributů pro další deklaraci třídy. Mějte na paměti, že deklarace atributu pro naši ukázkovou GetProcCommand třída deklaruje pouze názvy podstatných jmen a sloves pro rutinu Get-Proc.

Poznámka:

Pro všechny třídy atributů Windows PowerShellu můžou klíčová slova, která můžete nastavit, odpovídají vlastnostem třídy atributu.

Při pojmenování třídy rutiny je vhodné odrážet název rutiny v názvu třídy. Uděláte to tak, že použijete tvar SlovesnýnCommand a nahradíte sloveso a podstatné jméno sloveso a podstatné jméno použité v názvu rutiny. Jak je znázorněno v předchozí definici třídy, ukázková Get-Proc rutina definuje třídu s názvem GetProcCommand, která je odvozena od System.Management.Automation.Cmdlet základní třídy.

Důležité

Pokud chcete definovat rutinu, která přistupuje k modulu runtime Windows PowerShellu přímo, měla by vaše třída .NET odvodit ze třídy System.Management.Automation.PSCmdlet základní třídy. Další informace o této třídě naleznete v tématu Vytvoření rutiny, která definuje sady parametrů.

Poznámka:

Třída rutiny musí být explicitně označena jako veřejná. Třídy, které nejsou označené jako veřejné, budou ve výchozím nastavení interní a nebudou nalezeny modulem runtime Prostředí Windows PowerShell.

Windows PowerShell používá pro své třídy rutin Microsoft.PowerShell.Commands obor názvů. Doporučujeme umístit třídy rutin do oboru názvů Příkazů vašeho oboru názvů rozhraní API, například xxx.PS. Příkazy.

Přepsání metody zpracování vstupu

Třída System.Management.Automation.Cmdlet poskytuje tři hlavní metody zpracování vstupu, z nichž nejméně jedna musí přepsat vaši rutinu. Další informace o tom, jak Windows PowerShell zpracovává záznamy, naleznete v tématu Jak windows PowerShell funguje.

Pro všechny typy vstupu volá modul runtime Prostředí Windows PowerShell System.Management.Automation.Cmdlet.BeginProcessing pro povolení zpracování. Pokud vaše rutina musí provést některé předběžné zpracování nebo nastavení, může to udělat přepsáním této metody.

Poznámka:

Windows PowerShell používá termín "záznam" k popisu sady hodnot parametrů zadaných při zavolání rutiny.

Pokud vaše rutina přijímá vstup kanálu, musí přepsat System.Management.Automation.Rutin.ProcessRecord metoda a volitelně System.Management.Automation.Cmdlet.EndProcessing metoda. Rutina může například přepsat obě metody, pokud shromáždí všechny vstupy pomocí System.Management.Automation.ProcessRecord a pak pracuje se vstupem jako celek, nikoli s jedním prvkem najednou, jak to dělá rutina Sort-Object.

Pokud vaše rutina nepřebere vstup kanálu, měla by přepsat metodu System.Management.Automation.Cmdlet.EndProcessing. Uvědomte si, že tato metoda se často používá místo System.Management.Automation.Cmdlet.BeginProcessing, když rutina nemůže současně pracovat s jedním prvkem, stejně jako u rutiny řazení.

Vzhledem k tomu, že tato ukázková rutina Get-Proc musí přijímat vstup kanálu, přepisuje metodu System.Management.Automation.ProcessRecord a používá výchozí implementace pro System.Management.Automation.Cmdlet.BeginProcessing a System.Management.Automation.Cmdlet.EndProcessing. System.Management.Automation.Cmdlet.ProcessRecord přepsání načte procesy a zapíše je do příkazového řádku pomocí metody 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

Co je potřeba pamatovat na zpracování vstupu

Výchozí zdroj pro vstup je explicitní objekt (například řetězec) poskytnutý uživatelem na příkazovém řádku. Další informace naleznete v tématu Vytvoření rutiny pro zpracování vstupu příkazového řádku.
Metoda zpracování vstupu může také přijímat vstup z výstupního objektu upstreamové rutiny v kanálu. Další informace naleznete v tématu Vytvoření rutiny pro zpracování vstupu kanálu. Mějte na paměti, že vaše rutina může přijímat vstupy z kombinace zdrojů příkazového řádku a kanálu.
Podřízená rutina se nemusí dlouho vracet nebo nemusí vůbec. Z tohoto důvodu by metoda zpracování vstupu v rutině neměla uchovávat zámky během volání System.Management.Automation.Automation.WriteObject, zejména zámky, pro které rozsah přesahuje instanci rutiny.

Důležité

Rutiny by nikdy neměly volat System.Console.Writeline* nebo jeho ekvivalent.

Vaše rutina může mít proměnné objektů, které se mají po dokončení zpracování vyčistit (například pokud otevře popisovač souboru v metodě System.Management.Automation.Cmdlet.BeginProcess ing a udržuje popisovač otevřený pro použití System.Management.Automation.Cmdlet.ProcessRecord). Je důležité si uvědomit, že modul runtime prostředí Windows PowerShell nevolá vždy metodu System.Management.Automation.Cmdlet.EndProcessing, která by měla provádět čištění objektů.

Například System.Management.Automation.Cmdlet.EndProcessing nemusí být volána, pokud je rutina zrušena uprostřed nebo pokud dojde k ukončovací chybě v jakékoli části rutiny. Rutina, která vyžaduje vyčištění objektu, by proto měla implementovat úplný vzor System.IDisposable, včetně finalizátoru, aby modul runtime mohl volat System.Management.Automation.Cmdlet.EndProcessing a System.IDisposable.Dispose* na konci zpracování.

Ukázka kódu

Úplný vzorový kód jazyka C# najdete v tématu GetProcessSample01 Sample.

Definování typů objektů a formátování

Windows PowerShell předává informace mezi rutinami pomocí objektů .NET. Proto může být potřeba, aby rutina definovala vlastní typ, nebo může být potřeba rozšířit existující typ poskytovaný jinou rutinou. Další informace o definování nových typů nebo rozšíření existujících typů naleznete v tématu Rozšíření typů objektů a formátování.

Sestavení rutiny

Po implementaci rutiny ji musíte zaregistrovat ve Windows PowerShellu prostřednictvím modulu snap-in Prostředí Windows PowerShell. Další informace o registraci rutin naleznete v tématu Postup registrace rutin, poskytovatelů a hostitelských aplikací.

Testování rutiny

Když je vaše rutina zaregistrovaná ve Windows PowerShellu, můžete ji otestovat spuštěním na příkazovém řádku. Kód pro naši ukázkovou rutinu Get-Proc je malý, ale stále používá modul runtime Prostředí Windows PowerShell a existující objekt .NET, který stačí k tomu, aby byl užitečný. Pojďme to otestovat, abychom lépe pochopili, co Get-Proc může dělat a jak se dá použít jeho výstup. Další informace o používání rutin z příkazového řádku najdete v tématu Začínáme s prostředím Windows PowerShell.

Spusťte Windows PowerShell a získejte aktuální procesy spuštěné v počítači.

Get-Proc