Delen via

about_Functions_CmdletBindingAttribute

Korte beschrijving

Beschrijft het kenmerk waarmee een functie werkt als een gecompileerde cmdlet.

Lange beschrijving

Het kenmerk CmdletBinding is een kenmerk van functies waarmee ze werken als gecompileerde cmdlets die zijn geschreven in C#. Het biedt toegang tot de functies van cmdlets.

Wanneer u het kenmerk CmdletBinding gebruikt, worden in PowerShell automatisch de algemene parameters toegevoegd. U kunt geen parameters maken die dezelfde namen gebruiken als de algemene parameters. Zie about_CommonParametersvoor meer informatie.

PowerShell verbindt de parameters van functies met het kenmerk CmdletBinding op dezelfde manier als de parameters van gecompileerde cmdlets. De $PSCmdlet automatische variabele is beschikbaar voor functies met het kenmerk CmdletBinding, maar de $args variabele is niet beschikbaar.

In functies met het kenmerk CmdletBinding, onbekende parameters en positionele argumenten zonder overeenkomende positionele parameters, kunnen parameterbindingen mislukken.

Notitie

Gecompileerde cmdlets maken gebruik van het vereiste Cmdlet kenmerk, dat vergelijkbaar is met het CmdletBinding kenmerk dat in dit onderwerp wordt beschreven.

Syntaxis

In het volgende voorbeeld ziet u de indeling van een functie waarmee alle optionele argumenten van het kenmerk CmdletBinding worden opgegeven. Een korte beschrijving van elk argument volgt dit voorbeeld.

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

    param ($Parameter1)
    begin {}
    process {}
    end {}
}

De booleaanse argumenttypen van het CmdletBinding kenmerk worden standaard ingesteld op False wanneer deze worden weggelaten uit het CmdletBinding kenmerk. Stel de argumentwaarde in op $true of vermeld het argument op naam. De volgende CmdletBinding kenmerken zijn bijvoorbeeld gelijkwaardig.

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

Het argument ConfirmImpact geeft aan wanneer de actie van de functie moet worden bevestigd door een aanroep naar de methode ShouldProcess. De aanroep van de methode ShouldProcess geeft alleen een bevestigingsprompt weer wanneer het argument ConfirmImpact gelijk is aan of groter is dan de waarde van de $ConfirmPreference voorkeursvariabele. (De standaardwaarde van het argument is Gemiddeld.) Geef dit argument alleen op wanneer het argument SupportsShouldProcess ook is opgegeven.

Zie Bevestigingsaanvraagvoor meer informatie over bevestigingsaanvragen.

DefaultParameterSetName

Het argument DefaultParameterSetName geeft de naam op van de parameterset die PowerShell probeert te gebruiken wanneer deze niet kan bepalen welke parameter moet worden gebruikt. U kunt dit probleem voorkomen door de unieke parameter van elke parameterset een verplichte parameter te maken.

HelpURI

Het argument HelpUri geeft het internetadres op van de onlineversie van het Help-onderwerp waarin de functie wordt beschreven. De waarde van het argument HelpUri moet beginnen met 'http' of 'https'.

De HelpUri argumentwaarde wordt gebruikt voor de waarde van de eigenschap HelpUri van het CommandInfo-object dat Get-Command retourneert voor de functie.

Wanneer Help-bestanden echter zijn geïnstalleerd op de computer en de waarde van de eerste koppeling in de sectie RelatedLinks van het Help-bestand een URI is, of de waarde van het eerste .LINK trefwoord in hulp op basis van opmerkingen een URI is, wordt de URI in het Help-bestand gebruikt als de waarde van de HelpUri eigenschap van de functie.

De cmdlet Get-Help gebruikt de waarde van de eigenschap HelpUri om de onlineversie van het Help-onderwerp van de functie te vinden wanneer de parameter Online van Get-Help is opgegeven in een opdracht.

SupportsPaging

Het argument SupportsPaging voegt de parameters First, Skipen IncludeTotalCount parameters toe aan de functie. Met deze parameters kunnen gebruikers uitvoer selecteren uit een zeer grote resultatenset. Dit argument is ontworpen voor cmdlets en functies die gegevens retourneren uit grote gegevensarchieven die ondersteuning bieden voor gegevensselectie, zoals een SQL-database.

Dit argument is geïntroduceerd in Windows PowerShell 3.0.

  • Eerste: haalt alleen de eerste 'n'-objecten op.
  • overslaan: negeert de eerste 'n'-objecten en haalt vervolgens de resterende objecten op.
  • IncludeTotalCount: Rapporteert het aantal objecten in de gegevensset (een geheel getal) gevolgd door de objecten. Als de cmdlet het totale aantal niet kan bepalen, wordt 'Onbekend totaalaantal' geretourneerd.

PowerShell bevat NewTotalCount, een helpermethode waarmee de totale tellingswaarde wordt opgehaald en een schatting wordt gemaakt van de nauwkeurigheid van de totale tellingswaarde.

In de volgende voorbeeldfunctie ziet u hoe u ondersteuning voor de pagingparameters toevoegt aan een geavanceerde functie.

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
}

OndersteuntShouldProcess

Het argument SupportsShouldProcess voegt confirm en WhatIf parameters toe aan de functie. De parameter Bevestig vraagt de gebruiker om bevestiging voordat de opdracht op elk object in de pijplijn wordt uitgevoerd. De parameter WhatIf bevat de wijzigingen die de opdracht zou aanbrengen in plaats van de opdracht uit te voeren.

PositionalBinding

Het argument PositionalBinding bepaalt of parameters in de functie standaard positioneel zijn. De standaardwaarde is $true. U kunt het argument PositionalBinding met een waarde van $false gebruiken om positionele binding uit te schakelen.

Het argument PositionalBinding wordt geïntroduceerd in Windows PowerShell 3.0.

Wanneer parameters positioneel zijn, is de parameternaam optioneel. PowerShell koppelt niet-benoemde parameterwaarden aan de functieparameters volgens de volgorde of positie van de niet-benoemde parameterwaarden in de functieopdracht.

Wanneer parameters niet positioneel zijn (ze zijn "benoemd"), is de parameternaam (of een afkorting of alias van de naam) vereist in de opdracht.

Wanneer PositionalBinding is $true, zijn functieparameters standaard positioneel. PowerShell wijst positienummer toe aan de parameters in de volgorde waarin ze in de functie worden gedeclareerd.

Wanneer PositionalBinding is $false, zijn functieparameters niet standaard positioneel. Tenzij het argument Position van het kenmerk Parameter is gedeclareerd voor de parameter, moet de parameternaam (of een alias of afkorting) worden opgenomen wanneer de parameter in een functie wordt gebruikt.

Het argument Positie van het kenmerk Parameter heeft voorrang op de PositionalBinding standaardwaarde. U kunt het argument Positie gebruiken om een positiewaarde voor een parameter op te geven. Zie about_Functions_Advanced_Parametersvoor meer informatie over het argument Positie.

Opmerkingen

Het argument SupportsTransactions wordt niet ondersteund in geavanceerde functies.

Zoekwoorden

about_Functions_CmdletBinding_Attribute

Zie ook

  • Last updated on