about_Functions_CmdletBindingAttribute

Artikel
07/03/2024

Kort beskrivning

Beskriver attributet som gör att en funktion fungerar som en kompilerad cmdlet.

Lång beskrivning

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

När du använder attributet CmdletBinding lägger PowerShell automatiskt till de gemensamma parametrarna. Du kan inte skapa några parametrar som använder samma namn som de gemensamma parametrarna. Mer information finns i about_CommonParameters.

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 leder okända parametrar och positionsargument som inte har några matchande positionsparametrar till att parameterbindningen misslyckas.

Kommentar

Kompilerade cmdletar använder det obligatoriska Cmdlet attributet, som liknar det CmdletBinding attribut 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{}
}

De booleska argumenttyperna för attributet CmdletBinding är standardvärdet False när det utelämnas från attributet CmdletBinding . Ange argumentvärdet till $true eller visa bara argumentet efter namn. Följande CmdletBinding-attribut är till exempel likvärdiga.

{
    [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

Argumentet ConfirmImpact anger när funktionens åtgärd 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 kan 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 egenskapen HelpURI 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 dataval, till exempel en SQL-databas.

Det här argumentet introducerades i Windows PowerShell 3.0.

Första: Hämtar endast 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 returnerar den "Okänt totalt antal".

PowerShell innehåller NewTotalCount, en hjälpmetod som hämtar det totala antalet värden 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)]
    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 positionsnummer till parametrarna i den ordning 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.

Dela via