a_Függvényekről

Rövid leírás

Ismerteti, hogyan hozhat létre és használhat függvényeket a PowerShellben.

Hosszú leírás

A függvények a Hozzárendelt névvel rendelkező PowerShell-utasítások listája. Függvény futtatásakor beírja a függvény nevét.

A PowerShell kétféle függvényt határoz meg:

A függvény egy kódblokk, amely név alapján hívható meg. Bemenetet és kimenetet is képes visszaadni. A függvények a function kulcsszó használatával vannak definiálva.
A szűrő a folyamatból származó adatok feldolgozására tervezett függvénytípus. A szűrők a filter kulcsszó használatával vannak definiálva.

A függvényben lévő utasításokat négy különböző előre definiált utasításblokk egyikébe csoportosíthatja. Ezek az utasításblokkok a kulcsszavak begin, process, endés clean. Ha nem használja ezeket a kulcsszavakat, a PowerShell a megfelelő kódblokkba helyezi az utasításokat.

A függvények parancsmagokként is működhetnek. Olyan függvényt hozhat létre, amely ugyanúgy működik, mint egy parancsmag C# programozás nélkül. További információ: about_Functions_Advanced.

Fontos

A szkriptfájlokban és a szkriptalapú modulokban a függvényeket meg kell határozni, mielőtt meghívhatók lennének.

Függvényszintaxis

A függvények a következő szintaxissal vannak definiálva:

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

A függvények a következő elemeket tartalmazzák:

Egy function kulcsszó
Hatókör (nem kötelező)
A kiválasztott név
Tetszőleges számú elnevezett paraméter (nem kötelező), beleértve a dinamikus paramétereket is
Egy vagy több PowerShell-utasítás zárójelek közé zárva {}

Ha egy definícióban begin nem használja az egyik kulcsszót (process, end, , clean) , functiona PowerShell a blokkba helyezi az end utasításokat.

A függvények dynamicparam kulcsszóval és dinamikus paramétereivel kapcsolatos további információkért lásd: about_Functions_Advanced_Parameters.

A függvények lehetnek olyan egyszerűek, mint:

function Get-PowerShellProcess { Get-Process pwsh }

Miután definiált egy függvényt, a beépített parancsmagokhoz hasonlóan használhatja. Az újonnan definiált Get-PowerShellProcess függvény meghívása például:

Get-PowerShellProcess

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

A függvények olyan összetettek is lehetnek, mint a parancsmagok.

A függvények olyan értékeket adhatnak vissza, amelyek megjeleníthetők, hozzárendelhetők változókhoz, vagy átadhatók más függvényeknek vagy parancsmagoknak. A kulcsszóval visszaadhatja a return kimenetet. A return kulcsszó nem befolyásolja vagy nem tiltja le a függvényből visszaadott egyéb kimeneteket. A return kulcsszó azonban kilép a függvényből az adott sorban. További információ: about_Return.

Szűrőszintaxis

A függvény célja, filter hogy a folyamat minden objektumán futó függvényt rövid úton definiáljon.

A szűrő szintaxisa a következő:

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

A függvények szintaxisának filter leegyszerűsítéséhez hagyja ki az utasításblokk kulcsszót (begin, process, , end). clean A PowerShell a blokkba helyezi az process utasításokat. A szűrőfüggvények bármely más blokkját használhatja, de a szándék az volt, hogy rövid úton definiáljon egy függvényt, amelynek egyetlen célja a folyamat egyes objektumainak feldolgozása.

A következő szűrő naplóbejegyzéseket vesz fel a folyamatból, majd megjeleníti a teljes bejegyzést, vagy csak a bejegyzés üzenetrészét:

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

A következő módon használható:

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

Bemeneti feldolgozási módszerek

Az ebben a szakaszban leírt módszereket bemeneti feldolgozási módszereknek nevezzük. A függvények esetében ez a beginhárom metódus a függvény , processés end blokkjainak használatával van elnevezve. A PowerShell 7.3 egy clean blokkfolyamat-metódust ad hozzá.

Ezen blokkok egyikét sem kell használnia a függvényekben. Ha nem használ elnevezett blokkot, akkor a PowerShell a függvény end blokkjába helyezi a kódot. Ha azonban ezen elnevezett blokkok bármelyikét használja, vagy definiál egy dynamicparam blokkot, az összes kódot elnevezett blokkba kell helyeznie.

Az alábbi példa egy olyan függvény vázlatát mutatja be, amely egy blokkot begin tartalmaz az egyszeri előfeldolgozáshoz, egy process blokkadatokat a folyamatból, valamint egy blokkot end az egyszeri feldolgozás után.

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

`begin`

Ez a blokk a függvény opcionális egyszeri előfeldolgozásának biztosítására szolgál. A PowerShell-futtatókörnyezet a blokkban lévő kódot egyszer használja a folyamatfüggvény minden példányához.

`process`

Ez a blokk a függvény rekordonkénti feldolgozásának biztosítására szolgál. A process blokkokat a többi blokk definiálása nélkül is használhatja. A process blokkvégrehajtások száma attól függ, hogyan használja a függvényt, és milyen bemenetet kap a függvény.

Az automatikus változó $_ vagy $PSItem a folyamat aktuális objektumát tartalmazza a process blokkban való használatra. Az $input automatikus változó egy olyan enumerátort tartalmaz, amely csak függvények és szkriptblokkok számára érhető el. További információ: about_Automatic_Variables.

Ha a függvényt folyamatbemenet nélkül hívja meg, a PowerShell csak egyszer hajtja végre a process blokkot.
A folyamaton belül a process blokk minden olyan bemeneti objektum esetében egyszer fut, amely eléri a függvényt.
Ha a függvényt elérő folyamat bemenete üres, a process blokk nem fut.
- A begin, endés clean blokkok továbbra is futnak.

Fontos

Ha egy függvényparaméter elfogadja a folyamatbemenetet process , és a blokk nincs definiálva, a rekordonkénti feldolgozás meghiúsul. Ebben az esetben a függvény csak egyszer fut, a bemenettől függetlenül.

`end`

Ezzel a blokkban opcionális egyszeri utófeldolgozást adhat meg a függvényhez.

`clean`

A clean blokk a PowerShell 7.3-ban lett hozzáadva.

A clean blokk kényelmes módot nyújt a felhasználók számára a begin, processés end blokkokra kiterjedő erőforrások eltávolítására. Szemantikailag hasonló egy finally blokkhoz, amely egy szkriptfüggvény vagy egy szkriptparancsmag összes többi elnevezett blokkját lefedi. Az erőforrás-törlés a következő esetekben lesz kényszerítve:

ha a folyamat végrehajtása megszakítási hiba nélkül befejeződik
ha a folyamat végrehajtása leállási hiba miatt megszakad
ha a folyamat csonkolt, például: Select-Object -First
ha a folyamat le van állítva a Ctrl+c vagy a StopProcessing()

A tiszta blokk elveti a Siker streambe írt kimeneteket.

Figyelmeztet

A clean blokk hozzáadása kompatibilitástörő változás. Mivel clean kulcsszóként van elemezve, megakadályozza, hogy a felhasználók közvetlenül meghívják a szkriptblokk első utasításaként elnevezett clean parancsot. Ez azonban nem valószínű, hogy probléma lenne. A parancsot továbbra is meghívhatja a híváskezelővel (& clean).

Egyszerű függvények

A függvények nem kell bonyolultak ahhoz, hogy hasznosak legyenek. A legegyszerűbb függvények formátuma a következő:

function <function-name> { statements }

Az alábbi függvény például a Futtatás rendszergazdaként beállítással indítja el a PowerShellt.

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

A függvény használatához írja be a következőt: Start-PSAdmin

Ha utasításokat szeretne hozzáadni a függvényhez, írjon be minden utasítást egy külön sorba, vagy használjon pontosvesszőt (;) az utasítások elválasztásához.

Az alábbi függvény például megkeresi az összes olyan .jpg fájlt az aktuális felhasználó címtáraiban, amelyek a kezdési dátum után módosultak.

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

A hasznos kis függvények eszköztárát is létrehozhatja. Adja hozzá ezeket a függvényeket a PowerShell-profiljához a jelen cikk about_Profiles és későbbi részében leírtak szerint.

Függvénynevek

Bármilyen nevet hozzárendelhet egy függvényhez. A másokkal megosztott függvények esetében azonban a szokásos PowerShell-elnevezési szabályokat kell követnie.

A neveknek egy olyan főnévpárból kell állniuk, ahol az ige azonosítja a függvény által végrehajtott műveletet, a főnév pedig azt az elemet azonosítja, amelyen a parancsmag végrehajtja a műveletet.
A neveknek a jóváhagyott igéket kell használniuk az összes PowerShell-parancshoz. A jóváhagyott parancsok használata konzisztenciát hoz létre a felhasználók számára.

A szabványos PowerShell-igékről további információt Jóváhagyott igékcímű témakörben talál.

Paraméterekkel rendelkező függvények

Paramétereket használhat függvényekkel, beleértve az elnevezett paramétereket, a pozícióparamétereket, a kapcsolóparamétereket és a dinamikus paramétereket. További információ a függvények dinamikus paramétereiről: about_Functions_Advanced_Parameters.

Elnevezett paraméterek

Tetszőleges számú elnevezett paramétert definiálhat. Az elnevezett paraméterek alapértelmezett értékét a cikk későbbi részében leírtak szerint is megadhatja.

A zárójeleken belüli paramétereket a param kulcsszóval határozhatja meg, ahogyan az alábbi szintaxisban látható:

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

A param kulcsszó nélkül is definiálhat paramétereket a kapcsos zárójeleken kívül, ahogyan az a következő szintaxisban látható:

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

Az alábbi függvény például az alternatív szintaxist használja két paraméter definiálásához:

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

Bár az első módszer előnyben részesített, nincs különbség a két módszer között.

A függvény futtatásakor a paraméterhez megadott érték egy olyan változóhoz lesz hozzárendelve, amely tartalmazza a paraméter nevét. A változó értéke használható a függvényben.

Az alábbi példa egy Get-SmallFilesnevű függvény. Ez a függvény egy $Size paraméterrel rendelkezik. A függvény megjeleníti az összes olyan fájlt, amely kisebb, mint a $Size paraméter értéke, és kizárja a könyvtárakat:

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

A függvényben használhatja a $Size változót, amely a paraméterhez definiált név.

A függvény használatához írja be a következő parancsot:

Get-SmallFiles -Size 50

Egy elnevezett paraméter értékét a paraméter neve nélkül is megadhatja. A következő parancs például ugyanazt az eredményt adja, mint a Size paraméter neve:

Get-SmallFiles 50

Egy paraméter alapértelmezett értékének meghatározásához írjon be egy egyenlőségjelet és egy értéket a paraméter neve után, ahogyan az a Get-SmallFiles-példa alábbi változatában látható:

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

Ha érték nélkül írja be Get-SmallFiles, a függvény 100-et rendel $size. Ha értéket ad meg, a függvény ezt az értéket használja.

Ha szeretné, megadhat egy rövid súgósztringet, amely leírja a paraméter alapértelmezett értékét, ha hozzáadja a PSDefaultValue attribútumot a paraméter leírásához, és megadja PSDefaultValue Súgó tulajdonságát. Ha a függvény Get-SmallFiles paraméterének alapértelmezett értékét (100) leíró súgósztringet szeretne megadni, adja hozzá a PSDefaultValue attribútumot az alábbi példában látható módon.

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

A PSDefaultValue attribútumosztályról további információt a PSDefaultValue attribútumosztály PSDefaultValue attribútumtagokcímű témakörben talál.

Pozícióparaméterek

A pozícióparaméter egy paraméternév nélküli paraméter. A PowerShell a paraméter értékrendjével társítja az egyes paraméterértékeket a függvény egy paraméteréhez.

Pozícióparaméterek használatakor írjon be egy vagy több értéket a függvény neve után. A helyparaméter-értékek a $args tömbváltozóhoz vannak rendelve. A függvény nevét követő érték a $args tömb első pozíciójához van hozzárendelve, $args[0].

A következő Get-Extension függvény hozzáadja a .txt fájlnévkiterjesztést a megadott fájlnévhez:

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

Get-Extension myTextFile

myTextFile.txt

Paraméterek váltása

A kapcsoló olyan paraméter, amely nem igényel értéket. Ehelyett írja be a függvény nevét, majd a kapcsolóparaméter nevét.

Kapcsolóparaméter definiálásához adja meg a paraméter neve előtti [switch] típust, ahogyan az a következő példában látható:

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

Ha a On kapcsolóparamétert a függvény neve után írja be, a függvény Switch onjelenik meg. A kapcsolóparaméter nélkül Switch offjelenik meg.

Switch-Item -On

Switch on

Switch-Item

Switch off

A függvény futtatásakor logikai értéket is hozzárendelhet egy kapcsolóhoz, ahogyan az alábbi példában látható:

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Paraméterértékek átadása splatting használatával

A splatting használatával egy parancs paramétereit jelölheti. Ez a funkció a Windows PowerShell 3.0-ban jelenik meg.

Ezt a technikát a munkamenetben parancsokat hívó függvényekben használhatja. A parancsparaméterek módosításakor nem kell deklarálnia vagy számba vennie a parancsparamétereket, illetve módosítania a függvényt.

Az alábbi mintafüggvény meghívja a Get-Command parancsmagot. A parancs a @argsparamétereinek megjelenítéséhez Get-Command használ.

function Get-MyCommand { Get-Command @args }

A Get-Command összes paraméterét használhatja a Get-MyCommand függvény meghívásakor. A paramétereket és paraméterértékeket a rendszer @argshasználatával továbbítja a parancsnak.

Get-MyCommand -Name Get-ChildItem

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

A @args funkció az $args automatikus paramétert használja, amely a nem be nem jelentett parancsmagparamétereket és a fennmaradó argumentumokból származó értékeket jelöli.

További információ: about_Splatting.

Objektumok becsatolása függvényekhez

Bármely függvény képes bemenetet venni a folyamatból. A függvények begin, process, endés clean kulcsszavak használatával szabályozhatják, hogyan dolgozza fel a folyamat bemeneteit. Az alábbi mintaszintaxis az alábbi kulcsszavakat mutatja be:

A process utasításlista a folyamat minden objektumához egyszer fut. Amíg a process blokk fut, a rendszer minden folyamatobjektumot hozzárendel a $_ automatikus változóhoz, egyszerre egy folyamatobjektumhoz.

Az alábbi függvény a process kulcsszót használja. A függvény a folyamat értékeit jeleníti meg:

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

1, 2, 4 | Get-Pipeline

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

Ha olyan függvényt szeretne, amely képes folyamatbemenetet vagy bemenetet felvenni egy paraméterből, akkor a process blokknak mindkét esetet kezelnie kell. Például:

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

    begin { $retValue = 0 }

    process {
        if ($MyInvocation.ExpectingInput) {
           "Pipeline input: $_"
           $retValue += $_
        } else {
           foreach ($n in $Numbers) {
               "Command line input: $n"
               $retValue += $n
           }
        }
    }

    end { "Sum = $retValue" }
}


PS> 1,2,3,4 | Get-SumOfNumbers
Pipeline input: 1
Pipeline input: 2
Pipeline input: 3
Pipeline input: 4
Sum = 10
PS> Get-SumOfNumbers 1,2,3,4
Command line input: 1
Command line input: 2
Command line input: 3
Command line input: 4
Sum = 10

Amikor függvényt használ egy folyamatban, a függvényhez tartozó objektumok hozzá lesznek rendelve az $input automatikus változóhoz. A függvény utasításokat futtat az begin utasításblokkdal, mielőtt bármilyen objektum származik a folyamatból. A függvény utasításokat futtat az end utasításblokkdal, ha nincs több objektum a folyamatban.

Az alábbi példa az és az $inputbeginend utasításblokkokban használt automatikus változót mutatja be.

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

Amikor folyamatbemenettel futtatja a függvényt, az a következő eredményeket jeleníti meg:

1, 2, 4 | Get-PipelineBeginEnd

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

A begin utasítás futtatásakor a függvény nem rendelkezik a folyamat bemenetével. A end utasítás azután fut, hogy a függvény tartalmazza az értékeket.

Ha a függvény process kulcsszóval rendelkezik, a $input minden objektuma törlődik a $input és hozzá lesz rendelve $_. Az alábbi példa egy process utasításlistával rendelkezik:

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

Ebben a példában a függvényhez tartozó összes objektumot a rendszer elküldi az process utasításlistára. A process utasítások minden objektumon, egyszerre egy objektumon futnak. A $input automatikus változó üres, amikor a függvény eléri a end kulcsszót.

1, 2, 4 | Get-PipelineInput

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

További információ: Enumerators használata

A PowerShell 7.3 hozzáadta a clean blokkot. A clean blokk kényelmes módot biztosít a felhasználók számára a begin, processés end blokkokban létrehozott és használt erőforrások eltávolítására. Szemantikailag hasonló egy finally blokkhoz, amely egy szkriptfüggvény vagy egy szkriptparancsmag összes többi elnevezett blokkját lefedi. Az erőforrás-törlés a következő esetekben lesz kényszerítve:

ha a folyamat végrehajtása normál módon fejeződik be, megszakítási hiba nélkül
ha a folyamat végrehajtása leállási hiba miatt megszakad
ha a folyamat csonkolt, például: Select-Object -First
ha a folyamat le van állítva a Ctrl+C billentyűkombinációval vagy StopProcessing()

Figyelmeztet

A clean blokk hozzáadása kompatibilitástörő változás. Mivel clean kulcsszóként van elemezve, megakadályozza, hogy a felhasználók közvetlenül meghívják a szkriptblokk első utasításaként elnevezett clean parancsot. Ez azonban nem valószínű, hogy probléma lenne. A parancs továbbra is meghívható a híváskezelővel (& clean).

Függvény hatóköre

Egy függvény létezik abban a hatókörben, amelyben létre szeretné hozni.

Ha egy függvény egy szkript része, a függvény elérhető az adott szkripten belüli utasításokhoz. Alapértelmezés szerint a szkriptek egyik függvénye nem érhető el az adott szkripten kívül.

Megadhatja egy függvény hatókörét. A függvény például a következő példában lesz hozzáadva a globális hatókörhöz:

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

Ha egy függvény a globális hatókörben van, használhatja a függvényt szkriptekben, függvényekben és parancssorban.

A függvények új hatókört hoznak létre. A függvényben létrehozott elemek, például a változók csak a függvény hatókörében léteznek.

További információ: about_Scopes.

Függvények keresése és kezelése a `Function:` meghajtóval

A PowerShell összes függvénye és szűrője automatikusan a Function: meghajtón lesz tárolva. Ezt a meghajtót a PowerShell függvényszolgáltatója teszi elérhetővé.

Amikor a Function: meghajtóra hivatkozik, írjon be egy kettőspontot függvényután, ahogyan azt a számítógép C vagy D meghajtójára való hivatkozáskor tenné.

Az alábbi parancs megjeleníti a PowerShell aktuális munkamenetének összes függvényét:

Get-ChildItem Function:

A függvény parancsai szkriptblokkként vannak tárolva a függvény definíciótulajdonságában. Ha például a PowerShellhez tartozó súgófüggvényben szeretné megjeleníteni a parancsokat, írja be a következőt:

(Get-ChildItem Function:help).Definition

Az alábbi szintaxist is használhatja.

$Function:help

További információ: about_Function_Provider.

Függvények újrafelhasználása új munkamenetekben

Amikor függvényt ír be a PowerShell parancssorba, a függvény az aktuális munkamenet részévé válik. A függvény a munkamenet végéig érhető el.

Ha a függvényt minden PowerShell-munkamenetben használni szeretné, adja hozzá a függvényt a PowerShell-profiljához. További információ a profilokról: about_Profiles.

A függvényt PowerShell-szkriptfájlba is mentheti. Írja be a függvényt egy szövegfájlba, majd mentse a fájlt a .ps1 fájlnévkiterjesztéssel.

Súgó létrehozása függvényekhez

A Get-Help parancsmag segítséget kap a függvényekhez, parancsmagokhoz, szolgáltatókhoz és szkriptekhez. Ha segítségre van szüksége egy függvényhez, írja be a Get-Help, majd a függvény nevét.

Ha például segítségre van szüksége a Get-MyDisks függvényhez, írja be a következőt:

Get-Help Get-MyDisks

Egy függvényhez az alábbi két módszer egyikével írhat segítséget:

Comment-Based Függvények súgója

Segítség létrehozása speciális kulcsszavak használatával a megjegyzésekben. Ha megjegyzésalapú súgót szeretne létrehozni egy függvényhez, a megjegyzéseket a függvény elején, végén vagy törzsében kell elhelyezni. További információ a megjegyzésalapú súgóról: about_Comment_Based_Help.
XML-Based Függvények súgója

XML-alapú segítségre van szükség, ha a súgótartalmat több nyelvre kell honosítani. Ha a függvényt az XML-alapú súgófájlhoz szeretné társítani, használja a .EXTERNALHELP megjegyzésalapú súgó kulcsszót. E kulcsszó nélkül nem található a függvény súgófájlja, Get-Help és csak az automatikusan létrehozott súgót adja vissza.

A .EXTERNALHELP kulcsszóval kapcsolatos további információkért lásd: about_Comment_Based_Help. További információ az XML-alapú súgóról: Parancsmag írása súgó.

Lásd még

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-01-18