about_Functions_CmdletBindingAttribute

Cikk
10/04/2023

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.

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 $Truefü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 $Falsefü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