about_Functions_Advanced_Methods

  • Článek

Krátký popis

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

Dlouhý popis

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

  • Stejné metody zpracování vstupu dostupné pro všechny funkce.
  • Metody ShouldProcess , ShouldContinue které slouží k získání zpětné vazby uživatelů před provedením akce.
  • Metoda ThrowTerminatingError generování chybových záznamů.
  • 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 najdete v tématu about_Functions_CmdletBindingAttribute. Pro RutinBindingAttribute třídy, 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. PowerShell 7.3 přidá metodu clean procesu bloku.

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 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é následné zpracování.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Poznámka:

Tyto bloky platí pro všechny funkce, nejen pro funkce, které tento atribut používají 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. 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 na tom, jaký vstup funkce přijme.

Automatická proměnná $_ nebo $PSItem obsahuje aktuální objekt v kanálu pro použití v process bloku. Automatická $input proměnná obsahuje enumerátor, který je k dispozici 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 se process 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í .
    • Příkazy begin, enda clean bloky jsou stále spuštěny.

Důležité

Pokud je parametr funkce nastavený tak, aby přijímal vstup kanálu a process není definován blok, 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 měl používat proměnnou parametru, process kterou jste definovali pro vstup kanálu místo $_ nebo $PSItem. Pří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é pokrývají begin, processa end bloky. Je to sémanticky podobné finally bloku, 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í ctrl +c nebo StopProcessing()

Upozornění

clean Přidání bloku je zásadní změna. 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ž ShouldProcess metoda 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ě, funkce by měla volat metodu WriteError , která je popsána Write v čá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 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 WriteCommandDetails metodě naleznete v tématu System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Chcete-li poskytnout informace, které lze použít k řešení potíží s funkcí, zavolejte funkci metodu WriteDebug . Metoda WriteDebug zobrazí zprávy ladění pro uživatele. 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 ThrowTerminatingError metoda.

WriteObject

Tato WriteObject metoda umožňuje funkci odeslat objekt do dalšího příkazu v kanálu. Ve většině případů je metoda, která se má použít, WriteObject když funkce vrací 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 metodu WriteProgress , 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 , aby uživateli zobrazila podrobné zprávy. 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í $WarningPreference proměnné nebo pomocí možností příkazového Verbose řádku.Debug 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 získat přístup prostřednictvím $PSCmdlet proměnné, naleznete v tématu System.Management.Automation.PSCmdlet.

Vlastnost ParameterSetName například 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é