Informace o službě Functions

Článek
05/09/2024

Krátký popis

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

Dlouhý popis

Funkce je seznam příkazů PowerShellu s názvem, který přiřadíte. Při spuštění funkce zadáte název funkce. Příkazy v seznamu se spouští, 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é stejně složitá jako rutina nebo aplikační program.

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

Funkce můžou vracet hodnoty, které lze 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 return slova. Klíčové return slovo neovlivňuje ani nepotlačuje jiný výstup vrácený z funkce. Klíčové slovo však return funkci ukončí 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 , Processa End. Tyto seznamy příkazů zpracovávají vstup z kanálu odlišně.

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

Funkce se také můžou chovat 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.

Syntax

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é)
Jméno, 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 klíčových slovech Dynamicparam 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}

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

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

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

Pokud chcete do funkce přidat příkazy, zadejte každý příkaz na samostatný řádek nebo je oddělte středníkem ; .

Následující funkce například 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 se měly řídit pravidly vytváření názvů, která byla vytvořena pro všechny příkazy PowerShellu.

Názvy funkcí by se měly skládat z dvojice sloves-podstatné jméno, ve kterém sloveso identifikuje akci, kterou funkce provede, 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. Tyto příkazy nám pomáhají udržovat názvy příkazů jednoduché, konzistentní a pro uživatele snadno pochopitelné.

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žívat 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 pojmenovaných parametrů, jak je popsáno dále v tomto tématu.

Parametry uvnitř 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 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 uveden příklad této alternativní syntaxe.

Function Add-Numbers($one, $two) {
    $one + $two
}

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

Při spuštění funkce se hodnota, kterou zadáte pro parametr, přiřadí 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 proměnnou $size , což je název definovaný pro parametr.

Chcete-li použít tuto funkci, zadejte následující příkaz:

Get-SmallFiles -Size 50

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

Get-SmallFiles 50

Pokud chcete definovat výchozí hodnotu parametru, zadejte za název parametru znaménko rovná se a hodnotu, 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 k $size. Pokud zadáte hodnotu, funkce tuto hodnotu použije.

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 HelpPSDefaultValue. Chcete-li 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 třídě atributu PSDefaultValue naleznete v tématu PSDefaultValue – členy atributu.

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 $args proměnné pole. Hodnota, která následuje za názvem funkce, $args[0]je přiřazena k první pozici v $args poli .

Následující Get-Extension funkce přidá příponu .txt názvu souboru do zadaného 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 zadejte název funkce následovaný názvem parametru přepínače.

Pokud chcete definovat parametr přepínače, zadejte typ [switch] před názvem 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 přepínači přiřadit také logickou hodnotu, 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 zavedena v Windows PowerShell 3.0.

Tuto techniku použijte ve funkcích, které volají příkazy v relaci. Při změně parametrů příkazu není nutné deklarovat ani vypsat jejich výčet ani měnit funkci.

Následující ukázková funkce volá rutinu Get-Command . Příkaz používá @Args k reprezentaci parametrů parametru 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ů se předají příkazu pomocí @Argspříkazu .

Get-MyCommand -Name Get-ChildItem

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

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

Další informace o splattingu najdete v tématu about_Splatting.

Propojení objektů do funkcí

Z kanálu může přijímat vstup libovolná funkce. Pomocí klíčových slov , Processa End můžete řídit, jak funkce zpracovává vstup z kanáluBegin. Následující ukázková syntaxe ukazuje tři klíčová slova:

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

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

Důležité

Pokud vaše funkce definuje Beginblok , Process nebo End , musí se veškerý kód nacházet uvnitř jednoho z bloků.

Seznam příkazů se Process spustí jednou pro každý objekt v kanálu. Process Zatímco je blok spuštěný, každý objekt kanálu se přiřadí k $_ automatické proměnné, vždy po jednom objektu kanálu.

Jakmile funkce přijme všechny objekty v kanálu, spustí se End seznam příkazů jednou. Pokud se nepoužijí žádná Beginklíčová slova , Processnebo End , všechny příkazy se považují za End seznam příkazů.

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

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

Pro předvedení této funkce 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

Když použijete funkci v kanálu, objekty předané do funkce se přiřadí k $input automatické proměnné. Funkce spouští příkazy s klíčovým slovem Begin před tím, než z kanálu přijdou jakékoli objekty. Funkce po přijetí všech objektů z kanálu spustí příkazy s End klíčovým slovem .

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

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

Pokud se tato funkce spouští 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 se End spustí poté, co funkce obsahuje hodnoty.

Pokud má Process funkce klíčové slovo, každý objekt v souboru $input se odebere z $input a přiřadí se k $_. 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ředaný do funkce, odeslán do Process seznamu příkazů. Příkazy se Process spouští na každém objektu, vždy po jednom objektu. 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 najdete 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 příkazy v Process bloku.

Syntaxe filtru je následující:

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

Následující filtr převezme položky protokolu z kanálu a pak zobrazí buď celou položku, nebo jenom část zprávy v této položce:

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

Obor funkce

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

Pokud je funkce součástí skriptu, je funkce dostupná pro příkazy v rámci tohoto skriptu. Ve výchozím nastavení není funkce ve skriptu dostupná na příkazovém řádku.

Můžete zadat obor funkce. Například funkce je přidána 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í obor. Položky vytvořené ve funkci, například proměnné, existují pouze v oboru funkce.

Další informace o oboru v PowerShellu najdete v tématu about_Scopes.

Hledání a správa funkcí pomocí funkce Drive

Všechny funkce a filtry v PowerShellu se automaticky ukládají na jednotku Function: . Tato jednotka je zpřístupněna zprostředkovatelem funkcí PowerShellu.

Při odkazování na jednotku Function: zadejte za Function dvojtečku, stejně jako byste to udělali při odkazování na C jednotku nebo D 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: najdete v tématu nápovědy pro zprostředkovatele funkcí . Zadejte Get-Help Function.

Opakované pouu ení funkcí v nových relacích

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

Pokud chcete funkci použít ve všech relacích PowerShellu, přidejte ji do svého 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é pro rutiny, zprostředkovatele a skripty. Nápovědu k funkci získáte zadáním Get-Help a názvem funkce.

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

Get-Help Get-MyDisks

Nápovědu k funkci můžete napsat pomocí některé z následujících dvou metod:

Nápověda k Comment-Based pro Functions

Create 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 konci textu funkce nebo na řádky před klíčovým slovem funkce. Další informace o nápovědě založené na komentářích najdete v tématu about_Comment_Based_Help.
Nápověda k XML-Based pro Functions

Create 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ů, potřebujete nápovědu založenou 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ářích. Bez tohoto klíčového slova Get-Help nelze najít téma nápovědy funkce a volání funkce Get-Help vrátí pouze automaticky vygenerovanou nápovědu.

Další informace o klíčovém slově najdete v ExternalHelp tématu about_Comment_Based_Help. Další informace o nápovědě založené na jazyce XML naleznete v části How to Write Cmdlet Help (Jak psát nápovědu k rutině ) v knihovně MSDN.