about_Functions_CmdletBindingAttribute
Letzte Aktualisierung: Mai 2014
Betrifft: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
THEMA
about_Functions_CmdletBindingAttribute
KURZE BESCHREIBUNG
Beschreibt das Attribut, das bewirkt, dass eine Funktion wie ein kompiliertes Cmdlet funktioniert.
LANGE BESCHREIBUNG
Das CmdletBinding-Attribut ist ein Attribut von Funktionen, mit der so funktionieren wie kompilierte Cmdlets, die in C# geschrieben wurden, und es bietet Zugriff auf die Features von Cmdlets.
Windows PowerShell® bindet die Parameter von Funktionen, die über das CmdletBinding-Attribut verfügen, in gleicher Weise ein, wie es die Parameter von kompilierten Cmdlets einbindet. Für Funktionen, die über das CmdletBinding-Attribut verfügen, ist die automatische Variable „$PSCmdlet“ verfügbar sind, aber die $Args-Variable ist nicht verfügbar.
Bei Funktionen, die über das CmdletBinding-Attribut verfügen, führen unbekannte Parameter und Positionsargumente, die keine übereinstimmenden Positionsparameter haben, dazu, dass die Parameterbindung fehlschlägt.
Hinweis: Kompilierte Cmdlets verwenden das erforderliche Cmdlet-Attribut, das dem CmdletBinding-Attribut ähnelt, welches in diesem Thema beschrieben wird.
SYNTAX
Das folgende Beispiel zeigt das Format einer Funktion, die die 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{}
}
ConfirmImpact
Das ConfirmImpact-Argument gibt an, wann die Aktion der Funktion durch einen Aufruf der ShouldProcess-Methode bestätigt werden soll. Der Aufruf der ShouldProcess-Methode zeigt nur dann eine Bestätigungsaufforderung an, wenn das ConfirmImpact-Argument gleich oder größer als der Wert der $ConfirmPreference-Voreinstellungsvariable ist. (Der Standardwert des Arguments ist „Medium“.) Geben Sie dieses Argument nur an, wenn das SupportsShouldProcess-Argument ebenfalls angegeben ist.
Weitere Informationen zu Bestätigungsanforderungen finden Sie unter „Requesting Confirmation“ in der MSDN (Microsoft Developer Network)-Bibliothek unter https://go.microsoft.com/fwlink/?LinkId=136658.
DefaultParameterSetName
Das DefaultParameterSetName-Argument gibt den Namen des Parametersatzes an, das Windows PowerShell versucht zu verwenden, wenn es nicht ermitteln kann, welcher Parametersatz zu verwenden ist. Sie können dieses Problem vermeiden, indem Sie den eindeutigen Parameter von jedem Parametersatz zu einem obligatorischen Parameter machen.
HelpURI
Das HelpURI-Argument gibt die Internet-Adresse (Uniform Resource Identifier (URI)) der Online-Version des Hilfethemas an, welches die Funktion beschreibt. Der Wert der HelpURI-Arguments muss „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ückgibt.
Wenn allerdings Hilfedateien auf dem Computer installiert sind und der Wert des ersten Links im RelatedLinks-Abschnitt der Hilfedatei ein URI ist oder der Wert des ersten .Link-Anweisung in befehlsbasierter Hilfe ein URI ist, dann wird der URI in der Hilfedatei wird als Wert der HelpUri-Eigenschaft der Funktion verwendet.
Das Get-Help-Cmdlet verwendet den Wert der HelpURI-Eigenschaft, um die Online-Version des Hilfethemas zur Funktion zu suchen, wenn der Online-Parameter von Get-Help in einem Befehl angegeben ist.
SupportsPaging
Das SupportsPaging-Argument fügt der Funktion die First-, Skip- und IncludeTotalCount-Parameter hinzu. Mit diesen Parametern können Benutzer die Ausgabe aus einer sehr umfangreichen Ergebnismenge auswählen. Dieses Argument wurde für Cmdlets und Funktionen entwickelt, die Daten aus großen Datenspeichern zurückgeben und die Datenauswahl unterstützen, z. B. eine SQLDatenbank.
Dieses Argument wurde in Windows PowerShell 3.0 eingeführt.
First:
Ruft nur die ersten 'n' Objekte ab.
Skip:
Ignoriert die ersten 'n' Objekte und ruft anschließend die übrigen Objekte ab.
IncludeTotalCount:
Gibt die Anzahl an Objekten im Datensatz an (ganze Zahl) zurück, gefolgt von den Objekten. Wenn das Cmdlet die Gesamtanzahl nicht ermitteln kann, gibt es die Meldung „Unbekannte Gesamtanzahl“ zurück.
Windows PowerShell enthält NewTotalCount, eine Hilfsmethode, die den zurückzugebenen Gesamtanzahl-Wert abruft und eine Schätzung der Genauigkeit des Gesamtanzahl-Werts einschließt.
Die folgende Beispielfunktion veranschaulicht, wie Unterstützung für die Paging-Parameter zu einer erweiterten Funktion hinzugefügt wird.
function Get-Numbers
{
[CmdletBinding(SupportsPaging = $true)]
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 SupportsShouldProcess-Argument fügt der Funktion die Confirm- und WhatIf-Parameter hinzu. Durch den Confirm-Parameter wird der Benutzer vor der Ausführung des Befehls an jedem Objekt in der Pipeline zur Bestätigung aufgefordert. Der WhatIf-Parameter listet anstelle der Befehlsausführung die Änderungen auf, die der Befehl vornehmen würde.
PositionalBinding
Das PositionalBinding-Argument bestimmt, ob Parameter in der Funktion standardmäßig Positionsparameter sind. Der Standardwert ist „$True“. Sie können das PositionalBinding-Argument können mit einem Wert „$False“ verwenden, um die Positionsbindung zu deaktivieren.
Das PositionalBinding-Argument wurde mit Windows PowerShell3.0 eingeführt.
Wenn es sich bei Parametern um Positionsparameter handelt, ist der Name des Parameters optional. Windows PowerShell ordnet die unbenannten Parameterwerte den Funktionsparametern entsprechend der Reihenfolge oder der Position der unbenannten Parameterwerte im Funktionsbefehl zu.
Wenn es sich bei Parametern nicht um Positionsparameter handelt (sie sind „benannt“), ist in dem Befehl der Parametername (oder eine Abkürzung oder ein Alias des Namens) erforderlich.
Wenn PositionalBinding den Wert „$True“ hat, handelt es sich bei Funktionsparameter standardmäßig um Positionsparameter. Windows PowerShell weist den Parametern Positionsnummern in der Reihenfolge zu, in der sie in der Funktion deklariert sind.
Wenn PositionalBinding den Wert „$False“ hat, handelt es sich bei Funktionsparameter standardmäßig nicht um Positionsparameter. Außer wenn das Position-Argument des Parameter-Attributs deklariert wurde, muss der Parametername (oder ein Alias oder eine Abkürzung) enthalten sein, wenn der Parameter in einer Funktion verwendet wird.
Das Position-Argument des Parameter-Attributs hat Vorrang vor dem PositionalBinding-Standardwert. Sie können das Position-Argument verwenden, um einen Positionswert für einen Parameter anzugeben. Weitere Informationen zum Position-Argument finden Sie unter „about_Functions_Advanced_Parameters“ (https://go.microsoft.com/fwlink/?LinkID=135173).
NOTIZEN
Das SupportsTransactions-Argument wird in erweiterten Funktionen nicht unterstützt.
SCHLÜSSELWÖRTER
about_Functions_CmdletBinding_Attribute
SIEHE AUCH
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_OutputTypeAttribute