Megosztás a következőn keresztül:

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 listában szereplő utasítások úgy futnak, mintha beírta volna őket a parancssorba.

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

function Get-PowerShellProcess { Get-Process PowerShell }

A függvények olyan összetettek is lehetnek, mint egy parancsmag vagy egy alkalmazás.

A parancsmagokhoz hasonlóan a függvényeknek is lehetnek paramétereik. A paraméterek lehetnek névvel ellátott, pozíciós, kapcsoló vagy dinamikus paraméterek. A függvényparaméterek beolvashatók a parancssorból vagy a folyamatból.

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 return kulcsszóval is megadhat visszatérési értéket. A return kulcsszó nem befolyásolja vagy nem tiltja le a függvényből visszaadott egyéb kimeneteket. A return kulcsszó azonban ezen a sorban kilép a függvényből. További információ: about_Return.

A függvény utasításlistája különböző típusú utasításlistákat tartalmazhat begin, process, endés cleankulcsszavakkal. Ezek az utasításlisták másképp kezelik a folyamat bemeneteit.

A szűrő kulcsszóval olyan típusú függvényt hozhat létre, amely a folyamat minden objektumán fut. A szűrő hasonlít egy process blokk összes utasításával rendelkező függvényre.

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 programozás nélkül C# . 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.

Szemantika

A függvény szintaxisa a következő:

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

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

  • Kulcsszó function
  • Hatókör (nem kötelező)
  • A kiválasztott név
  • Tetszőleges számú elnevezett paraméter (nem kötelező)
  • Egy vagy több PowerShell-parancs zárójelek közé {}

A függvények kulcsszójáról dynamicparam és dinamikus paramétereiről további információt a about_Functions_Advanced_Parameters talál.

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 ezt a három metódust a függvény begin, processés end blokkja jelöli. 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 körvonalát mutatja be, amely begin blokkot tartalmaz az egyszeri előfeldolgozáshoz, egy process blokkot több rekord feldolgozásához, valamint egy end blokkot az egyszeri utófeldolgozáshoz.

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óért tekintse meg az *about_Automatic_Variables* témakört a éscímkék alatt.

  • A függvény meghívása egy folyamat elején vagy egy folyamaton kívül egyszer végrehajtja 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ő folyamatbemenet üres, a process blokk nem végrehajtani.
    • A begin, endés clean blokkok továbbra is futnak.

Fontos

Ha egy függvényparaméter úgy van beállítva, hogy fogadja el a folyamatbemenetet, és nincs definiálva process blokk, a rekordonkénti feldolgozás sikertelen lesz. Ebben az esetben a függvény csak egyszer lesz végrehajtva, a bemenettől függetlenül.

end

Ez a blokk a függvény opcionális egyszeri utófeldolgozásának biztosítására szolgál.

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:

  1. ha a folyamat végrehajtása normál módon fejeződik be, megszakítási hiba nélkül
  2. ha a folyamat végrehajtása leállási hiba miatt megszakad
  3. Amikor a Select-Object -First leállítja a pipeline-t.
  4. ha a csővezeték leállítása által Ctrl+c vagy StopProcessing() történik

Figyelmeztetés

A clean blokk hozzáadása jelentős változás, amely kompatibilitási problémákat okozhat. Mivel a clean kulcsszóként van elemezve, megakadályozza, hogy a felhasználók közvetlenül meghívják az clean nevű parancsot egy szkriptblokk első utasításaként. Ez azonban nem valószínű, hogy probléma lenne. A parancs továbbra is meghívható 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 az aktuális felhasználó címtáraiban található összes .jpg olyan fájlt megkeresi, amely a kezdési dátum után módosult.

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

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 témakör about_Profiles és újabb részében leírtak szerint.

Függvénynevek

Bármilyen nevet hozzárendelhet egy függvényhez, de a másokkal megosztott függvényeknek az összes PowerShell-parancshoz létrehozott elnevezési szabályokat kell követniük.

A függvényneveknek egy ige-főnév pá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 függvényeknek az összes PowerShell-parancshoz jóváhagyott szabványos parancsokat kell használniuk. Ezek az igék segítenek nekünk abban, hogy a parancsneveket egységesen és könnyen megérthessük a felhasználók számára.

A szabványos PowerShell-igékről további információt a Jóváhagyott igék cí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 jelen témakör későbbi részében leírtak szerint is megadhatja.

A kapcsos zárójeleken belüli paramétereket a param kulcsszó használatával határozhatja meg, ahogyan az a következő szintaxisban is látható:

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

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

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

Az alábbiakban egy példa látható erre az alternatív szintaxisra.

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 függvény neve Get-SmallFiles. Ez a függvény paraméterrel $Size rendelkezik. A függvény megjeleníti az összes olyan fájlt, amely kisebb, mint a paraméter értéke, és kizárja a $Size 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étert elnevező parancs:

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 ír Get-SmallFiles , a függvény 100-et rendel hozzá $size. Ha értéket ad meg, a függvény ezt az értéket használja.

Igény szerint megadhat egy rövid súgósztringet, amely leírja a paraméter alapértelmezett értékét. Ehhez adja hozzá a PSDefaultValue attribútumot a paraméter leírásához, és adja meg a PSDefaultValue súgótulajdonságát. Ha a függvény Méret paraméterének Get-SmallFiles 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
  )
}

A PSDefaultValue attribútumosztályról további információt a PSDefaultValue attribútumtagok cí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ékei a tömbváltozóhoz $args vannak rendelve. A függvény nevét követő érték a tömb első pozíciójához $args van 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 típust [switch] az alábbi példában látható módon:

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

Amikor a kapcsolóparamétert a On függvény neve után írja be, a függvény megjelenik Switch on. A kapcsolóparaméter nélkül megjelenik Switch off.

Switch-Item -on

Switch on

Switch-Item

Switch off

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Splatting használata parancsparaméterek megjelenítéséhez

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 @Args a Get-Command.

function Get-MyCommand { Get-Command @Args }

A függvény hívásához Get-Command használhatja az összes paramétert Get-MyCommand . A paramétereket és a paraméterértékeket a rendszer a paranccsal továbbítja a parancsnak @Args.

Get-MyCommand -Name Get-ChildItem

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

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

További információkért tekintse meg a következőket: about_Splatting.

Objektumok piping to Functions

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:

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

Az alábbi függvény a kulcsszót process 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 ($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

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 az begin kulcsszóval futtat utasításokat, mielőtt bármilyen objektum származik a folyamatból. A függvény az end kulcsszóval futtatja az utasításokat, miután az összes objektum megérkezett a folyamatból.

Az alábbi példa az $input automatikus változót mutatja be begin és end kulcsszavakkal.

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

Ha ez a függvény a folyamat használatával fut, a következő eredményeket jeleníti meg:

1,2,4 | Get-PipelineBeginEnd

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

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

Ha a függvény rendelkezik egy kulcsszóval process , a rendszer minden benne lévő $input objektumot $input eltávolít, és hozzá $_van 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 minden olyan objektumot, amely a függvényhez van csövezve, a process utasításlistára kerül. Az process utasítások minden objektumon, egyszerre egy objektumon futnak. Az $input automatikus változó üres, amikor a függvény eléri a kulcsszót end .

1,2,4 | Get-PipelineInput

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

További információ: Enumerátorok 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:

  1. ha a folyamat végrehajtása normál módon fejeződik be, megszakítási hiba nélkül
  2. ha a folyamat végrehajtása leállási hiba miatt megszakad
  3. Amikor a Select-Object -First leállítja a pipeline-t.
  4. ha a folyamat leállítása Ctrl+C vagy StopProcessing()

Figyelmeztetés

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

Szűrők

A szűrő olyan függvénytípus, amely a folyamat minden objektumán fut. A szűrő hasonlít egy process blokk összes utasításával rendelkező függvényre.

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

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

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

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

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

Függvény hatóköre

A függvény abban a hatókörben létezik, amelyben létre van hozva.

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ó található a about_Scopesrészben.

Függvények keresése és kezelése a következő függvény használatával: Meghajtó

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ó teszi közzé.

Amikor a Function: meghajtóra hivatkozik, írjon be egy kettőspontot a Függvény után, ugyanúgy, ahogy a számítógép vagy C a D számítógép 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

A Function: meghajtóval kapcsolatos további információkért tekintse meg a függvény szolgáltatójának súgótémakörét. Gépelje be: Get-Help Function.

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ó írása a Függvényekhez

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

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

Get-Help Get-MyDisks

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

  • Megjegyzéseken alapuló súgó függvényekhez

    Súgótémakör 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 törzsének elején vagy végén, illetve a függvény kulcsszó előtti sorokban kell elhelyezni. További információ a megjegyzésalapú súgóról: about_Comment_Based_Help.

  • XML-alapú súgó függvényekhez

    Hozzon létre egy XML-alapú súgótémakört, például a parancsmagokhoz általában létrehozott típust. XML-alapú segítségre van szükség, ha a súgótémaköröket több nyelvre honosítja.

    Ha a függvényt az XML-alapú súgótémakörhöz szeretné társítani, használja a .EXTERNALHELP megjegyzésalapú súgó kulcsszót. E kulcsszó nélkül Get-Help nem találja a függvény súgótémakörét, és a függvényhez Get-Help hívásai csak automatikusan generált súgót adnak vissza.

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

Lásd még

  • Last updated on