Informationen zu Functions CmdletBindingAttribute

Artikel
05/09/2024

Kurze Beschreibung

Beschreibt das Attribut, durch 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.

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

In Funktionen, die über das CmdletBinding -Attribut verfügen, verursachen unbekannte Parameter und Positionsargumente, die keine übereinstimmenden Positionsparameter haben, einen Fehler bei der Parameterbindung.

Hinweis

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

Syntax

Das folgende Beispiel zeigt das Format einer Funktion, die alle optionalen Argumente des CmdletBinding Attributs 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 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 nur dann eine Bestätigungsaufforderung an, wenn das ConfirmImpact-Argument gleich oder größer ist als der Wert der Einstellungsvariable $ConfirmPreference . (Der Standardwert des Arguments ist Medium.) Geben Sie dieses Argument nur an, wenn auch das Argument SupportsShouldProcess angegeben ist.

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

DefaultParameterSetName

Das Argument DefaultParameterSetName gibt den Namen des Parametersatzes an, den PowerShell zu verwenden versucht, wenn der zu verwendende Parametersatz nicht bestimmt werden kann. Sie können dieses Problem vermeiden, indem Sie den eindeutigen Parameter jedes Parameters als obligatorischen Parameter festlegen.

HelpURI

Das Argument HelpURI gibt die Internetadresse der Onlineversion des Hilfethemas an, das die Funktion beschreibt. Der Wert des Arguments HelpURI muss mit "http" oder "https" beginnen.

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

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 .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 von Get-Help in einem Befehl angegeben ist.

SupportsPaging

Das SupportsPaging-Argument 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 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.
Überspringen: 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 ermitteln kann, wird "Unbekannte Gesamtanzahl" zurückgegeben.

PowerShell enthält NewTotalCount, eine Hilfsmethode, die den zurückzugebenden Gesamtanzahlwert abruft und eine Schätzung der Genauigkeit des Gesamtanzahlwerts 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, 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. Standardwert: $True. Sie können das Argument PositionalBinding mit dem Wert von $False verwenden, 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 festgelegt ist $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 ist $False, sind Funktionsparameter standardmäßig nicht positional. Es sei denn, das Argument Position des Parameter-Attributs wird für den Parameter deklariert, 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 PositionalBinding-Standardwert . 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.