Informace o službě Functions

2019-02-27

Krátký popis

Popisuje, jak vytvořit a používat funkce v prostředí PowerShell.

Dlouhý popis

Funkce je seznam příkazů PowerShellu, které mají název, který přiřadíte. Když spustíte funkci, zadáte název funkce. Příkazy v seznamu se spustí, jako kdyby byly zadány v 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 program aplikace.

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

Funkce mohou vracet hodnoty, které lze zobrazit, přiřadit proměnným nebo předávat jiným funkcím nebo rutinám. Můžete také zadat návratovou hodnotu pomocí return klíčového slova. returnKlíčové slovo neovlivňuje nebo potlačí ostatní výstupy vracené z vaší funkce. returnKlíč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 slovy Begin , Process a End . Tyto příkazy zpracovávají vstup z kanálu odlišně.

Filtr je zvláštní druh funkce, která používá Filter klíčové 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.

Syntax

Následuje syntaxe pro funkci:

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:

FunctionKlíčové slovo
Obor (volitelné)
Název, který vyberete
Libovolný počet pojmenovaných parametrů (volitelné)
Jeden nebo více příkazů prostředí PowerShell uzavřených ve složených závorkách{}

Další informace o Dynamicparam klíčovém slově a dynamických parametrech ve funkcích naleznete 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}

Chcete-li funkci použít, zadejte:Start-PSAdmin

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

Následující funkce například vyhledá 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ů užitečných malých funkcí. Přidejte tyto funkce do vašeho profilu prostředí PowerShell, 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 prostředí PowerShell.

Názvy funkcí by měly být tvořeny dvojicí příkazového jména, ve které příkaz identifikuje akci, kterou funkce provádí, a podstatné jméno identifikuje položku, na které rutina provádí akci.

Funkce by měly používat standardní příkazy, které byly schváleny pro všechny příkazy prostředí PowerShell. Tyto příkazy nám pomohou zajistit, aby názvy příkazů byly jednoduché, konzistentní a srozumitelné pro uživatele.

Další informace o standardních příkazech PowerShellu naleznete v tématu schválené operace v Microsoft docs.

Funkce s parametry

Můžete použít parametry 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 naleznete 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 můžete definovat uvnitř složených závorek pomocí klíčového slova param , jak je znázorněno v následující vzorové syntaxi:

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

Můžete také definovat parametry mimo složené závorky bez Param klíčového slova, jak je znázorněno v následující vzorové 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 první metoda upřednostňovaná, neexistuje rozdíl mezi těmito dvěma metodami.

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.

V následujícím příkladu je volána funkce Get-SmallFiles . Tato funkce má $size parametr. Funkce zobrazí všechny soubory, které jsou menší než hodnota $size parametru, 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, která 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 poskytuje stejný výsledek jako příkaz, který má název parametru Size :

Get-SmallFiles 50

Chcete-li definovat výchozí hodnotu pro parametr, zadejte znaménko rovná se a hodnotu za názvem parametru, jak je znázorněno v následující variaci Get-SmallFiles příkladu:

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í 100 $size . Pokud zadáte hodnotu, funkce použije tuto hodnotu.

Volitelně můžete zadat krátký řetězec Help, který popisuje výchozí hodnotu parametru, přidáním atributu PSDefaultValue do popisu parametru a zadáním vlastnosti help třídy PSDefaultValue. Chcete-li zadat řetězec pro nápovědě, 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ě atributů PSDefaultValue naleznete v tématu Členové atributu PSDefaultValue.

Poziční parametry

Poziční parametr je parametr bez názvu parametru. Prostředí PowerShell používá pořadí hodnot parametrů k přidružení jednotlivých hodnot parametrů k parametru ve funkci.

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

Následující Get-Extension funkce přidá .txt příponu názvu souboru do 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 přepínače.

Chcete-li 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ž zadáte On parametr Switch za název funkce, funkce zobrazí "Zapnout". Bez parametru přepínače se zobrazí "přepínač vypnuto".

Switch-Item -on

Switch on

Switch-Item

Switch off

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Reprezentace parametrů příkazu pomocí seskupováním

Seskupováním můžete použít k reprezentaci parametrů příkazu. Tato funkce se zavádí v prostředí Windows PowerShell 3,0.

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

Následující ukázková funkce volá Get-Command rutinu. Příkaz používá @Args k vyjádření 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

Tato @Args funkce používá $Args Automatický parametr, který reprezentuje nedeklarované parametry rutiny a hodnoty ze zbývajících argumentů.

Další informace o seskupováním najdete v tématu about_Splatting.

Potrubní objekty do funkcí

Kterákoli z funkcí může přebírat vstup z kanálu. Můžete řídit, jak funkce zpracovává vstup z kanálu pomocí Begin Process End klíčových slov, a. Následující vzorová syntaxe ukazuje tři klíčová slova:

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

BeginSeznam příkazů se spouští pouze jednou, na začátku funkce.

Důležité

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

ProcessSeznam příkazů se spustí jednou pro každý objekt v kanálu. I když Process je spuštěn blok, každý objekt kanálu je přiřazen k $_ automatické proměnné, jeden objekt kanálu v daném okamžiku.

Jakmile funkce obdrží všechny objekty v kanálu, End seznam příkazů se spustí jednou. Pokud Begin Process End se použijí klíčová slova No, nebo, jsou 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 kanálu:

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

Chcete-li předvést tuto funkci, zadejte seznam čísel oddělený čá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

Použijete-li funkci v kanálu, objekty, které jsou zařazeny do funkce, jsou přiřazeny $input automatické proměnné. Funkce spouští příkazy s Begin klíčovým slovem před tím, než všechny objekty pocházejí z kanálu. Funkce spouští příkazy s End klíčovým slovem po přijetí všech objektů z kanálu.

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

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

Pokud se tato funkce spustí 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

Když se Begin příkaz spustí, funkce nemá vstup z kanálu. EndPříkaz se spustí poté, co funkce obsahuje hodnoty.

Pokud má funkce Process klíčové slovo, každý objekt v $input je odebrán z $input a přiřazen do $_ . 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 jsou všechny objekty, které jsou přenášeny do funkce, odesílány do Process seznamu příkazů. ProcessPříkazy jsou spouštěny každý objekt v jednom okamžiku. $inputAutomatická proměnná je prázdná, pokud funkce dosáhne End klíčového 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á se spouští na jednotlivých objektech 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á záznamy protokolu z kanálu a pak zobrazuje buď celou položku, nebo pouze část zprávy v této položce:

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

Rozsah funkce

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

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

Můžete zadat rozsah 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}
}

Když je funkce v globálním rozsahu, můžete použít funkci ve skriptech, v functions a na příkazovém řádku.

Funkce normálně vytvoří obor. Položky vytvořené ve funkci, jako 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: jednotka

Všechny funkce a filtry v PowerShellu se automaticky ukládají do Function: jednotky. Tuto jednotku zveřejňuje poskytovatel funkce PowerShellu.

Při odkazování na Function: jednotku zadejte dvojtečku po funkci, stejně jako při odkazování na C D jednotku nebo počítač.

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

Get-ChildItem function:

Příkazy ve funkci jsou uloženy jako blok skriptu ve vlastnosti definice funkce. Pokud například chcete zobrazit příkazy ve funkci Help, která je součástí prostředí PowerShell, zadejte:

(Get-ChildItem function:help).Definition

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

$function:help

Další informace o Function: jednotce naleznete v tématu nápovědy pro poskytovatele funkce . Zadejte Get-Help Function.

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

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

Pokud chcete funkci používat ve všech relacích PowerShellu, přidejte funkci do vašeho 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 uložte soubor s .ps1 příponou názvu souboru.

Psaní nápovědu pro funkce

Get-HelpRutina získá nápovědu pro funkce a také pro rutiny, zprostředkovatele a skripty. Chcete-li získat nápovědu pro funkci, zadejte Get-Help následovaný názvem funkce.

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

Get-Help Get-MyDisks

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

Nápovědu k funkcím na základě komentářů

Umožňuje vytvořit téma nápovědy pomocí speciálních klíčových slov v komentářích. Chcete-li pro funkci vytvořit nápovědu založenou na komentářích, je nutné komentáře umístit na začátek nebo konec těla funkce nebo na řádky před klíčovým slovem Function. Další informace o nápovědě založené na komentářích najdete v tématu about_Comment_Based_Help.
Nápovědu založené na XML pro funkce

Vytvoření tématu nápovědy založeného na jazyce XML, jako je například typ, který je obvykle vytvořen pro rutiny. Při lokalizaci témat nápovědy do několika jazyků je vyžadována nápovědu založená na jazyce XML.

Chcete-li přidružit funkci k tématu nápovědy založenému na jazyce XML, použijte .ExternalHelp klíčové slovo Nápověda na základě komentářů. Bez tohoto klíčového slova Get-Help nelze najít téma nápovědy funkce a volání Get-Help funkce vrátí pouze automaticky generovanou nápovědu.

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