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 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 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