about_Functions_CmdletBindingAttribute

Kurze Beschreibung

Beschreibt das Attribut, mit dem eine Funktion wie ein kompiliertes Cmdlet funktioniert.

Lange Beschreibung

Das -Attribut ist ein Attribut von Funktionen, mit denen sie wie kompilierte Cmdlets funktionieren, CmdletBinding die in C# geschrieben wurden. Sie bietet Zugriff auf die Funktionen von Cmdlets.

PowerShell bindet die Parameter von Funktionen, die über das -Attribut verfügen, auf die gleiche Weise wie die Parameter CmdletBinding kompilierter Cmdlets. Die $PSCmdlet automatische Variable ist für Funktionen mit dem -Attribut CmdletBinding verfügbar, aber die Variable ist nicht $Args verfügbar.

In Funktionen mit dem -Attribut führen unbekannte Parameter und Positionsargumente ohne übereinstimmende Positionsparameter dazu, dass die CmdletBinding Parameterbindung fehlschlägt.

Hinweis

Kompilierte Cmdlets verwenden das erforderliche Attribut, das dem in diesem Thema Cmdlet CmdletBinding beschriebenen Attribut ähnelt.

Syntax

Das folgende Beispiel zeigt das Format einer Funktion, die alle optionalen Argumente des Attributs CmdletBinding angibt. Diesem Beispiel folgt eine kurze Beschreibung der einzelnen Argumente.

{
    [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 Einstellungsvariablen $ConfirmPreference ist. (Der Standardwert des Arguments ist Mittel.) Geben Sie dieses Argument nur an, wenn auch das SupportsShouldProcess-Argument angegeben ist.

Weitere Informationen zu Bestätigungsanforderungen finden Sie unter Anfordern der Bestätigung.

DefaultParameterSetName

Das DefaultParameterSetName-Argument gibt den Namen des Parametersets an, den PowerShell verwenden soll, wenn nicht bestimmt werden kann, welcher Parametersatz verwendet werden soll. Sie können dieses Problem vermeiden, indem Sie den eindeutigen Parameter jedes Parameters als obligatorischen Parameter festlegen.

HelpURI

Das HelpURI-Argument gibt die Internetadresse der Onlineversion des Hilfethemas an, in dem die Funktion beschrieben wird. Der Wert des HelpURI-Arguments muss mit "http" oder "https" beginnen.

Der HelpURI-Argumentwert wird für den Wert der HelpURI-Eigenschaft des CommandInfo-Objekts verwendet, das Get-Command für die Funktion zurückgibt.

Wenn jedoch Hilfedateien auf dem Computer installiert sind und der Wert des ersten Links im Abschnitt RelatedLinks der Hilfedatei ein URI ist oder der Wert der ersten Direktive in der kommentarbasierten Hilfe ein URI ist, wird der URI in der Hilfedatei als Wert der .Link HelpUri-Eigenschaft der Funktion verwendet.

Das Get-Help Cmdlet verwendet den Wert der HelpURI-Eigenschaft, um die Onlineversion des Hilfethemas der Funktion zu suchen, wenn der Online-Parameter von in einem Befehl Get-Help angegeben wird.

SupportsPaging

Das SupportsPaging-Argument fügt der Funktion die Parameter First, Skip und IncludeTotalCount hinzu. Mit diesen Parametern können Benutzer die Ausgabe eines sehr großen Resultsets auswählen. Dieses Argument ist für Cmdlets und Funktionen konzipiert, 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.

  • First: Ruft nur die ersten "n"-Objekte ab.
  • Skip: Ignoriert die ersten "n"-Objekte und ruft dann die verbleibenden Objekte ab.
  • IncludeTotalCount: Gibt die Anzahl der Objekte im DataSet (eine ganze Zahl) gefolgt von den -Objekten an. Wenn das Cmdlet die Gesamtanzahl nicht bestimmen kann, gibt es "Unknown total count" zurück.

PowerShell enthält NewTotalCount, eine Hilfsmethode, die den zurückzukehrenden Gesamtwert ruft und eine Schätzung der Genauigkeit des Gesamtwerts enthält.

Die folgende Beispielfunktion zeigt, wie Sie einer erweiterten Funktion Unterstützung für die Pagingparameter hinzufügen.

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 Parameter Confirm und WhatIf hinzu. Der Confirm-Parameter fordert den Benutzer auf, den Befehl für jedes Objekt in der Pipeline auszuführen. Der WhatIf-Parameter listet die Änderungen auf, die der Befehl vornehmen würde, anstatt den Befehl auszuführen.

PositionalBinding

Das PositionalBinding-Argument bestimmt, ob Parameter in der Funktion standardmäßig positioniert sind. Der Standardwert ist $True. Sie können das PositionalBinding-Argument mit dem Wert verwenden, $False um die Positionsbindung zu deaktivieren.

Das Argument PositionalBinding wird in Windows PowerShell 3.0 eingeführt.

Wenn Parameter positional sind, ist der Parametername optional. PowerShell ordnet den Funktionsparametern unbenannte Parameterwerte entsprechend der Reihenfolge oder Position der unbenannten Parameterwerte 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 auf $True festgelegt ist, 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 auf $False festgelegt ist, sind Funktionsparameter standardmäßig nicht positional. Sofern das Position-Argument des Parameterattributs 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 Position-Argument 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 SupportsTransactions-Argument wird in erweiterten Funktionen nicht unterstützt.

Schlüsselwörter

about_Functions_CmdletBinding_Attribute

Weitere Informationen

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute