about_Functions_Advanced_Methods

  • Cikk

Rövid leírás

Azt ismerteti, hogy az 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

Az CmdletBinding attribútumot meghatározó függvények a változón keresztül további metódusokhoz és tulajdonságokhoz férhetnek $PSCmdlet hozzá. 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.
  • ShouldContinue A ShouldProcess felhasználói visszajelzések a művelet végrehajtása előtt történő lekéréséhez használt módszerek.
  • A ThrowTerminatingError hibarekordok létrehozásának módja.
  • 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ó: System.Management.Automation.PSCmdlet.

Az attribútummal kapcsolatos további információkért lásd: CmdletBinding 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 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{}
}

Feljegyzés

Ezek a blokkok az összes függvényre vonatkoznak, nem csak az 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 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.

Amikor olyan függvényt hoz létre, amely elfogadja a folyamat bemenetét és használja CmdletBinding, a blokknak a process folyamatbemenethez megadott paraméterváltozót kell használnia $_ ahelyett vagy $PSItemhelyett. Példa:

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

  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. ha a folyamat leállítása a következő: Select-Object -First
  4. 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).

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 Process{} függvény blokkjából hívható meg. Az CmdletBinding attribútumnak azt is deklarálnia kell, hogy a függvény támogatja ShouldProcess (ahogy az előző példában is látható).

A metódussal kapcsolatos további információkért lásd: 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.

ShouldContinue

Ez a metódus egy második megerősítést kérő üzenet igénylésére van meghívva. A metódus visszatérésekor ShouldProcess$truemeg kell hívni. A metódussal kapcsolatos további információkért lásd: System.Management.Automation.Cmdlet.ShouldContinue.

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 leállási hiba történik, és a függvény nem folytatható, a metódust kell meghívnia ThrowTerminatingError . Az utasítással megszüntetheti a Throw hibákat, és az Írási hiba parancsmagot is használhatja a nem végződő hibákhoz.

További információ: 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 metódussal kapcsolatos információkért lásd: WriteCommandDetailsSystem.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ó: System.Management.Automation.Cmdlet.WriteDebug.

WriteError

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ó: System.Management.Automation.Cmdlet.WriteError.

Feljegyzés

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

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 WriteObject ezt a módszert kell használni, amikor a függvény adatokat ad vissza. További információ: 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 a folyamatinformációk megjelenítéséhez. Megjelenítheti például a készültségi arányt. További információ: System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Ha részletes információkat szeretne nyújtani a függvény működéséről, hívja meg a metódust, WriteVerbose 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ó: 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ó: System.Management.Automation.PSCmdlet.WriteWarning.

Feljegyzés

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

Egyéb módszerek és tulajdonságok

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

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