about_Functions_CmdletBindingAttribute
Kurze Beschreibung
Beschreibt das Attribut, das eine Funktion wie ein kompiliertes Cmdlet funktioniert.
Lange Beschreibung
Das CmdletBinding Attribut ist ein Attribut von Funktionen, mit dem sie wie kompilierte Cmdlets funktionieren, die in C# geschrieben wurden. Sie bietet Zugriff auf die Features von Cmdlets.
Wenn Sie das CmdletBinding Attribut verwenden, fügt PowerShell automatisch die allgemeinen Parameter hinzu. Sie können keine Parameter erstellen, die dieselben Namen wie die allgemeinen Parameter verwenden. Weitere Informationen findest du unter about_CommonParameters.
PowerShell bindet die Parameter von Funktionen, die das CmdletBinding Attribut auf die gleiche Weise aufweisen, wie sie die Parameter von kompilierten Cmdlets bindet. Die $PSCmdlet automatische Variable ist für Funktionen mit dem CmdletBinding Attribut verfügbar, die Variable ist jedoch $Args nicht verfügbar.
In Funktionen mit dem CmdletBinding Attribut führen unbekannte Parameter und Positionsargumente ohne übereinstimmende Positionsparameter dazu, dass die Parameterbindung fehlschlägt.
Hinweis
Kompilierte Cmdlets verwenden das erforderliche Cmdlet Attribut, das dem CmdletBinding attribut ähnelt, das in diesem Thema beschrieben wird.
Syntax
Das folgende Beispiel zeigt das Format einer Funktion, die alle optionalen Argumente des CmdletBinding Attributs angibt. Eine kurze Beschreibung der einzelnen Argumente folgt diesem Beispiel.
{
[CmdletBinding(ConfirmImpact=<String>,
DefaultParameterSetName=<String>,
HelpURI=<URI>,
SupportsPaging=<Boolean>,
SupportsShouldProcess=<Boolean>,
PositionalBinding=<Boolean>)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Die booleschen Argumenttypen des CmdletBinding-Attributs standardmäßig auf "False ", wenn sie aus dem CmdletBinding-Attribut weggelassen werden. Legen Sie den Argumentwert auf $true das Argument fest oder listen Sie das Argument einfach anhand des Namens auf. Die folgenden CmdletBinding-Attribute sind z. B. gleichwertig.
{
[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
Das Argument ConfirmImpact gibt an, wann die Aktion der Funktion durch einen Aufruf der ShouldProcess-Methode bestätigt werden soll. Der Aufruf der ShouldProcess-Methode zeigt eine Bestätigungsaufforderung nur an, wenn das ConfirmImpact-Argument gleich oder größer als der Wert der $ConfirmPreference Einstellungsvariable ist. (Der Standardwert des Arguments ist Mittel.) Geben Sie dieses Argument nur an, wenn das Argument SupportsShouldProcess ebenfalls angegeben wird.
Weitere Informationen zu Bestätigungsanforderungen finden Sie unter Anfordern einer Bestätigung.
DefaultParameterSetName
Das Argument DefaultParameterSetName gibt den Namen des Parametersatzes an, den PowerShell verwenden soll, wenn er nicht bestimmen kann, welcher Parameter verwendet werden soll. Sie können dieses Problem vermeiden, indem Sie den eindeutigen Parameter jedes Parameters als obligatorischen Parameter festlegen.
Hilfe-URI
Das HelpURI-Argument gibt die Internetadresse der Onlineversion des Hilfethemas an, die die Funktion beschreibt. Der Wert des HelpURI-Arguments muss mit "http" oder "https" beginnen.
Der Wert des HelpURI-Arguments wird für den Wert der HelpURI-Eigenschaft des CommandInfo-Objekts verwendet, das Get-Command für die Funktion zurückgegeben wird.
Wenn Hilfedateien jedoch auf dem Computer installiert sind und der Wert des ersten Links im Abschnitt "RelatedLinks " der Hilfedatei ein URI ist oder der Wert der ersten .Link Direktive in der kommentarbasierten Hilfe ein URI ist, wird der URI in der Hilfedatei als Wert der HelpUri-Eigenschaft der Funktion verwendet.
Das Get-Help Cmdlet verwendet den Wert der HelpURI-Eigenschaft , um die Onlineversion des Funktionshilfethemas zu suchen, wenn der Online-Parameter Get-Help in einem Befehl angegeben wird.
SupportsPaging
Das Argument SupportsPaging fügt der Funktion die Parameter "First", "Skip" und "IncludeTotalCount " hinzu. Mit diesen Parametern können Benutzer die Ausgabe aus einem sehr großen Resultset auswählen. Dieses Argument wurde für Cmdlets und Funktionen entwickelt, die Daten aus großen Datenspeichern zurückgeben, die die Datenauswahl unterstützen, z. B. eine SQL-Datenbank.
Dieses Argument wurde in Windows PowerShell 3.0 eingeführt.
- Zuerst: Ruft nur die ersten "n"-Objekte ab.
- Überspringen: Ignoriert die ersten n-Objekte und ruft dann die verbleibenden Objekte ab.
- IncludeTotalCount: Meldet die Anzahl der Objekte im Dataset (eine ganze Zahl), gefolgt von den Objekten. Wenn das Cmdlet die Gesamtanzahl nicht ermitteln kann, wird "Unbekannte Gesamtanzahl" zurückgegeben.
PowerShell enthält NewTotalCount, eine Hilfsmethode, die den zurückzugebenden Gesamtanzahlswert abruft und eine Schätzung der Genauigkeit des Gesamtanzahlswerts enthält.
Die folgende Beispielfunktion zeigt, wie Sie unterstützung für die Pagingparameter zu einer erweiterten Funktion hinzufügen.
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
Das Argument SupportsShouldProcess fügt "Confirm " und "WhatIf" -Parameter zur Funktion hinzu. Der Parameter Confirm fordert den Benutzer auf, bevor er den Befehl für jedes Objekt in der Pipeline ausführt. Der WhatIf-Parameter listet die Änderungen auf, die der Befehl vornehmen würde, anstatt den Befehl auszuführen.
PositionalBinding
Das Argument PositionalBinding bestimmt, ob Parameter in der Funktion standardmäßig positional sind. Der Standardwert ist $True. Sie können das Argument PositionalBinding mit einem Wert zum Deaktivieren der $False Positionsbindung verwenden.
Das Argument PositionalBinding wird in Windows PowerShell 3.0 eingeführt.
Wenn Parameter positional sind, ist der Parametername optional. PowerShell ordnet nicht benannte Parameterwerte den Funktionsparametern entsprechend der Reihenfolge oder Position der Werte für nicht benannte Parameter im Funktionsbefehl zu.
Wenn Parameter nicht positional sind (sie sind "benannt"), ist der Parametername (oder eine Abkürzung oder ein Alias des Namens) im Befehl erforderlich.
Wenn "PositionalBinding " lautet $True, sind Funktionsparameter standardmäßig positional. PowerShell weist den Parametern die Positionsnummer in der Reihenfolge zu, in der sie in der Funktion deklariert werden.
Wenn "PositionalBinding " lautet $False, sind Funktionsparameter standardmäßig nicht positional. Sofern das Argument Position des Parameter-Attributs nicht für den Parameter deklariert ist, muss der Parametername (oder ein Alias oder eine Abkürzung) eingeschlossen werden, wenn der Parameter in einer Funktion verwendet wird.
Das Argument Position des Parameter-Attributs hat Vorrang vor dem Standardwert PositionalBinding . Sie können das Argument Position verwenden, um einen Positionswert für einen Parameter anzugeben. Weitere Informationen zum Argument Position finden Sie unter about_Functions_Advanced_Parameters.
Hinweise
Das Argument SupportsTransactions wird in erweiterten Funktionen nicht unterstützt.
Schlüsselwörter
about_Functions_CmdletBinding_Attribute
