O funkcích

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

Funkce může být také tak složitá jako rutina nebo aplikační program.

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. Návratovou hodnotu můžete zadat také pomocí klíčového slova return. Klíčové return slovo nemá vliv na jiný výstup vrácený z funkce, ani ho nepotlačuje. return Klíčové slovo však ukončí funkci na daném řádku. Další informace naleznete v tématu about_Return.

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

Filtr je speciální druh funkce, která používá klíčové Filter slovo.

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.

Syntaxe

Následuje syntaxe funkce:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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.

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 příkazy oddělte středníkem ; .

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 páru sloveso-podstatné jméno, ve kterém sloveso identifikuje akci, kterou funkce provádí, a podstatné jméno identifikuje položku, na které rutina provádí svou akci.

Funkce by měly používat standardní příkazy schválené pro všechny příkazy PowerShellu. Tato slovesa nám pomáhají udržovat názvy našich příkazů jednoduché, konzistentní a snadno srozumitelné pro uživatele.

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

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 slova Param , 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($one, $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
  )
}

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 názvu souboru, který zadáte:

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 switch, funkce zobrazí "Zapnout". Bez parametru switch se zobrazí "Vypnout".

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

Pro 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. Parametry příkazu nemusíte deklarovat ani vytvářet výčet ani měnit funkci, když se parametry příkazu změní.

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 }

Můžete použít všechny parametry Get-Command při volání Get-MyCommand funkce. 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 o splattingu najdete v části 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, Processa End klíčových slov. Následující ukázková syntaxe ukazuje tři klíčová slova:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Seznam Begin příkazů se spustí pouze jednou, a to na začátku funkce.

Důležité

Pokud vaše funkce definuje Beginblok nebo ProcessEnd , musí být veškerý kód umístěn uvnitř jednoho z bloků.

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.

Jakmile funkce obdrží všechny objekty v kanálu, seznam příkazů End se spustí jednou. Pokud nejsou použita klíčová slova , BeginProcess, nebo , budou End všechny příkazy považovány za End seznam příkazů.

Následující funkce používá Process klíčové slovo. Funkce zobrazí příklady z pipeline:

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

Chcete-li tuto funkci předvést, zadejte seznam čísel oddělených čárkami, jak je znázorněno v následujícím příkladu:

1,2,4 | Get-Pipeline

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

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 $input automatické proměnné s klíčovými slovy Begin a End.

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

Pokud je tato funkce spuštěna pomocí kanálu, zobrazí následující výsledky:

1,2,4 | Get-PipelineBeginEnd

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

Begin Při spuštění příkazu 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 je každý objekt, který je předán funkci, odeslán do seznamu příkazů Process . 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ů

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 bloku Process.

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

Obor funkce

Funkce existuje v rozsahu, ve kterém byla 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 na příkazovém řádku k dispozici.

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 obvykle vytvářejí rozsah. Položky vytvořené ve funkci, například proměnné, existují pouze v oboru funkce.

Další informace o rozsahu v PowerShellu 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í 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 o jednotce Function: naleznete v tématu nápovědy pro poskytovatele 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. Je k dispozici až do konce relace.

Pokud chcete funkci používat ve všech relacích PowerShellu, přidejte tuto funkci do profilu PowerShellu. Další informace o profilech, viz 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 k funkci můžete napsat pomocí jedné ze dvou následujících 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 vytváří pro rutiny. Pokud lokalizujete témata nápovědy do více jazyků, vyžaduje se nápověda založená na jazyce XML.

Chcete-li přidružit funkci k tématu nápovědy založené na jazyce XML, použijte klíčové slovo nápovědy založené na komentáři .ExternalHelp. Bez tohoto klíčového slova Get-Help nelze najít téma nápovědy k funkci a volání Get-Help funkce 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ám v knihovně MSDN.