Om Functions CmdletBindingAttribute

Artikel
06/21/2023

Kort beskrivning

Beskriver attributet som får en funktion att fungera som en kompilerad cmdlet.

Lång beskrivning

Attributet CmdletBinding är ett attribut för funktioner som gör att de fungerar som kompilerade cmdletar som skrivits i C#. Den ger åtkomst till funktionerna i cmdletar.

PowerShell binder parametrarna för funktioner som har CmdletBinding attributet på samma sätt som det binder parametrarna för kompilerade cmdletar. Den $PSCmdlet automatiska variabeln är tillgänglig för funktioner med CmdletBinding attributet , men variabeln $Args är inte tillgänglig.

I funktioner som har CmdletBinding attributet misslyckas okända parametrar och positionsargument som inte har några matchande positionsparametrar.

Anteckning

Kompilerade cmdletar använder det obligatoriska Cmdlet attributet, som liknar attributet CmdletBinding som beskrivs i det här avsnittet.

Syntax

I följande exempel visas formatet för en funktion som anger alla valfria argument för attributet CmdletBinding . En kort beskrivning av varje argument följer det här exemplet.

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

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

ConfirmImpact

Argumentet ConfirmImpact anger när åtgärden för funktionen ska bekräftas av ett anrop till metoden ShouldProcess . Anropet till metoden ShouldProcess visar bara en bekräftelsefråga när argumentet ConfirmImpact är lika med eller större än värdet för $ConfirmPreference inställningsvariabeln. (Standardvärdet för argumentet är Medel.) Ange endast det här argumentet när argumentet SupportsShouldProcess också har angetts.

Mer information om bekräftelsebegäranden finns i Begära bekräftelse.

DefaultParameterSetName

Argumentet DefaultParameterSetName anger namnet på parameteruppsättningen som PowerShell försöker använda när det inte går att avgöra vilken parameter som ska användas. Du kan undvika det här problemet genom att göra den unika parametern för varje parameteruppsättning till en obligatorisk parameter.

Hjälp-URI

Argumentet HelpURI anger Internetadressen för onlineversionen av hjälpavsnittet som beskriver funktionen. Värdet för HelpURI-argumentet måste börja med "http" eller "https".

Argumentet HelpURI används för värdet för HelpURI-egenskapen för det CommandInfo-objekt som Get-Command returneras för funktionen.

Men när hjälpfiler installeras på datorn och värdet för den första länken i avsnittet RelatedLinks i hjälpfilen är en URI, eller om värdet för det första .Link direktivet i kommentarsbaserad hjälp är en URI, används URI:n i hjälpfilen som värdet för funktionens HelpUri-egenskap .

Cmdleten Get-Help använder värdet för egenskapen HelpURI för att hitta onlineversionen av funktionshjälpavsnittet när onlineparametern Get-Help för anges i ett kommando.

SupportsPaging

Argumentet SupportsPaging lägger till parametrarna First, Skip och IncludeTotalCount i funktionen. Med de här parametrarna kan användarna välja utdata från en mycket stor resultatuppsättning. Det här argumentet är utformat för cmdletar och funktioner som returnerar data från stora datalager som stöder val av data, till exempel en SQL-databas.

Det här argumentet introducerades i Windows PowerShell 3.0.

För det första: Hämtar bara de första n-objekten.
Hoppa över: Ignorerar de första n-objekten och hämtar sedan de återstående objekten.
IncludeTotalCount: Rapporterar antalet objekt i datauppsättningen (ett heltal) följt av objekten. Om cmdleten inte kan fastställa det totala antalet returneras "Okänt totalt antal".

PowerShell innehåller NewTotalCount, en hjälpmetod som hämtar det totala antalsvärdet som ska returneras och innehåller en uppskattning av noggrannheten för det totala antalet värden.

Följande exempelfunktion visar hur du lägger till stöd för växlingsparametrarna i en avancerad funktion.

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
}

SupportsShouldProcess

Argumentet SupportsShouldProcess lägger till parametrarna Confirm och WhatIf i funktionen. Parametern Bekräfta uppmanar användaren innan den kör kommandot på varje objekt i pipelinen. Parametern WhatIf visar de ändringar som kommandot skulle göra i stället för att köra kommandot .

PositionalBinding

Argumentet PositionalBinding avgör om parametrarna i funktionen är positionella som standard. Standardvärdet är $True. Du kan använda argumentet PositionalBinding med värdet $False för för att inaktivera positionsbindning.

Argumentet PositionalBinding introduceras i Windows PowerShell 3.0.

När parametrarna är positionella är parameternamnet valfritt. PowerShell associerar namnlösa parametervärden med funktionsparametrarna enligt ordningen eller positionen för de namnlösa parametervärdena i funktionskommandot.

När parametrarna inte är positionella (de är "namngivna" krävs parameternamnet (eller en förkortning eller ett alias för namnet) i kommandot .

När PositionalBinding är $Trueär funktionsparametrarna positionella som standard. PowerShell tilldelar position nummer till parametrarna i den ordning som de deklareras i funktionen.

När PositionalBinding är $Falseär funktionsparametrarna inte positionella som standard. Om inte argumentet Position för parameterattributet deklareras för parametern måste parameternamnet (eller ett alias eller en förkortning) inkluderas när parametern används i en funktion.

Argumentet Position för parameterattributet har företräde framför standardvärdet PositionalBinding. Du kan använda argumentet Position för att ange ett positionsvärde för en parameter. Mer information om argumentet Position finns i about_Functions_Advanced_Parameters.