Tudnivalók a functions CmdletBindingAttributeAbout Functions CmdletBindingAttribute

Rövid leírásShort description

Leírja azt az attribútumot, amely egy függvényt, például egy lefordított parancsmagot használ.Describes the attribute that makes a function work like a compiled cmdlet.

Hosszú leírásLong description

Az CmdletBinding attribútum a függvények olyan attribútuma, amely a C#-ban írt lefordított parancsmagokhoz hasonlóan működik.The CmdletBinding attribute is an attribute of functions that makes them operate like compiled cmdlets written in C#. Hozzáférést biztosít a parancsmagok funkcióihoz.It provides access to the features of cmdlets.

A PowerShell olyan függvények paramétereit köti össze, amelyek az CmdletBinding attribútummal azonos módon kötik össze a lefordított parancsmagok paramétereit.PowerShell binds the parameters of functions that have the CmdletBinding attribute in the same way that it binds the parameters of compiled cmdlets. Az $PSCmdlet automatikus változó elérhető az attribútummal rendelkező függvények számára CmdletBinding , de a $Args változó nem érhető el.The $PSCmdlet automatic variable is available to functions with the CmdletBinding attribute, but the $Args variable is not available.

Az attribútummal rendelkező függvények esetében az CmdletBinding ismeretlen paraméterek és pozíciós argumentumok nem rendelkeznek egyező pozíciós paraméterekkel, mert a paraméter kötése sikertelen lesz.In functions that have the CmdletBinding attribute, unknown parameters and positional arguments that have no matching positional parameters cause parameter binding to fail.

Megjegyzé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.Compiled cmdlets use the required Cmdlet attribute, which is similar to the CmdletBinding attribute that is described in this topic.

SyntaxSyntax

Az alábbi példa egy függvény formátumát mutatja be, amely az attribútum összes opcionális argumentumát megadja CmdletBinding .The following example shows the format of a function that specifies all the optional arguments of the CmdletBinding attribute. Az egyes argumentumok rövid leírása a következő példát követi.A brief description of each argument follows this example.

{
    [CmdletBinding(ConfirmImpact=<String>,
    DefaultParameterSetName=<String>,
    HelpURI=<URI>,
    SupportsPaging=<Boolean>,
    SupportsShouldProcess=<Boolean>,
    PositionalBinding=<Boolean>)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ConfirmImpactConfirmImpact

A ConfirmImpact argumentum azt adja meg, hogy a függvény műveletét a ShouldProcess metódus hívásával kell-e megerősíteni.The ConfirmImpact argument specifies when the action of the function should be confirmed by a call to the ShouldProcess method. A ShouldProcess metódus hívása csak akkor jelenít meg megerősítési kérést, ha a ConfirmImpact argumentum értéke vagy nagyobb a $ConfirmPreference preferencia változó értékénél.The call to the ShouldProcess method displays a confirmation prompt only when the ConfirmImpact argument is equal to or greater than the value of the $ConfirmPreference preference variable. (Az argumentum alapértelmezett értéke közepes.) Ezt az argumentumot csak akkor adja meg, ha a helpuri argumentum is meg van adva.(The default value of the argument is Medium.) Specify this argument only when the SupportsShouldProcess argument is also specified.

További információ a megerősítő kérésekről: megerősítés kérése.For more information about confirmation requests, see Requesting Confirmation.

DefaultParameterSetNameDefaultParameterSetName

A DefaultParameterSetName argumentum megadja annak a paraméternek a nevét, amelyet a PowerShell megpróbál használni, amikor nem tudja meghatározni, hogy melyik paramétert kell használni.The DefaultParameterSetName argument specifies the name of the parameter set that PowerShell will attempt to use when it cannot determine which parameter set to use. Ezt a problémát elkerülheti úgy, hogy az egyes paraméterek egyedi paraméterét beállítja egy kötelező paraméterként.You can avoid this issue by making the unique parameter of each parameter set a mandatory parameter.

HelpURIHelpURI

A HelpURI argumentum megadja a függvényt leíró súgótémakör online verziójának internetes verzióját.The HelpURI argument specifies the internet address of the online version of the help topic that describes the function. A HelpURI argumentum értékének a "http" vagy a "https" előtaggal kell kezdődnie.The value of the HelpURI argument must begin with "http" or "https".

A HelpURI argumentum értéke a függvény által visszaadott CommandInfo objektum HelpURI tulajdonságának értékére szolgál Get-Command .The HelpURI argument value is used for the value of the HelpURI property of the CommandInfo object that Get-Command returns for the function.

Ha azonban a súgófájlok telepítve vannak a számítógépen, és a súgófájl RelatedLinks szakaszának első hivatkozás értéke egy URI, vagy a .Link Megjegyzés-alapú súgóban szereplő első direktíva egy URI, a súgófájl URI-ja a függvény HelpUri tulajdonságának értéke lesz.However, when help files are installed on the computer and the value of the first link in the RelatedLinks section of the help file is a URI, or the value of the first .Link directive in comment-based help is a URI, the URI in the help file is used as the value of the HelpUri property of the function.

A Get-Help parancsmag a HelpURI tulajdonság értékét használja, hogy megkeresse a függvény súgójának online verzióját, ha az online paraméter meg Get-Help van adva egy parancsban.The Get-Help cmdlet uses the value of the HelpURI property to locate the online version of the function help topic when the Online parameter of Get-Help is specified in a command.

SupportsPagingSupportsPaging

A SupportsPaging argumentum hozzáadja az első , a kihagyás és a IncludeTotalCount paramétereket a függvényhez.The SupportsPaging argument adds the First , Skip , and IncludeTotalCount parameters to the function. Ezek a paraméterek lehetővé teszik a felhasználók számára, hogy nagyon nagy eredményhalmaz kimenetét válasszák.These parameters allow users to select output from a very large result set. Ez az argumentum olyan parancsmagok és függvények számára készült, amelyek olyan nagy adattárakból származó adatokkal térnek vissza, amelyek támogatják az adatok kiválasztását, például egy SQL Database-adatbázist.This argument is designed for cmdlets and functions that return data from large data stores that support data selection, such as an SQL database.

Ez az argumentum a Windows PowerShell 3,0-ben lett bevezetve.This argument was introduced in Windows PowerShell 3.0.

  • Először : csak az első "n" objektumot kapja meg.First : Gets only the first 'n' objects.
  • Kihagyás : figyelmen kívül hagyja az első "n" objektumot, majd beolvassa a fennmaradó objektumokat.Skip : Ignores the first 'n' objects and then gets the remaining objects.
  • IncludeTotalCount : az adathalmazban (egész szám) lévő objektumok számát adja meg, amelyet az objektumok követnek.IncludeTotalCount : Reports the number of objects in the data set (an integer) followed by the objects. Ha a parancsmag nem tudja meghatározni a teljes darabszámot, az "ismeretlen teljes szám" értéket adja vissza.If the cmdlet cannot determine the total count, it returns "Unknown total count".

A PowerShell magában foglalja a NewTotalCount , a segítő metódust, amely a visszaadott értékek számát adja vissza, és tartalmazza az összesített darabszám értékének becslését.PowerShell includes NewTotalCount , a helper method that gets the total count value to return and includes an estimate of the accuracy of the total count value.

A következő minta függvény azt mutatja be, hogyan adhat hozzá támogatást a lapozási paraméterekhez egy speciális függvényhez.The following sample function shows how to add support for the paging parameters to an advanced function.

function Get-Numbers {
    [CmdletBinding(SupportsPaging = $true)]
    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
}

HelpuriSupportsShouldProcess

A helpuri argumentum hozzáadja a jóváhagyás és a whatIf paramétereket a függvényhez.The SupportsShouldProcess argument adds Confirm and WhatIf parameters to the function. A Confirm paraméter kéri a felhasználót, mielőtt futtatja a parancsot a folyamat minden egyes objektumán.The Confirm parameter prompts the user before it runs the command on each object in the pipeline. A whatIf paraméter felsorolja a parancs által végrehajtott módosításokat a parancs futtatása helyett.The WhatIf parameter lists the changes that the command would make, instead of running the command.

PositionalBindingPositionalBinding

A PositionalBinding argumentum határozza meg, hogy a függvényben szereplő paraméterek alapértelmezés szerint pozícionálva vannak-e.The PositionalBinding argument determines whether parameters in the function are positional by default. Az alapértelmezett érték $True.The default value is $True. A PositionalBinding argumentumot használhatja a értékkel a $False pozíciós kötés letiltásához.You can use the PositionalBinding argument with a value of $False to disable positional binding.

A PositionalBinding argumentum a Windows PowerShell 3,0-ben kerül beléptetésre.The PositionalBinding argument is introduced in Windows PowerShell 3.0.

Ha a paraméterek pozícionálva vannak, a paraméter neve nem kötelező.When parameters are positional, the parameter name is optional. A PowerShell a függvények paraméterei alapján a névvel ellátott paramétereket társítja a Function parancsban található nem megnevezett paraméterek sorrendjének vagy pozíciójának megfelelően.PowerShell associates unnamed parameter values with the function parameters according to the order or position of the unnamed parameter values in the function command.

Ha a paraméterek nem pozicionáló ("named"), akkor a parancsnak a paraméter nevét (vagy a név rövidítését vagy aliasát) kell megadnia.When parameters are not positional (they are "named"), the parameter name (or an abbreviation or alias of the name) is required in the command.

Ha PositionalBinding a PositionalBinding $True , a függvény paraméterei alapértelmezés szerint pozícionálva vannak.When PositionalBinding is $True, function parameters are positional by default. A PowerShell a függvényben deklarált sorrendben rendeli hozzá a pozíciót a paraméterekhez.PowerShell assigns position number to the parameters in the order in which they are declared in the function.

Ha PositionalBinding a PositionalBinding $False , a függvény paraméterei alapértelmezés szerint nem helyezhetők el.When PositionalBinding is $False, function parameters are not positional by default. Ha a paraméter attribútuma nem deklarálva van a paraméterben, a paraméter neve (vagy alias vagy rövidítés) szerepelnie kell, ha a paramétert egy függvényben használják.Unless the Position argument of the Parameter attribute is declared on the parameter, the parameter name (or an alias or abbreviation) must be included when the parameter is used in a function.

A paraméter attribútumának position argumentuma elsőbbséget élvez a PositionalBinding alapértelmezett értékével szemben.The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. A pozíció argumentum használatával megadhatja a paraméter pozíció értékét.You can use the Position argument to specify a position value for a parameter. További információ a pozíció argumentumról: about_Functions_Advanced_Parameters.For more information about the Position argument, see about_Functions_Advanced_Parameters.

JegyzetekNotes

A SupportsTransactions argumentum nem támogatott a speciális függvényeknél.The SupportsTransactions argument is not supported in advanced functions.

KulcsszavakKeywords

about_Functions_CmdletBinding_Attributeabout_Functions_CmdletBinding_Attribute

Lásd mégSee also

about_Functionsabout_Functions

about_Functions_Advancedabout_Functions_Advanced

about_Functions_Advanced_Methodsabout_Functions_Advanced_Methods

about_Functions_Advanced_Parametersabout_Functions_Advanced_Parameters

about_Functions_OutputTypeAttributeabout_Functions_OutputTypeAttribute