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 }

Egy függvény olyan összetett is lehet, mint egy parancsmag vagy egy alkalmazásprogram.

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 tiltja le a függvény által 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és ProcessEnda . Ezek az utasításlisták másképp kezelik a folyamat bemeneteit.

A szűrő egy speciális függvény, amely a kulcsszót Filter használja.

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.

Szemantika

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

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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.

Egyszerű funkciók

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

function <function-name> {statements}

A következő függvény például elindítja a PowerShellt a Futtatás rendszergazdaként beállítással.

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, írja be az egyes utasításokat egy külön sorba, vagy pontosvesszővel ; válassza el az utasításokat.

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ények nevének egy ige-főnév párból kell állnia, amelyben az ige azonosítja a függvény által végrehajtott műveletet, a főnév pedig azt az elemet, 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 abban, hogy parancsneveink egyszerűek, következetesek és könnyen érthetőek legyenek a felhasználók számára.

További információ a szabványos PowerShell-műveletekről: Jóváhagyott műveletek a Microsoft Docsban.

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óval határozhatja meg, ahogy az az alábbi mintaszintaxisban 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($one, $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 fájlnévkiterjesztést .txt 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" }
}

Ha a kapcsoló paraméterét a funkció neve után írja On be, a funkció a "Bekapcsolás" feliratot jeleníti meg. A kapcsolóparaméter nélkül a "Kikapcsolás" felirat jelenik meg.

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. Nem kell deklarálnia vagy számba vennie a parancsparamétereket, és nem kell módosítania a függvényt a parancsparaméterek módosításakor.

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ásakor Get-Command az összes paramétert Get-MyCommand használhatja. 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ó a fröccsenésről: 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 , Beginés Process kulcsszavak használatávalEnd. Az alábbi mintaszintaxis a három kulcsszót mutatja be:

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

Az Begin utasításlista csak egyszer fut, a függvény elején.

Fontos

Ha a függvény definiál egy Beginblokkot ProcessEnd , akkor az összes kódnak az egyik blokkon belül kell lennie.

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.

Miután a függvény megkapta a folyamat összes objektumát, az End utasításlista egyszer fut. Ha nem Beginhasznál , Process, vagy End kulcsszavakat, a rendszer az összes utasítást utasításlistaként End kezeli.

Az alábbi függvény a kulcsszót Process használja. A függvény példákat jelenít meg a folyamatból:

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

A funkció bemutatásához adjon meg egy vesszővel elválasztott számlistát, ahogy az alábbi példában látható:

1,2,4 | Get-Pipeline

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

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 ezt a függvényt a folyamat használatával futtatja, a következő eredményeket jeleníti meg:

1,2,4 | Get-PipelineBeginEnd

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

Az Begin 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 a függvénybe továbbított összes objektumot a rendszer elküldi az Process utasításlistának. 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

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 { $_ }
}

Függvény hatóköre

A függvény abban a hatókörben létezik, amelyben létrehozták.

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 parancsfájl egyik függvénye nem érhető el a parancssorban.

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 általában 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ó a PowerShell hatóköréről: 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 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 munkamenet végéig elérhető.

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

A függvényekhez az alábbi két módszer valamelyikével írhat súgót:

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

Hozzon létre egy súgótémakört 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ény csak Get-Help automatikusan generált súgót ad 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 az MSDN-könyvtár Parancsmag írása súgójában talál.