Vytvoření rutiny bez parametrů

Článek
09/27/2021

Tato část popisuje, jak vytvořit rutinu, která načte informace z místního počítače bez použití parametrů a pak tyto informace zapíše do kanálu. Zde popsaná rutina je 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

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

Pojmenování rutiny

Název rutiny se skládá z operace, která označuje akci, kterou rutina přijímá, a podstatného jména, které označuje položky, se kterými rutina pracuje. Vzhledem k tomu, že tato ukázková rutina Get-Proc načte objekty procesu, používá příkaz Get definovaný výčtem System.Management.Automation.Verbscommon a podstatné jméno "Proc", které 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 singelární podstatné jméno s předponou zkrácené verze názvu produktu. Příklad názvu rutiny tohoto typu je Get-SQLServer .

Volba slovesa

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

Definování třídy rutiny

Po zvolení názvu rutiny definujte třídu .NET pro implementaci rutiny. Tady je definice třídy pro tuto ukázkovou rutinu Get-Proc:

[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 k identifikaci této třídy jako rutiny používá atribut System.Management.Automation.CmdletAttribute se [Cmdlet(verb, noun, ...)] syntaxí . Toto je jediný povinný atribut pro všechny rutiny a umožňuje modulu runtime Windows PowerShell je správně volat. Pokud je to potřeba, můžete nastavit klíčová slova atributu pro další deklaraci třídy. Uvědomte si, že deklarace atributu pro naši ukázkovou třídu GetProcCommand deklaruje pouze názvy podstatného jména a slovesa Get-Proc rutinu.

Poznámka

U všech Windows PowerShell atributů klíčová slova, která můžete nastavit, odpovídají vlastnostem třídy atributu.

Při pojmenování třídy rutiny je vhodné v názvu třídy odrážet název rutiny. Použijte k tomu tvar "VerbNounCommand" a nahraďte "Sloveso" a "Podstatné jméno" slovesem a podstatné jméno použitým v názvu rutiny. Jak je znázorněno v předchozí definici třídy, ukázková rutina Get-Proc definuje třídu s názvem GetProcCommand, která je odvozená ze základní třídy System.Management.Automation.Cmdlet.

Důležité

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

Poznámka

Třída pro rutinu 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 nebude nalezeny Windows PowerShell runtime.

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

Přepsání metody vstupního zpracování

Třída System.Management.Automation.Cmdlet poskytuje tři hlavní metody zpracování vstupu, z nichž alespoň jedna musí přepsat vaši rutinu. Další informace o tom, jak Windows PowerShell záznamy, najdete v tématu How Windows PowerShell Works.

Pro všechny typy vstupů volá modul runtime Windows PowerShell System.Management.Automation.Cmdlet.BeginProcessing, aby umožnil zpracování. Pokud vaše rutina musí provést určité předběžné zpracování nebo nastavení, může to provést 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 volání rutiny.

Pokud vaše rutina přijímá vstup kanálu, musí přepsat metodu System.Management.Automation.Cmdlet.ProcessRecord a volitelně metodu System.Management.Automation.Cmdlet.EndProcessing. Rutina může například přepsat obě metody, pokud shromáždí všechny vstupy pomocí System.Management.Automation.Cmdlet.ProcessRecord, a pak funguje na vstupu jako celek, nikoli po jednom prvku, jak to dělá Sort-Object rutina.

Pokud vaše rutina nepřistupuje ke vstupu 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 pracovat současně s jedním prvkem, jako je tomu u rutiny řazení.

Vzhledem k tomu, že tato ukázková rutina Get-Proc musí přijímat vstup kanálu, přepíše metodu System.Management.Automation.Cmdlet.ProcessRecord a používá výchozí implementace pro System.Management.Automation.Cmdlet.BeginProcessing a System.Management.Automation.Cmdlet.EndProcessing. Přepsání System.Management.Automation.Cmdlet.ProcessRecord 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 třeba si zapamatovat o zpracování vstupu

Výchozím zdrojem pro vstup je explicitní objekt (například řetězec), který poskytuje uživatel na příkazovém řádku. Další informace najdete v tématu Vytvoření rutiny pro zpracování vstupu příkazového řádku.
Metoda zpracování vstupu může také přijímat vstupy z výstupního objektu upstreamové rutiny v kanálu. Další informace najdete v tématu Vytvoření rutiny pro zpracování vstupu kanálu. Uvědomte si, že vaše rutina může přijímat vstupy z kombinace příkazového řádku a zdrojů kanálu.
Rutina podřízeného serveru se nemusí vrátit po dlouhou dobu nebo vůbec. Z tohoto důvodu by metoda zpracování vstupu ve vaší rutině neměla během volání metody System.Management.Automation.Cmdlet.WriteObjectuchovat zámky, zejména zámky, pro které obor přesahuje instanci rutiny.

Důležité

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

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

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

Vzorek kódu

Kompletní vzorový kód jazyka C# najdete v části Ukázka GetProcessSample01.

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

Windows PowerShell předá informace mezi rutinami pomocí objektů .NET. V důsledku toho může rutina potřebovat definovat vlastní typ nebo může potřebovat rozšířit existující typ poskytovaný jinou rutinou. Další informace o definování nových typů nebo rozšíření existujících typů najdete v tématu Rozšíření typů objektůa formátování .

Sestavení rutiny

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

Testování rutiny

Když je vaše rutina zaregistrovaná v Windows PowerShell, 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 přesto používá modul runtime Windows PowerShell a existující objekt .NET, což je dostačující k tomu, aby byl užitečný. Pojďme ho otestovat, abychom lépe pochopili, co Get-Proc a jak lze jeho výstup použít. Další informace o používání rutin z příkazového řádku najdete v tématu Začínáme s Windows PowerShell.

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

get-proc