about_Functions_Advanced_Methods

Krátký popis

Popisuje, jak funkce, které určují CmdletBinding atribut, můžou používat metody a vlastnosti, které jsou k dispozici pro kompilované rutiny.

Dlouhý popis

Funkce, které určují CmdletBinding atribut, mají přístup k mnoha metodám a vlastnostem $PSCmdlet prostřednictvím proměnné. Mezi tyto metody patří následující metody:

  • Metody zpracování vstupu, které kompilované rutiny používají k práci.
  • Metody ShouldProcess , ShouldContinue které slouží k získání zpětné vazby uživatelů před provedením akce.
  • Metoda ThrowTerminatingError generování záznamů chyb.
  • Několik Write metod, které vrací různé typy výstupu.

Pro pokročilé funkce jsou k dispozici všechny metody a vlastnosti třídy PSCmdlet . Další informace naleznete v tématu System.Management.Automation.PSCmdlet.

Další informace o atributu CmdletBinding najdete v tématu about_Functions_CmdletBindingAttribute. Pro RutinBindingAttribute třída, viz System.Management.Automation.Rutin.RutinBindingAttribute.

Metody zpracování vstupu

Metody popsané v této části se označují jako metody zpracování vstupu. Pro funkce jsou tyto tři metody reprezentovány Begin, Processa End bloky funkce. Ve svých funkcích nemusíte používat žádný z těchto bloků.

Poznámka

Tyto bloky jsou také dostupné pro funkce, které tento atribut nepoužívají CmdletBinding .

Začátek

Tento blok slouží k poskytování volitelného jednorázového předběžného zpracování funkce. Modul runtime PowerShellu používá kód v tomto bloku jednou pro každou instanci funkce v kanálu.

Proces

Tento blok slouží k poskytování zpracování záznamů podle záznamů pro funkci. Blok můžete použít Process bez definování ostatních bloků. Počet Process spuštění bloku závisí na tom, jak funkci používáte a jaký vstup funkce přijímá.

Automatická proměnná $_ nebo $PSItem obsahuje aktuální objekt v kanálu pro použití v Process bloku. Automatická $input proměnná obsahuje výčet, který je dostupný pouze pro funkce a bloky skriptů. Další informace najdete v tématu about_Automatic_Variables.

  • Volání funkce na začátku nebo mimo kanál spustí Process blok jednou.
  • V rámci kanálu Process se blok spustí jednou pro každý vstupní objekt, který dosáhne funkce.
  • Pokud je vstup kanálu, který dosáhne funkce, prázdný, Process blok se nespustí .
    • Bloky Begin se End pořád spouštějí.

Důležité

Pokud je parametr funkce nastavený tak, aby přijímal vstup kanálu a Process blok není definován, zpracování záznamů podle záznamů selže. V tomto případě se vaše funkce spustí jenom jednou bez ohledu na vstup.

End

Tento blok slouží k poskytování volitelného jednorázového zpracování funkce.

Následující příklad ukazuje přehled funkce, která obsahuje Begin blok pro jednorázové předběžné zpracování, Process blok pro zpracování více záznamů a End blok pro jednorázové zpracování po zpracování.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

Poznámka

Použití nebo BeginEnd bloku vyžaduje, abyste definovali všechny tři bloky. Při použití všech tří bloků musí být veškerý kód PowerShellu uvnitř jednoho z bloků.

Metody potvrzení

Měl by zpracovat

Tato metoda se volá k vyžádání potvrzení od uživatele před provedením akce, která by změnila systém. Funkce může pokračovat na základě logické hodnoty vrácené metodou. Tuto metodu lze volat pouze z Process{} bloku funkce. Atribut CmdletBinding musí také deklarovat, že funkce podporuje ShouldProcess (jak je znázorněno v předchozím příkladu).

Další informace o této metodě naleznete v tématu System.Management.Automation.Rutin.ShouldProcess.

Další informace o tom, jak požádat o potvrzení, najdete v tématu Žádost o potvrzení.

ShouldContinue

Tato metoda se volá k vyžádání druhé potvrzovací zprávy. Měla by se volat, když ShouldProcess metoda vrátí $true. Další informace o této metodě naleznete v tématu System.Management.Automation.Rutin.ShouldContinue.

Metody chyb

Funkce můžou při výskytu chyb volat dvě různé metody. Pokud dojde k nedokončující chybě, měla by funkce volat metodu WriteError , která je popsaná v Write části metody. Pokud dojde k ukončovací chybě a funkce nemůže pokračovat, měla by volat metodu ThrowTerminatingError . Můžete také použít Throw příkaz pro ukončování chyb a rutinu Write-Error pro nekončující chyby.

Další informace naleznete v tématu System.Management.Automation.Cmdlet.ThrowTerminatingError.

Metody zápisu

Funkce může volat následující metody pro vrácení různých typů výstupu. Všimněte si, že ne veškerý výstup přejde na další příkaz v kanálu. Můžete také použít různé Write rutiny, například Write-Error.

WriteCommandDetail

Informace o WriteCommandDetails metodě naleznete v tématu System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Pokud chcete poskytnout informace, které lze použít k řešení potíží s funkcí, zavolejte metodu WriteDebug . Metoda WriteDebug zobrazí uživatelům ladicí zprávy. Další informace najdete v tématu System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Funkce by měly tuto metodu volat, když dojde k nekončovacím chybám a funkce je navržená tak, aby pokračovala ve zpracování záznamů. Další informace naleznete v tématu System.Management.Automation.Cmdlet.WriteError.

Poznámka

Pokud dojde k ukončovací chybě, měla by funkce volat metodu ThrowTerminatingError .

WriteObject

Metoda WriteObject umožňuje funkci odeslat objekt na další příkaz v kanálu. Ve většině případů je metoda, která se má použít, WriteObject když funkce vrátí data. Další informace naleznete v tématu System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

U funkcí s akcemi, které trvá dlouhou dobu dokončení, tato metoda umožňuje funkci volat metodu WriteProgress tak, aby se zobrazily informace o průběhu. Můžete například zobrazit procento dokončení. Další informace naleznete v tématu System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Pokud chcete poskytnout podrobné informace o tom, co funkce dělá, zavolejte metodu WriteVerbose k zobrazení podrobných zpráv uživateli. Ve výchozím nastavení se podrobné zprávy nezobrazují. Další informace naleznete v tématu System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Pokud chcete poskytnout informace o podmínkách, které mohou způsobit neočekávané výsledky, zavolejte funkci WriteWarning metodu pro zobrazení upozornění zpráv uživateli. Ve výchozím nastavení se zobrazují zprávy s upozorněním. Další informace naleznete v tématu System.Management.Automation.PSCmdlet.WriteWarning.

Poznámka

Upozornění můžete také zobrazit konfigurací proměnné nebo pomocí VerboseDebug možností příkazového $WarningPreference řádku. Další informace o $WarningPreference proměnné najdete v tématu about_Preference_Variables.

Další metody a vlastnosti

Informace o dalších metodách a vlastnostech, ke kterým lze přistupovat prostřednictvím $PSCmdlet proměnné, najdete v tématu System.Management.Automation.PSCmdlet.

Například vlastnost ParameterSetName umožňuje zobrazit použitou sadu parametrů. Sady parametrů umožňují vytvořit funkci, která provádí různé úlohy na základě parametrů zadaných při spuštění funkce.

Viz také