about_Functions

Článek
2025-04-17

Krátký popis

Popisuje, jak vytvářet a používat funkce v PowerShellu.

Dlouhý popis

Funkce je seznam příkazů PowerShellu, které mají přiřazený název. Při spuštění funkce zadáte název funkce.

PowerShell definuje dva druhy funkcí:

Funkce je blok kódu, který lze volat podle názvu. Může přijímat vstup a vracet výstup. Funkce jsou definovány pomocí klíčového function slova.
Filtr je typ funkce navržené ke zpracování dat z kanálu. Filtry se definují pomocí klíčového filter slova.

Příkazy ve funkci můžete seskupit do jednoho ze čtyř různých předdefinovaných bloků skriptů. Tyto bloky skriptu jsou pojmenovány beginpomocí klíčových slov , process, enda clean. Pokud tato klíčová slova nepoužíváte, PowerShell umístí příkazy do příslušného bloku kódu.

Funkce můžou také fungovat jako rutiny. Můžete vytvořit funkci, která funguje stejně jako rutina bez použití C# programování. Další informace najdete v tématu about_Functions_Advanced.

Důležité

V souborech skriptů a modulech založených na skriptech musí být funkce před jejich zavolání definovány.

Syntaxe funkce

Funkce se definují pomocí následující syntaxe:

function [<scope:>]<name> {
  param([type]$Parameter1 [,[type]$Parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Funkce obsahuje následující položky:

Klíčové function slovo
Obor (volitelné)
Název, který vyberete
Libovolný počet pojmenovaných parametrů (volitelné), včetně dynamických parametrů
Jeden nebo více příkazů PowerShellu uzavřených ve složených závorkách {}

Pokud v definici nepoužíváte jedno z klíčových slov (begin, processend, , clean), function PowerShell vloží příkazy do end bloku.

Další informace o dynamicparam klíčových slovech a dynamických parametrech ve funkcích najdete v tématu about_Functions_Advanced_Parameters.

Funkce může být jednoduchá jako:

function Get-PowerShellProcess { Get-Process pwsh }

Jakmile je funkce definovaná, můžete ji použít jako předdefinované rutiny. Pokud chcete například volat nově definovanou Get-PowerShellProcess funkci:

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

Funkce může být také stejně složitá jako rutina.

Funkce můžou vracet hodnoty, které se dají zobrazit, přiřadit k proměnným nebo předat jiným funkcím nebo rutinám. K vrácení výstupu return můžete použít klíčové slovo. Klíčové return slovo nemá vliv ani nepotlačuje jiný výstup vrácený z vaší funkce. return Klíčové slovo však ukončí funkci na daném řádku. Další informace najdete v tématu about_Return.

Syntaxe filtru

Účelem filter funkce je poskytnout krátký způsob definování funkce, která se spouští na každém objektu v kanálu.

Syntaxe filtru je následující:

filter [<scope:>]<name> {<statement list>}

Pro zjednodušení syntaxe funkcí filter vynecháte klíčové slovo bloku skriptu (begin, process, end, clean). PowerShell umístí příkazy do process bloku. Ve funkci filtru můžete použít libovolný z dalších bloků, ale záměrem bylo poskytnout zkrácený způsob definování funkce, která má jediný účel zpracování každého objektu v kanálu.

Následující filtr přebírá položky protokolu z kanálu a pak zobrazí buď celou položku, nebo pouze část zprávy položky:

filter Get-EventMessage ([switch]$MessageOnly) {
  if ($MessageOnly) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Dá se použít takto:

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

Metody zpracování vstupu

Metody popsané v této části se označují jako metody zpracování vstupu. Pro funkce, tyto tři metody pojmenované beginpomocí , 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 bloková data z kanálu a end blok pro jednorázové následné zpracování.

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

`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.

Pokud je funkce vyvolána bez vstupu kanálu, PowerShell spustí process blok pouze 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 parametr funkce přijímá vstup kanálu a process blok není definovaný, zpracování záznamu po záznamu selže. V tomto případě se vaše funkce spustí jenom jednou bez ohledu na vstup.

`end`

Tento blok použijte 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:

po dokončení provádění kanálu bez ukončení chyby
při přerušení spuštění kanálu kvůli ukončovací chybě
když je kanál zkrácen, například: Select-Object -First
když je kanál zastaven pomocí Ctrl+c nebo StopProcessing()

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

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 můžete přesto vyvolat pomocí operátoru volání (& clean).

Jednoduché funkce

Funkce nemusí být složité, aby byly užitečné. Nejjednodušší funkce mají následující formát:

function <function-name> { statements }

Například následující funkce spustí PowerShell s možností Spustit jako správce .

function Start-PSAdmin { Start-Process PowerShell -Verb RunAs }

Pokud chcete funkci použít, zadejte: Start-PSAdmin

Chcete-li do funkce přidat příkazy, zadejte každý příkaz na samostatný řádek nebo k oddělení příkazů použijte středník (;).

Například následující funkce najde všechny .jpg soubory v adresářích aktuálního uživatele, které byly změněny po počátečním datu.

function Get-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | Where-Object {$_.LastWriteTime -gt $Start}
}

Můžete vytvořit sadu nástrojů s užitečnými malými funkcemi. Přidejte tyto funkce do profilu PowerShellu, jak je popsáno v about_Profiles a dále v tomto článku.

Názvy funkcí

Funkci můžete přiřadit libovolný název. Pro funkce, které sdílíte s ostatními, byste ale měli dodržovat standardní pravidla pojmenování PowerShellu.

Názvy by se měly skládat z dvojice sloves-podstatné jméno, kde příkaz identifikuje akci, kterou funkce provede, a podstatné jméno identifikuje položku, na které rutina akci provede.
Názvy by měly používat schválené příkazy pro všechny příkazy PowerShellu. Použití schválených příkazů vytváří konzistenci pro uživatele.

Další informace o standardních příkazech PowerShellu najdete v tématu Schválené příkazy.

Funkce s parametry

Parametry můžete použít s funkcemi, včetně pojmenovaných parametrů, pozičních parametrů, parametrů přepínače a dynamických parametrů. Další informace o dynamických parametrech ve funkcích najdete v tématu about_Functions_Advanced_Parameters.

Pojmenované parametry

Můžete definovat libovolný počet pojmenovaných parametrů. Můžete zahrnout výchozí hodnotu pro pojmenované parametry, jak je popsáno dále v tomto článku.

Parametry uvnitř složených závorek můžete definovat pomocí klíčového param slova, jak je znázorněno v následující ukázkové syntaxi:

function <name> {
  param ([type]$Parameter1 [,[type]$Parameter2])
  <statement list>
}

Můžete také definovat parametry mimo složené závorky bez klíčového param slova, jak je znázorněno v následující ukázkové syntaxi:

function <name> [([type]$Parameter1[,[type]$Parameter2])] {
  <statement list>
}

Například následující funkce používá alternativní syntaxi k definování dvou parametrů:

function Add-Numbers([int]$One, [int]$Two) {
    $One + $Two
}

I když je první metoda upřednostňovaná, mezi těmito dvěma metodami není žádný rozdíl.

Při spuštění funkce je hodnota, kterou zadáte pro parametr, přiřazena proměnné, která obsahuje název parametru. Hodnotu této proměnné lze použít ve funkci.

Následující příklad je funkce s názvem Get-SmallFiles. Tato funkce má $Size parametr. Funkce zobrazí všechny soubory, které jsou menší než hodnota parametru $Size , a vyloučí adresáře:

function Get-SmallFiles {
  param ($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Ve funkci můžete použít $Size proměnnou, což je název definovaný pro parametr.

Pokud chcete použít tuto funkci, zadejte následující příkaz:

Get-SmallFiles -Size 50

Můžete také zadat hodnotu pojmenovaného parametru bez názvu parametru. Například následující příkaz vrátí stejný výsledek jako příkaz, který pojmenuje parametr Velikost :

Get-SmallFiles 50

Pokud chcete definovat výchozí hodnotu pro parametr, zadejte symbol rovná se a hodnotu za název parametru, jak je znázorněno v následující variantě příkladu Get-SmallFiles :

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Pokud zadáte Get-SmallFiles bez hodnoty, funkce přiřadí hodnotu 100 .$size Pokud zadáte hodnotu, použije funkce tuto hodnotu.

Volitelně můžete zadat krátký řetězec nápovědy, který popisuje výchozí hodnotu parametru přidáním atributu PSDefaultValue do popisu parametru a zadáním vlastnosti Nápověda PSDefaultValue. Pokud chcete poskytnout řetězec nápovědy, který popisuje výchozí hodnotu (100) parametru Size ve Get-SmallFiles funkci, přidejte atribut PSDefaultValue , jak je znázorněno v následujícím příkladu.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Další informace o PSDefaultValue atribut třída, viz PSDefaultValue Attribute Members.

Poziční parametry

Poziční parametr je parametr bez názvu parametru. PowerShell používá pořadí hodnot parametrů k přidružení každé hodnoty parametru k parametru ve funkci.

Při použití pozičních parametrů zadejte za název funkce jednu nebo více hodnot. Hodnoty pozičních parametrů jsou přiřazeny proměnné $args pole. Hodnota, která následuje za názvem funkce, je přiřazena k první pozici v $args poli, $args[0].

Následující Get-Extension funkce přidá příponu .txt názvu souboru k zadanému názvu souboru:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Parametry přepínače

Přepínač je parametr, který nevyžaduje hodnotu. Místo toho zadáte název funkce následovaný názvem parametru switch.

Pokud chcete definovat parametr přepínače, zadejte typ [switch] před název parametru, jak je znázorněno v následujícím příkladu:

function Switch-Item {
  param ([switch]$On)
  if ($On) { "Switch on" }
  else { "Switch off" }
}

Když za název funkce zadáte On parametr přepínače, zobrazí Switch onse funkce . Bez parametru přepínače se zobrazí Switch off.

Switch-Item -On

Switch on

Switch-Item

Switch off

Při spuštění funkce můžete také přiřadit logickou hodnotu přepínači, jak je znázorněno v následujícím příkladu:

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Předání hodnot parametrů pomocí splattingu

K reprezentaci parametrů příkazu můžete použít splatting. Tato funkce je představena ve Windows PowerShellu 3.0.

Tuto techniku použijte ve funkcích, které volají příkazy v relaci. Nemusíte deklarovat ani vyčíslovat parametry příkazu nebo měnit funkci při změně parametrů příkazu.

Následující ukázková funkce volá rutinu Get-Command . Příkaz používá @args k reprezentaci parametrů .Get-Command

function Get-MyCommand { Get-Command @args }

Při volání Get-Command funkce můžete použít všechny parametryGet-MyCommand. Parametry a hodnoty parametrů jsou předány příkazu pomocí @args.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Funkce @args používá $args automatický parametr, který představuje nedelarované parametry rutiny a hodnoty ze zbývajících argumentů.

Další informace najdete v tématu about_Splatting.

Propojení objektů do funkcí

Každá funkce může přijímat vstupy z kanálu. Můžete řídit, jak funkce zpracovává vstup z kanálu pomocí begin, process, enda clean klíčových slov. Následující ukázková syntaxe ukazuje tato klíčová slova:

Seznam process příkazů se spustí jednou pro každý objekt v kanálu. process Zatímco je blok spuštěný, každý objekt kanálu je přiřazen k $_ automatické proměnné, jeden objekt kanálu najednou.

Následující funkce používá process klíčové slovo. Funkce zobrazí hodnoty z kanálu:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1, 2, 4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Pokud chcete, aby funkce, která může přijímat vstup kanálu nebo vstup z parametru, process musí blok zpracovat oba případy. Příklad:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

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

Pokud používáte funkci v kanálu, objekty předané funkci jsou přiřazeny k $input automatické proměnné. Funkce spouští příkazy s blokem begin skriptu před tím, než všechny objekty pocházejí z kanálu. Funkce spouští příkazy s blokem end skriptu, pokud v kanálu nejsou žádné další objekty.

Následující příklad ukazuje automatickou $input proměnnou použitou v blocích skriptu a end int.begin

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Při spuštění funkce se vstupem kanálu se zobrazí následující výsledky:

1, 2, 4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Když se begin příkaz spustí, funkce nemá vstup z kanálu. Příkaz end se spustí poté, co má funkce hodnoty.

Pokud má process funkce klíčové slovo, každý objekt v $input je odebrán z $input a přiřazen .$_ Následující příklad obsahuje process seznam příkazů:

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

V tomto příkladu se každý objekt předá funkci do process seznamu příkazů. Příkazy process běží na každém objektu, jeden objekt najednou. Automatická $input proměnná je prázdná, když funkce dosáhne klíčového end slova.

1, 2, 4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Další informace naleznete v tématu Použití enumerátorů

PowerShell 7.3 přidal clean blok. Blok clean je pohodlný způsob, jak uživatelům vyčistit prostředky vytvořené a používané v beginprocess, a 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:

po dokončení provádění kanálu normálně bez ukončení chyby
při přerušení spuštění kanálu kvůli ukončovací chybě
když je kanál zkrácen, například: Select-Object -First
když je kanál zastaven pomocí 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).

Rozsah funkce

Funkce existuje v oboru, ve kterém ji vytvoříte.

Pokud je funkce součástí skriptu, je funkce k dispozici pro příkazy v rámci tohoto skriptu. Ve výchozím nastavení není funkce ve skriptu dostupná mimo tento skript.

Můžete zadat rozsah funkce. Například funkce se přidá do globálního oboru v následujícím příkladu:

function Global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Pokud je funkce v globálním oboru, můžete ji použít ve skriptech, ve funkcích a na příkazovém řádku.

Funkce vytvoří nový obor. Položky vytvořené ve funkci, například proměnné, existují pouze v oboru funkce.

Další informace najdete v tématu about_Scopes.

Vyhledání a správa funkcí pomocí `Function:` jednotky

Všechny funkce a filtry v PowerShellu se automaticky ukládají na jednotku Function: . Tato jednotka je vystavena poskytovatelem funkce PowerShellu.

Při odkazování na jednotku Function: zadejte dvojtečku za funkci stejně jako při odkazování CD na jednotku počítače.

Následující příkaz zobrazí všechny funkce v aktuální relaci PowerShellu:

Get-ChildItem Function:

Příkazy ve funkci jsou uloženy jako blok skriptu ve vlastnosti definice funkce. Pokud chcete například zobrazit příkazy ve funkci nápovědy, která je součástí PowerShellu, zadejte:

(Get-ChildItem Function:help).Definition

Můžete také použít následující syntaxi.

$Function:help

Další informace najdete v tématu about_Function_Provider.

Opakované použití funkcí v nových relacích

Když zadáte funkci na příkazovém řádku PowerShellu, stane se tato funkce součástí aktuální relace. Funkce je k dispozici až do ukončení relace.

Pokud chcete funkci používat ve všech relacích PowerShellu, přidejte tuto funkci do profilu PowerShellu. Další informace o profilech najdete v tématu about_Profiles.

Funkci můžete také uložit do souboru skriptu PowerShellu. Zadejte funkci do textového souboru a pak soubor uložte s příponou .ps1 názvu souboru.

Vytvoření nápovědy pro funkce

Rutina Get-Help získá nápovědu pro funkce, rutiny, zprostředkovatele a skripty. Nápovědu k funkci získáte zadáním Get-Help názvu funkce.

Pokud chcete například získat nápovědu Get-MyDisks pro funkci, zadejte:

Get-Help Get-MyDisks

Nápovědu pro funkci můžete napsat pomocí některé z těchto dvou metod:

Nápověda k funkcím založená na komentářích

Vytvořte nápovědu pomocí speciálních klíčových slov v komentářích. Pokud chcete pro funkci vytvořit nápovědu založenou na komentářích, musí být komentáře umístěny na začátku, na konci nebo v těle funkce. Další informace o nápovědě založené na komentářích najdete v tématu about_Comment_Based_Help.
Nápověda založená na JAZYCE XML pro funkce

Pokud potřebujete lokalizovat obsah nápovědy do více jazyků, vyžaduje se nápověda založená na jazyce XML. Pokud chcete přidružit funkci k souboru nápovědy založenému na JAZYCE XML, použijte klíčové slovo nápovědy založené na .EXTERNALHELP komentáři. Bez tohoto klíčového slova Get-Help nemůže najít soubor nápovědy funkce a vrátí pouze automaticky vygenerovanou nápovědu.

Další informace o klíčovém slově .EXTERNALHELP najdete v tématu about_Comment_Based_Help. Další informace o nápovědě založené na jazyce XML naleznete v tématu Jak napsat nápovědu k rutině.

Sdílet prostřednictvím