about_Functions

Cikk
03/13/2024

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 kulcsszóval return visszatérési értéket is megadhat. 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 a kulcsszavakkal begin, processés endclean. 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 blokk összes utasításával rendelkező függvényre process .

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.

Syntax

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ójelben {}

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 beginfüggvény , processés end blokkja jelöli. A PowerShell 7.3 blokkfolyamat-metódust clean 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 blokkjába helyezi a end kódot. Ha azonban ezen elnevezett blokkok bármelyikét használja, vagy egy blokkot dynamicparam definiál, az összes kódot elnevezett blokkba kell helyeznie.

Az alábbi példa egy olyan függvény körvonalát mutatja be, amely egy blokkot begin tartalmaz az egyszeri előfeldolgozáshoz, egy blokkot process több rekord feldolgozásához, 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 blokkokat process a többi blokk definiálása nélkül is használhatja. A blokkvégrehajtások száma process 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 blokkban process való használatra. Az $input automatikus változó olyan számbavételt tartalmaz, amely csak függvények és szkriptblokkok számára érhető el. További információ: about_Automatic_Variables.

A függvény meghívása a folyamat elején vagy azon kívül 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 a blokkok továbbra is futnak.

Fontos

Ha egy függvényparaméter úgy van beállítva, hogy fogadja el a folyamatbemenetet, és nincs megadva blokk process , 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ódja annak, hogy a felhasználók megtisztítsa azokat az erőforrásokat, amelyek a beginteljes , processés end blokkokra kiterjednek. Szemantikailag hasonló egy finally olyan 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 leállítása a következő: Select-Object -First
ha a folyamat le van állítva a Ctrl+c vagy a StopProcessing()

Figyelemfelhívás

clean A 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).

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 Rendszergazda istrator 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ó: about_Splatting.

Objektumok piping to Functions

Bármely függvény képes bemenetet venni a folyamatból. Szabályozhatja, hogy egy függvény hogyan dolgozza fel a folyamat bemenetét a , process, endés clean kulcsszavak használatávalbegin. 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élda:

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

Az alábbi példa az automatikus változót és end kulcsszavakat $inputbegin mutatja be.

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 rendszer elküldi az process utasításlistára. 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 blokkot clean . A clean blokk kényelmes módja annak, hogy a felhasználók megtisztítják a , processés blokkokban beginlétrehozott és end használt erőforrásokat. Szemantikailag hasonló egy finally olyan 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 leállítása a következő: Select-Object -First
ha a folyamat le van állítva a Ctrl+C billentyűkombinációval vagyStopProcessing()

Figyelemfelhívás

Szűrők

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

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ó: about_Scopes.

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 D a C 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 meghajtóval kapcsolatos Function: további információkért tekintse meg a függvényszolgáltató 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, szolgáltatókhoz és 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 nem található a függvény súgótémaköre, Get-Help és a függvényhez Get-Help intézett hívások 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. Az XML-alapú súgóról további információt a Parancsmag írása súgójában talál.