about_Functions_CmdletBindingAttribute
Korte beschrijving
Beschrijft het kenmerk waardoor een functie werkt als een gecompileerde cmdlet.
Lange beschrijving
Het CmdletBinding kenmerk is een kenmerk van functies waardoor ze werken als gecompileerde cmdlets die zijn geschreven in C#. Het biedt toegang tot de functies van cmdlets.
PowerShell verbindt de parameters van functies die het CmdletBinding kenmerk hebben op dezelfde manier als de parameters van gecompileerde cmdlets. De $PSCmdlet automatische variabele is beschikbaar voor functies met het CmdletBinding kenmerk, maar de $Args variabele is niet beschikbaar.
In functies die het CmdletBinding kenmerk hebben, zorgen onbekende parameters en positionele argumenten die geen overeenkomende positionele parameters hebben ervoor dat de parameterbinding mislukt.
Notitie
Gecompileerde cmdlets gebruiken het vereiste Cmdlet kenmerk, dat vergelijkbaar is met het CmdletBinding kenmerk dat in dit onderwerp wordt beschreven.
Syntax
In het volgende voorbeeld ziet u de indeling van een functie die alle optionele argumenten van het CmdletBinding kenmerk opgeeft. 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 kenmerk CmdletBinding zijn standaard ingesteld op False wanneer deze worden weggelaten uit het kenmerk CmdletBinding . Stel de waarde van het argument 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 van 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 als het argument SupportsShouldProcess ook is opgegeven.
Zie Bevestiging aanvragen voor meer informatie over bevestigingsaanvragen.
DefaultParameterSetName
Het argument DefaultParameterSetName geeft de naam op van de parameterset die PowerShell probeert te gebruiken wanneer niet kan worden bepaald welke parameterset moet worden gebruikt. U kunt dit probleem voorkomen door van 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 waarde van het argument HelpURI wordt gebruikt voor de waarde van de eigenschap HelpURI van het object CommandInfo dat Get-Command retourneert voor de functie.
Wanneer er echter Help-bestanden op de computer zijn geïnstalleerd en de waarde van de eerste koppeling in de sectie RelatedLinks van het Help-bestand een URI is, of als de waarde van de eerste .Link instructie in op opmerkingen gebaseerde Help een URI is, wordt de URI in het Help-bestand gebruikt als de waarde van de eigenschap HelpUri van de functie.
De Get-Help cmdlet 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
Met het argument SupportsPaging worden de parameters First, Skip en IncludeTotalCount toegevoegd 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 totaal aantal' geretourneerd.
PowerShell bevat NewTotalCount, een helpermethode die de waarde van het totale aantal retourneert en een schatting van de nauwkeurigheid van de totale tellingswaarde bevat.
De volgende voorbeeldfunctie laat zien 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
}
SupportsShouldProcess
Met het argument SupportsShouldProcess worden de parameters Confirm en WhatIf aan de functie toegevoegd. De parameter Confirm vraagt de gebruiker om de opdracht uit te voeren op elk object in de pijplijn. De WhatIf parameter vermeldt 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 gebruiken met de waarde van $False om positionele binding uit te schakelen.
Het argument PositionalBinding is geïntroduceerd in Windows PowerShell 3.0.
Wanneer parameters positioneel zijn, is de parameternaam optioneel. PowerShell koppelt naamloze parameterwaarden aan de functieparameters op basis van de volgorde of positie van de naamloze parameterwaarden in de functieopdracht.
Wanneer parameters niet positioneel zijn (ze hebben een 'naam'), 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 zijn gedeclareerd in de functie.
Wanneer PositionalBinding is $False, zijn functieparameters niet standaard positioneel. Tenzij het argument Positie van het kenmerk Parameter is gedeclareerd voor de parameter, moet de parameternaam (of een alias of afkorting) worden opgenomen wanneer de parameter wordt gebruikt in een functie.
Het argument Position van het kenmerk Parameter heeft voorrang op de standaardwaarde PositionalBinding . U kunt het argument Positie gebruiken om een positiewaarde voor een parameter op te geven. Zie about_Functions_Advanced_Parameters voor meer informatie over het argument Positie.
Notities
Het argument SupportsTransactions wordt niet ondersteund in geavanceerde functies.
Trefwoorden
about_Functions_CmdletBinding_Attribute