about_Functions_CmdletBindingAttribute
Rövid leírás
Azt az attribútumot ismerteti, amely egy függvényt lefordított parancsmagként hoz létre.
Hosszú leírás
Az CmdletBinding
attribútum a függvények attribútuma, amely úgy működik, mint a C#-ban írt lefordított parancsmagok. Hozzáférést biztosít a parancsmagok funkcióihoz.
Az attribútum használatakor a CmdletBinding
PowerShell automatikusan hozzáadja a gyakori paramétereket. Nem hozhat létre olyan paramétereket, amelyek ugyanazokat a neveket használják, mint a Common Parameters. További információ: about_CommonParameters.
A PowerShell az attribútummal rendelkező CmdletBinding
függvények paramétereit ugyanúgy köti össze, mint a lefordított parancsmagok paramétereit. Az $PSCmdlet
automatikus változó az attribútummal rendelkező függvények CmdletBinding
számára érhető el, de a $Args
változó nem érhető el.
Az attribútummal rendelkező függvényekben ismeretlen CmdletBinding
paraméterek és pozícióargumentumok, amelyek nem rendelkeznek egyező pozícióparaméterekkel, a paraméterkötés sikertelen lesz.
Feljegyzés
A lefordított parancsmagok a szükséges Cmdlet
attribútumot használják, amely hasonló a CmdletBinding
jelen témakörben ismertetett attribútumhoz.
Syntax
Az alábbi példa egy függvény formátumát mutatja be, amely az attribútum összes választható argumentumát CmdletBinding
meghatározza. Az egyes argumentumok rövid leírása ezt a példát követi.
{
[CmdletBinding(ConfirmImpact=<String>,
DefaultParameterSetName=<String>,
HelpURI=<URI>,
SupportsPaging=<Boolean>,
SupportsShouldProcess=<Boolean>,
PositionalBinding=<Boolean>)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
A CmdletBinding attribútum logikai argumentumtípusa alapértelmezés szerint Hamis, ha a CmdletBinding attribútumból hiányzik. Állítsa be az argumentum értékét név $true
szerint, vagy csak listázhatja az argumentumot. A következő CmdletBinding attribútumok például egyenértékűek.
{
[CmdletBinding(SupportsPaging=$true)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
# Boolean arguments can be defined using this shorthand syntax
{
[CmdletBinding(SupportsPaging)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
ConfirmImpact
A ConfirmImpact argumentum azt határozza meg, hogy a függvény műveletét mikor kell megerősíteni a ShouldProcess metódus hívásával. A ShouldProcess metódus hívása csak akkor jelenít meg megerősítési kérést, ha a ConfirmImpact argumentum egyenlő vagy nagyobb, mint a $ConfirmPreference
beállítási változó értéke. (Az argumentum alapértelmezett értéke: Közepes.) Ezt az argumentumot csak akkor adja meg, ha a SupportsShouldProcess argumentum is meg van adva.
A megerősítési kérelmekről további információt a Megerősítés kérése című témakörben talál.
DefaultParameterSetName
A DefaultParameterSetName argumentum megadja annak a paraméterkészletnek a nevét, amelyet a PowerShell használni fog, ha nem tudja meghatározni, hogy melyik paraméterkészletet használja. Ezt a problémát elkerülheti, ha az egyes paraméterek egyedi paraméterét kötelező paraméterként állítja be.
SúgóURI
A SúgóURI argumentum a függvényt leíró súgótémakör online verziójának internetes címét adja meg. A HelpURI argumentum értékének "http" vagy "https" értékkel kell kezdődnie.
A SúgóURI argumentum értéke a függvényhez visszaadott CommandInfo objektum Get-Command
HelpURI tulajdonságának értékéhez használatos.
Ha azonban a súgófájlok telepítve vannak a számítógépre, és a súgófájl RelatedLinks szakaszában az első hivatkozás értéke egy URI, vagy a megjegyzésalapú súgó első .Link
irányelvének értéke egy URI, a súgófájlban lévő URI a függvény HelpUri tulajdonságának értéke.
A Get-Help
parancsmag a SúgóURI tulajdonság értékét használja a függvény súgótémakörének online verziójának megkereséséhez, ha a parancsban meg van adva az Online paraméterGet-Help
.
SupportsPaging
A SupportsPaging argumentum hozzáadja az Első, a Kihagyás és az IncludeTotalCount paramétert a függvényhez. Ezek a paraméterek lehetővé teszik a felhasználók számára, hogy nagyon nagy eredményhalmazból válassza ki a kimenetet. Ez az argumentum olyan parancsmagokhoz és függvényekhez lett kialakítva, amelyek adatokat adnak vissza olyan nagy adattárakból, amelyek támogatják az adatkiválasztást, például egy SQL-adatbázist.
Ezt az argumentumot a Windows PowerShell 3.0-ban vezettük be.
- Először: Csak az első "n" objektumot kapja meg.
- Kihagyás: Figyelmen kívül hagyja az első "n" objektumokat, majd lekéri a többi objektumot.
- IncludeTotalCount: Az adathalmazban lévő objektumok számát (egész szám), majd az objektumokat jelenti. Ha a parancsmag nem tudja meghatározni a teljes darabszámot, az "Ismeretlen teljes szám" értéket adja vissza.
A PowerShell tartalmazza a NewTotalCount nevű segédmetódust, amely lekéri a teljes darabszám visszaadandó értékét, és tartalmazza a teljes számérték pontosságának becslését.
Az alábbi mintafüggvény bemutatja, hogyan adhat támogatást a lapozási paraméterekhez egy speciális függvényhez.
function Get-Numbers {
[CmdletBinding(SupportsPaging)]
param()
$FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
$LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
$FirstNumber - 1, 100)
if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
$TotalCountAccuracy = 1.0
$TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
$TotalCountAccuracy)
Write-Output $TotalCount
}
$FirstNumber .. $LastNumber | Write-Output
}
Támogatja a ShouldProcess-et
A SupportsShouldProcess argumentum megerősítési és WhatIf paramétereket ad hozzá a függvényhez. A Megerősítés paraméter kéri a felhasználót, mielőtt futtatja a parancsot a folyamat minden objektumán. A WhatIf paraméter felsorolja a parancs által végrehajtott módosításokat a parancs futtatása helyett.
PositionalBinding
A PositionalBinding argumentum határozza meg, hogy a függvény paraméterei alapértelmezés szerint pozícióban vannak-e. Az alapértelmezett érték $True
. A PositionalBinding argumentummal $False
letilthatja a pozíciókötést.
A PositionalBinding argumentum a Windows PowerShell 3.0-ban van bevezetve.
Ha a paraméterek pozícióban vannak, a paraméter neve nem kötelező. A PowerShell a meg nem nevezett paraméterértékeket a függvényparancs meg nem nevezett paraméterértékeinek sorrendje vagy pozíciója alapján társítja a függvényparaméterekhez.
Ha a paraméterek nem pozíciósak ("névvel" vannak elnevezve), a paraméter neve (vagy a név rövidítése vagy aliasa) kötelező a parancsban.
Ha a PositionalBinding értéke, a $True
függvényparaméterek alapértelmezés szerint pozicionáltak. A PowerShell pozíciószámot rendel a paraméterekhez abban a sorrendben, amelyben a függvényben deklarálva vannak.
Ha a PositionalBinding értéke, a $False
függvényparaméterek alapértelmezés szerint nem pozicionáltak. Ha a Paraméter attribútum Pozíció argumentuma nincs deklarálva a paraméteren, a paraméter nevét (aliasát vagy rövidítését) akkor kell megadni, ha a paramétert egy függvényben használják.
A Paraméter attribútum Pozíció argumentuma elsőbbséget élvez a PositionalBinding alapértelmezett értékével szemben. A Pozíció argumentum használatával megadhat egy pozícióértéket egy paraméterhez. A Pozíció argumentumról további információt a about_Functions_Advanced_Parameters talál.
Jegyzetek
A SupportTransactions argumentum speciális függvényekben nem támogatott.
Kulcsszavak
about_Functions_CmdletBinding_Attribute