Freigeben über

about_Functions_CmdletBindingAttribute

Kurzbeschreibung

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

Lange Beschreibung

Das attribut CmdletBinding ist ein Attribut von Funktionen, das sie wie kompilierte Cmdlets funktioniert, die in C# geschrieben wurden. Sie bietet Zugriff auf die Features von Cmdlets.

Wenn Sie das attribut CmdletBinding 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 finden Sie unter about_CommonParameters.

PowerShell bindet die Parameter von Funktionen, die das attribut CmdletBinding auf die gleiche Weise aufweisen, wie sie die Parameter von kompilierten Cmdlets bindet. Die $PSCmdlet automatische Variable ist für Funktionen mit dem attribut CmdletBinding verfügbar, die $args Variable ist jedoch nicht verfügbar.

In Funktionen mit dem attribut CmdletBinding führen unbekannte Parameter und Positionsargumente ohne übereinstimmende Positionsparameter zu einem Fehler bei der Parameterbindung.

Anmerkung

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

Syntax

Das folgende Beispiel zeigt das Format einer Funktion, die alle optionalen Argumente des attributs CmdletBinding 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 Attributstandard für False-, wenn aus dem attribut CmdletBinding weggelassen wird. Legen Sie den Argumentwert auf $true fest, oder listen Sie das Argument einfach anhand des Namens auf. Beispielsweise sind die folgenden CmdletBinding- Attribute 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 Argument ConfirmImpact gleich oder größer als der Wert der $ConfirmPreference Einstellungsvariable ist. (Der Standardwert des Arguments ist Medium.) 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.

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 HelpUri Argumentwert wird für den Wert der HelpUri--Eigenschaft des CommandInfo-Objekts verwendet, das für die Funktion zurückgegeben Get-Command.

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 des ersten .LINK Schlüsselworts in der kommentarbasierten Hilfe ein URI ist, wird der URI in der Hilfedatei als Wert der HelpUri Eigenschaft der Funktion verwendet.

Das cmdlet Get-Help verwendet den Wert der HelpUri--Eigenschaft, um die Onlineversion des Funktionshilfethemas zu suchen, wenn der Online--Parameter von Get-Help in einem Befehl angegeben wird.

SupportsPaging

Das Argument SupportsPaging fügt der Funktion die Parameter First, Skipund 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.

  • First: Ruft nur die ersten n -Objekte ab.
  • Überspringen sie: 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 Gesamtanzahlwerts 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 der Funktion Confirm hinzu und WhatIf-Parameter. Der Bestätigen 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. Der Standardwert ist $true. Sie können das argument PositionalBinding mit dem Wert $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 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$trueist, 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$falseist, sind Funktionsparameter standardmäßig nicht positional. Sofern das argument Position argument des Parameter attributs 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 argument 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.

Hinweise

Das argument SupportsTransactions wird in erweiterten Funktionen nicht unterstützt.

Schlüsselwörter

about_Functions_CmdletBinding_Attribute

Siehe auch

  • Last updated on