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

Függvényekkel_Kapcsolatos_Előrehaladott_Módszerek

Rövid leírás

Ismerteti, hogy a CmdletBinding attribútumot meghatározó függvények hogyan használhatják a lefordított parancsmagok számára elérhető metódusokat és tulajdonságokat.

Hosszú leírás

A CmdletBinding attribútumot meghatározó függvények további metódusokhoz és tulajdonságokhoz férhetnek hozzá a $PSCmdlet változón keresztül. Ezek a módszerek a következő módszereket tartalmazzák:

  • Ugyanazok a bemeneti feldolgozási módszerek érhetők el az összes függvény számára.
  • A ShouldProcess és ShouldContinue metódusok, amelyek a felhasználói visszajelzések lekérésére szolgálnak a művelet végrehajtása előtt.
  • A hibarekordok létrehozásának ThrowTerminatingError metódusa.
  • Számos Write metódus, amelyek különböző típusú kimeneteket adnak vissza.

A PSCmdlet osztály összes metódusa és tulajdonsága elérhető a speciális függvények számára. További információért lásd: System.Management.Automation.PSCmdlet.

A CmdletBinding attribútummal kapcsolatos további információkért lásd: about_Functions_CmdletBindingAttribute. A CmdletBindingAttribute osztályért lásd: System.Management.Automation.Cmdlet.CmdletBindingAttribute.

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

Jegyzet

Ezek a blokkok az összes függvényre vonatkoznak, nem csak a CmdletBinding attribútumot használó függvényekre.

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ókért lásd a(z) about_Automatic_Variables.

  • 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.

Amikor olyan függvényt hoz létre, amely elfogadja a folyamatbemenetet, és CmdletBindinghasznál, a process blokknak a folyamatbemenethez definiált paraméterváltozót kell használnia $_ vagy $PSItemhelyett. Például:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

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

A tiszta blokk eldob minden kimenetet, amit a Success adatfolyamra írtak.

Vigyázat

A clean blokk hozzáadása jelentős változás, amely kompatibilitási problémákat okozhat. 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).

Megerősítési módszerek

ShouldProcess

Ezt a metódust úgy hívjuk meg, hogy megerősítést kérjen a felhasználótól, mielőtt a függvény végrehajtana egy olyan műveletet, amely megváltoztatná a rendszert. A függvény a metódus által visszaadott logikai érték alapján folytatható. Ez a metódus csak a függvény process {} blokkjából hívható meg. A CmdletBinding attribútumnak azt is deklarálnia kell, hogy a függvény támogatja a ShouldProcess (ahogy az előző példában is látható).

További információért erről a metódusról, lásd a(z) System.Management.Automation.Cmdlet.ShouldProcess.

További információ a megerősítés kéréséről: Megerősítés kérése.

KellFolytatni

Ez a metódus egy második megerősítést kérő üzenet igénylésére van meghívva. Akkor kell meghívni, amikor a ShouldProcess metódus $truead vissza. A(z) módszerről további információt a System.Management.Automation.Cmdlet.ShouldContinue-nál talál.

Hibametelyek

A függvények két különböző metódust hívhatnak meg hibák esetén. Ha nem végződő hiba történik, a függvénynek meg kell hívnia a WriteError metódust, amelyet a Write metódusok szakasz ismertet. Ha megszűnő hiba lép fel, és a függvény nem folytatható, a ThrowTerminatingError metódust kell meghívnia. A throw utasítással leállíthatja az hibákat, és a Write-Error parancsmagot is használhatja a nem végzetes hibákhoz.

További információért lásd: System.Management.Automation.Cmdlet.ThrowTerminatingError.

Írási módszerek

A függvények a következő metódusokat hívhatják meg különböző típusú kimenetek visszaadásához. Figyelje meg, hogy nem minden kimenet megy a folyamat következő parancsára. Használhatja a különböző Write parancsmagokat is, például Write-Error.

WriteCommandDetail

A WriteCommandDetails metódussal kapcsolatos információkért lásd a System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

A függvény hibaelhárításához használható információk megadásához hívja meg a függvényt a WriteDebug metódussal. A WriteDebug metódus hibakeresési üzeneteket jelenít meg a felhasználónak. További információért lásd: System.Management.Automation.Cmdlet.WriteDebug.

Írási hiba

A függvényeknek ezt a metódust akkor kell meghívni, ha nem végződő hibák lépnek fel, és a függvény a rekordok feldolgozásának folytatására van kialakítva. További információkért lásd: System.Management.Automation.Cmdlet.WriteError.

Jegyzet

Ha megszűnési hiba történik, a függvénynek meghívnia kell a ThrowTerminatingError metódust.

WriteObject

A WriteObject metódus lehetővé teszi, hogy a függvény objektumot küldjön a folyamat következő parancsára. A legtöbb esetben a WriteObject az a módszer, amelyet akkor kell használni, amikor a függvény adatokat ad vissza. További információért lásd: System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

A hosszú ideig tartó műveleteket tartalmazó függvények esetében ez a metódus lehetővé teszi, hogy a függvény meghívja a WriteProgress metódust, hogy megjelenjenek a folyamat előrehaladási adatai. Megjelenítheti például a készültségi arányt. További információ: System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

A függvény működésével kapcsolatos részletes információk megadásához hívja meg a WriteVerbose metódust, hogy részletes üzeneteket jelenítsen meg a felhasználónak. Alapértelmezés szerint a részletes üzenetek nem jelennek meg. További információkért lásd: System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Ha információt szeretne adni a váratlan eredményeket okozó feltételekről, a függvény hívja meg a WriteWarning metódust, hogy figyelmeztető üzeneteket jelenítsen meg a felhasználónak. Alapértelmezés szerint figyelmeztető üzenetek jelennek meg. További információért lásd: System.Management.Automation.PSCmdlet.WriteWarning.

Jegyzet

A figyelmeztető üzeneteket a $WarningPreference változó konfigurálásával vagy a Verbose és Debug parancssori beállítások használatával is megjelenítheti. A $WarningPreference változóval kapcsolatos további információkért lásd: about_Preference_Variables.

Egyéb módszerek és tulajdonságok

A $PSCmdlet változón keresztül elérhető egyéb módszerekről és tulajdonságokról a System.Management.Automation.PSCmdlet című témakörben talál további információt.

A ParameterSetName tulajdonság például lehetővé teszi a használt paraméterkészlet megtekintését. A paraméterkészletek lehetővé teszik olyan függvények létrehozását, amelyek a függvény futtatásakor megadott paraméterek alapján különböző feladatokat hajtanak végre.

Lásd még

  • Last updated on