about_Functions_Advanced_Methods
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
AShouldProcess
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 begin
fü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
ésclean
a blokkok továbbra is futnak.
- A
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 $PSItem
helyett. 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 begin
teljes , 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()
A tiszta blokk elveti a Siker streambe írt kimeneteket.
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
$true
meg 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: WriteCommandDetails
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ó: 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 Verbose
Debug
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.