Sdílet prostřednictvím

about_Functions_Advanced_Methods

Krátký popis

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

Dlouhý popis

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

  • Stejné metody zpracování vstupu dostupné pro všechny funkce.
  • Metody ShouldProcess a ShouldContinue, které slouží k získání zpětné vazby uživatelů před provedením akce.
  • Metoda ThrowTerminatingError pro generování záznamů chyb.
  • Několik Write metod, které vracejí 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 naleznete v tématu about_Functions_CmdletBindingAttribute. CmdletBindingAttribute třídy naleznete v tématu System.Management.Automation.CmdletBindingAttribute.

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. PowerShell 7.3 přidá metodu procesu bloku clean.

Ve svých funkcích nemusíte používat žádný z těchto bloků. Pokud pojmenovaný blok nepoužíváte, PowerShell vloží kód do end bloku funkce. Pokud ale použijete některý z těchto pojmenovaných bloků nebo definujete dynamicparam blok, musíte do pojmenovaného bloku vložit veškerý kód.

Následující příklad ukazuje osnovu funkce, která obsahuje blok begin pro jednorázové předběžné zpracování, blok process pro zpracování více záznamů a blok end pro jednorázové následné zpracování.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Poznámka

Tyto bloky platí pro všechny funkce, nejen funkce, které používají atribut CmdletBinding.

begin

Tento blok slouží k poskytnutí 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.

process

Tento blok slouží k zajištění zpracování záznamu po záznamu pro funkci. Můžete použít blok 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 bloku process. Automatická $input proměnná obsahuje enumerátor, který je k dispozici pouze pro funkce a bloky skriptů. Další informace naleznete 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 se blok process spustí jednou pro každý vstupní objekt, který dosáhne funkce.
  • Pokud je vstup kanálu, který dosáhne funkce, prázdný, process blok spustit.
    • Bloky begin, enda clean se stále spouštějí.

Důležitý

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

Při vytváření funkce, která přijímá vstup kanálu a používá CmdletBinding, by blok process měl místo $_ nebo $PSItempoužít proměnnou parametru, kterou jste definovali pro vstup kanálu. Například:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

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

clean

Blok clean byl přidán v PowerShellu 7.3.

Blok clean je pohodlný způsob, jak uživatelům vyčistit prostředky, které se nachází v begin, processa end blocích. Je to sémanticky podobné bloku finally, který pokrývá všechny ostatní pojmenované bloky funkce skriptu nebo rutiny skriptu. Vyčištění prostředků se vynucuje pro následující scénáře:

  1. po dokončení provádění kanálu normálně bez ukončení chyby
  2. při přerušení spuštění kanálu kvůli ukončovací chybě
  3. po zastavení kanálu Select-Object -First
  4. když kanál zastavíte Ctrl+c nebo StopProcessing()

Čistý blok zahodí všechny výstupy zapsané do datového proudu Success.

Opatrnost

Přidání bloku clean představuje zásadní změnu. Protože clean je analyzován jako klíčové slovo, brání uživatelům v přímém volání příkazu pojmenovaného clean jako první příkaz v bloku skriptu. Pravděpodobně to ale nebude problém. Příkaz lze přesto vyvolat pomocí operátoru volání (& clean).

Metody potvrzení

ShouldProcess

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.Cmdlet.ShouldProcess.

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

ShouldContinue

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

Metody chyb

Funkce můžou při výskytu chyb volat dvě různé metody. Pokud dojde k neukončující chybě, měla by funkce volat metodu WriteError, která je popsána v části Write metody. Pokud dojde k ukončovací chybě a funkce nemůže pokračovat, měla by volat metodu ThrowTerminatingError. Můžete také použít příkaz throw pro ukončování chyb a rutinu Write-Error pro neukonč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 všechny výstupy přejdou na další příkaz v kanálu. Můžete také použít různé Write rutiny, například Write-Error.

WriteCommandDetail

Informace o metodě WriteCommandDetails 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 funkci WriteDebug metodu. Metoda WriteDebug uživateli zobrazí zprávy ladění. Další informace naleznete v tématu System.Management.Automation.Cmdlet.WriteDebug.

Chyba zápisu

Funkce by měla tuto metodu volat, pokud dojde k neukončovacím chybám a funkce je navržena 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ě, funkce by měla volat metodu ThrowTerminatingError.

WriteObject

Metoda WriteObject umožňuje funkci odeslat objekt do dalšího příkazu v kanálu. Ve většině případů je WriteObject metodou, která se má použít, 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, tato metoda umožňuje funkci volat WriteProgress metodu, 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 funkci 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

Chcete-li poskytnout informace o podmínkách, které mohou způsobit neočekávané výsledky, proveďte volání metody WriteWarning k zobrazení upozornění zprávy pro uživatele. Ve výchozím nastavení se zobrazují zprávy upozornění. Další informace naleznete v tématu System.Management.Automation.PSCmdlet.WriteWarning.

Poznámka

Upozornění můžete zobrazit také konfigurací proměnné $WarningPreference nebo pomocí možností Verbose a Debug příkazového řádku. Další informace o proměnné $WarningPreference naleznete 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 proměnné $PSCmdlet, naleznete 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é

  • Last updated on