about_Functions

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. Příkazy v seznamu se spustí tak, jako kdybyste je zadali na příkazovém řádku.

Funkce můžou 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 nebo aplikace.

Podobně jako rutiny můžou mít funkce parametry. Parametry mohou být pojmenované, poziční, přepínače nebo dynamické parametry. Parametry funkce lze číst z příkazového řádku nebo z kanálu.

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. Můžete také zadat návratovou hodnotu pomocí klíčového return slova. 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.

Seznam příkazů funkce může obsahovat různé typy seznamů příkazů s klíčovými beginslovy , process, enda clean. Tyto seznamy příkazů zpracovávají vstup z kanálu jinak.

Klíčové slovo filtru slouží k vytvoření typu funkce, která běží na každém objektu v kanálu. Filtr se podobá funkci se všemi jeho příkazy v process bloku.

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

Následující syntaxe funkce:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

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é)
• Jeden nebo více příkazů PowerShellu uzavřených ve složených závorkách {}

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

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{}
}

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.

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()

Čistý blok zahodí všechny výstupy, které jsou zapsány 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 lze 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-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | 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 tématu.

Názvy funkcí

Funkci můžete přiřadit libovolný název, ale funkce, které sdílíte s ostatními, by měly dodržovat pravidla pojmenování, která byla vytvořena pro všechny příkazy PowerShellu.

Názvy funkcí by se měly skládat z dvojice sloves-podstatných jmen, kde příkaz identifikuje akci, kterou funkce provede, a podstatné jméno identifikuje položku, na které rutina provede svou akci.

Funkce by měly používat standardní příkazy schválené pro všechny příkazy PowerShellu. Tyto příkazy nám pomáhají udržet názvy příkazů konzistentní a snadno pochopitelné.

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 tématu.

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>
}

Níže je příklad této alternativní syntaxe.

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

Použití splattingu k reprezentaci parametrů příkazu

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-MyCommand funkce můžete použít všechny parametryGet-Command. 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 klíčovým slovem begin před tím, než všechny objekty pocházejí z kanálu. Funkce spustí příkazy s klíčovým slovem end po přijetí všech objektů z kanálu.

Následující příklad ukazuje automatickou proměnnou $input s begin klíčovými slovy a end klíčové slovo.

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

Pokud se tato funkce spustí pomocí kanálu, zobrazí se 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ému objektu, který je předaný do funkce, odešle 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:

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. při zastavení kanálu 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).

Filtry

Filtr je typ funkce, která běží na každém objektu v kanálu. Filtr se podobá funkci se všemi jeho příkazy v process bloku.

Syntaxe filtru je následující:

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

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-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Dá se použít takto:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Obor funkce

Funkce existuje v oboru, ve kterém je vytvořena.

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.

Hledání a správa funkcí pomocí funkce: Jednotka

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í C D 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 o Function: jednotce najdete v tématu nápovědy pro zprostředkovatele funkce . Zadejte Get-Help Function.

Opakované používání 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.

Psaní nápovědy pro funkce

Rutina Get-Help získá nápovědu pro funkce a také rutiny, poskytovatele 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 téma nápovědy 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 nebo na konci textu funkce nebo na řádcích předcházejících klíčovému slovu 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

  Vytvořte téma nápovědy založené na jazyce XML, například typ, který se obvykle vytvoří pro rutiny. Pokud lokalizujete témata nápovědy do více jazyků, vyžaduje se nápověda založená na jazyce XML.

  Pokud chcete funkci přidružit k tématu 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 téma nápovědy funkce a volání Get-Help funkce vrátit 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ě.

Viz také

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks