about_Functions_CmdletBindingAttribute
Korte beschrijving
Beschrijft het kenmerk waarmee een functie werkt als een gecompileerde cmdlet.
Lange beschrijving
Het CmdletBinding kenmerk is een kenmerk van functies waarmee ze werken zoals gecompileerde cmdlets die zijn geschreven in C#. Het biedt toegang tot de functies van cmdlets.
Wanneer u het CmdletBinding kenmerk gebruikt, worden in PowerShell automatisch de algemene parameters toegevoegd. U kunt geen parameters maken die dezelfde namen gebruiken als de algemene parameters. Zie about_CommonParameters voor meer informatie.
PowerShell verbindt de parameters van functies met het CmdletBinding kenmerk 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 met het CmdletBinding kenmerk, onbekende parameters en positionele argumenten die geen overeenkomende positionele parameters hebben, kan de parameterbinding mislukken.
Notitie
Gecompileerde cmdlets gebruiken het vereiste Cmdlet kenmerk, wat 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 CmdletBinding kenmerk 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 kenmerk CmdletBinding . Stel de argumentwaarde in op $true of geef het argument op naam weer. 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 Bevestiging aanvragen voor 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 waarde van het Argument HelpURI wordt gebruikt voor de waarde van de Eigenschap HelpURI van het CommandInfo-object dat Get-Command wordt geretourneerd voor de functie.
Wanneer Help-bestanden echter 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 de waarde van de eerste .Link instructie in hulp op basis van opmerkingen is een URI, 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
Het argument SupportsPaging voegt de parameters First, Skip en IncludeTotalCount 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.
- Eerst: Hiermee haalt u alleen de eerste 'n' objecten op.
- Overslaan: hiermee worden de eerste 'n'-objecten genegeerd en worden vervolgens de resterende objecten opgehaald.
- 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 geretourneerd en een schatting bevat 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 de parameters Confirm en WhatIf toe aan de functie. Met de parameter Bevestigen wordt de gebruiker gevraagd 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 gebruiken met de waarde om $False 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 Positie van het parameterkenmerk wordt gedeclareerd voor de parameter, moet de parameternaam (of een alias of afkorting) worden opgenomen wanneer de parameter wordt gebruikt in een functie.
Het argument Positie van het parameterkenmerk 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.
Opmerkingen
Het argument SupportsTransactions wordt niet ondersteund in geavanceerde functies.
Trefwoorden
about_Functions_CmdletBinding_Attribute
