about_Functions_Advanced_Parameters

Kurze Beschreibung

Erläutert das Hinzufügen von Parametern zu erweiterten Funktionen.

Lange Beschreibung

Sie können den erweiterten Funktionen, die Sie schreiben, Parameter hinzufügen und Parameterattribute und Argumente verwenden, um die Parameterwerte zu begrenzen, die Funktionsbenutzer mit dem Parameter übermitteln.

Die Parameter, die Sie ihrer Funktion hinzufügen, stehen Benutzern zusätzlich zu den allgemeinen Parametern zur Verfügung, die PowerShell allen Cmdlets und erweiterten Funktionen automatisch hinzufügt. Weitere Informationen zu den allgemeinen PowerShell-Parametern finden Sie unter about_CommonParameters.

Ab PowerShell 3.0 können Sie Splatting mit verwenden, um die @Args Parameter in einem Befehl zu darstellen. Splatting ist für einfache und erweiterte Funktionen gültig. Weitere Informationen finden Sie unter about_Functions und about_Splatting.

Typkonvertierung von Parameterwerten

Wenn Sie Zeichenfolgen als Argumente für Parameter angeben, die einen anderen Typ erwarten, konvertiert PowerShell die Zeichenfolgen implizit in den Parameterzieltyp. Erweiterte Funktionen führen eine kulturinvariante Analyse von Parameterwerten durch.

Im Gegensatz dazu wird während der Parameterbindung für kompilierte Cmdlets eine kulturempfindliche Konvertierung durchgeführt.

In diesem Beispiel erstellen wir ein Cmdlet und eine Skriptfunktion, die einen Parameter [datetime] verwenden. Die aktuelle Kultur wird geändert, um deutsche Einstellungen zu verwenden. Ein Datum im deutschen Format wird an den Parameter übergeben.

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00

Wie oben gezeigt, verwenden Cmdlets die kulturempfindliche Analyse, um die Zeichenfolge zu konvertieren.

# Define an equivalent function.
function Get-Date_Func {
  param(
    [DateTime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

Erweiterte Funktionen verwenden die kulturinvariante Analyse, was zu folgendem Fehler führt.

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error: "String
'19-06-2018' was not recognized as a valid DateTime."

Statische Parameter

Statische Parameter sind Parameter, die in der Funktion immer verfügbar sind. Die meisten Parameter in PowerShell-Cmdlets und -Skripts sind statische Parameter.

Das folgende Beispiel zeigt die Deklaration eines ComputerName-Parameters, der die folgenden Merkmale aufweist:

  • Dies ist obligatorisch (erforderlich).
  • Sie nimmt Eingaben aus der Pipeline entgegen.
  • Sie nimmt ein Array von Zeichenfolgen als Eingabe an.
Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

Attribute von Parametern

In diesem Abschnitt werden die Attribute beschrieben, die Sie Funktionsparametern hinzufügen können.

Alle Attribute sind optional. Wenn Sie jedoch das CmdletBinding-Attribut weglassen, muss die Funktion das Parameter-Attribut enthalten, um als erweiterte Funktion erkannt zu werden.

Sie können in jeder Parameterdeklaration ein oder mehrere Attribute hinzufügen. Es gibt keine Beschränkung für die Anzahl von Attributen, die Sie einer Parameterdeklaration hinzufügen können.

Parameterattribut

Das Parameter-Attribut wird verwendet, um die Attribute von Funktionsparametern zu deklarieren.

Das Parameter-Attribut ist optional, und Sie können es weglassen, wenn keiner der Parameter Ihrer Funktionen Attribute benötigt. Um jedoch nicht als einfache Funktion, sondern als erweiterte Funktion erkannt zu werden, muss eine Funktion entweder das CmdletBinding-Attribut, das Parameter-Attribut oder beides aufweisen.

Das Parameter-Attribut verfügt über Argumente, die die Merkmale des Parameters definieren, z. B. ob der Parameter obligatorisch oder optional ist.

Verwenden Sie die folgende Syntax, um das Parameter-Attribut, ein Argument und einen Argumentwert zu deklarieren. Die Klammern, die das Argument und seinen Wert einschließen, müssen parameter ohne dazwischenliegende Leerzeichen folgen.

Param(
    [Parameter(Argument=value)]
    $ParameterName
)

Verwenden Sie Kommas, um Argumente innerhalb der Klammern zu trennen. Verwenden Sie die folgende Syntax, um zwei Argumente des Parameter-Attributs zu deklarieren.

Param(
    [Parameter(Argument1=value1,
    Argument2=value2)]
)

Die booleschen Argumenttypen des Parameter-Attributs werden standardmäßig auf False festgelegt, wenn sie aus dem Parameter-Attribut weggelassen werden. Legen Sie den Argumentwert auf fest, $true oder listen Sie das Argument einfach anhand des Namens auf. Beispielsweise sind die folgenden Parameterattribute gleichwertig.

Param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

Param(
    [Parameter(Mandatory)]
)

Wenn Sie das Parameter-Attribut ohne Argumente als Alternative zur Verwendung des CmdletBinding-Attributs verwenden, sind die Klammern, die dem Attributnamen folgen, weiterhin erforderlich.

Param(
    [Parameter()]
    $ParameterName
)

Obligatorisches Argument

Das Mandatory Argument gibt an, dass der Parameter erforderlich ist. Wenn dieses Argument nicht angegeben wird, ist der Parameter optional.

Im folgenden Beispiel wird der ComputerName-Parameter deklariert. Er verwendet das Mandatory -Argument, um den Parameter obligatorisch zu machen.

Param(
    [Parameter(Mandatory=$true)]
    [String[]]
    $ComputerName
)

Positionsargument

Das Position -Argument bestimmt, ob der Parametername erforderlich ist, wenn der Parameter in einem Befehl verwendet wird. Wenn eine Parameterdeklaration das Argument enthält, kann der Parametername weggelassen werden, und PowerShell identifiziert den unbenannten Parameterwert nach seiner Position oder Reihenfolge in der Liste der unbenannten Parameterwerte im Position Befehl.

Wenn das Argument nicht angegeben ist, muss der Parametername oder ein Parameternamenalias oder eine Abkürzung dem Parameterwert vorangehenden, wenn der Parameter in einem Befehl Position verwendet wird.

Standardmäßig sind alle Funktionsparameter positionell. PowerShell weist Parametern Positionsnummern in der Reihenfolge zu, in der die Parameter in der Funktion deklariert werden. Um dieses Feature zu deaktivieren, legen Sie den Wert des Arguments PositionalBinding des CmdletBinding-Attributs auf $False fest. Das Position Argument hat Vorrang vor dem Wert des Arguments des PositionalBinding CmdletBinding-Attributs. Weitere Informationen finden Sie PositionalBinding in about_Functions_CmdletBindingAttribute.

Der Wert des Arguments Position wird als ganze Zahl angegeben. Der Positionswert 0 stellt die erste Position im Befehl dar, der Positionswert 1 die zweite Position im Befehl und so weiter.

Wenn eine Funktion über keine Positionsparameter verfügt, weist PowerShell jedem Parameter Positionen basierend auf der Reihenfolge zu, in der die Parameter deklariert werden. Als bewährte Methode sollten Sie sich jedoch nicht auf diese Zuweisung verlassen. Wenn Parameter positionell sein sollen, verwenden Sie das Position -Argument.

Im folgenden Beispiel wird der ComputerName-Parameter deklariert. Es verwendet das Position -Argument mit dem Wert 0. Wenn aus -ComputerName dem Befehl weggelassen wird, muss der Wert daher der erste oder einzige unbenannte Parameterwert im Befehl sein.

Param(
    [Parameter(Position=0)]
    [String[]]
    $ComputerName
)

ParameterSetName-Argument

Das ParameterSetName -Argument gibt den Parametersatz an, zu dem ein Parameter gehört. Wenn kein Parametersatz angegeben wird, gehört der Parameter zu allen Parametersätzen, die von der Funktion definiert werden. Daher muss jeder Parametersatz mindestens einen Parameter aufweisen, der kein Member eines anderen Parametersatzes ist, um eindeutig zu sein.

Hinweis

Für ein Cmdlet oder eine Funktion gilt ein Grenzwert von 32 Parametersätzen.

Im folgenden Beispiel werden ein ComputerName-Parameter im Computer Parametersatz, ein UserName-Parameter im User Parametersatz und ein Summary-Parameter in beiden Parametersätzen deklariert.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false)]
    [Switch]
    $Summary
)

Sie können in jedem Argument nur einen ParameterSetName Wert und in jedem ParameterSetName Parameterattribut nur ein Argument angeben. Um anzugeben, dass ein Parameter in mehr als einem Parametersatz angezeigt wird, fügen Sie zusätzliche Parameterattribute hinzu.

Im folgenden Beispiel wird der Summary-Parameter explizit den Computer Parametersätzen und User hinzugefügt. Der Summary-Parameter ist im Parametersatz optional Computer und im User Parametersatz obligatorisch.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false, ParameterSetName="Computer")]
    [Parameter(Mandatory=$true, ParameterSetName="User")]
    [Switch]
    $Summary
)

Weitere Informationen zu Parametersätzen finden Sie unter Informationen zu Parametersätzen.

ValueFromPipeline-Argument

Das ValueFromPipeline Argument gibt an, dass der Parameter Eingaben aus einem Pipelineobjekt akzeptiert. Geben Sie dieses Argument an, wenn die Funktion das gesamte -Objekt akzeptiert, nicht nur eine -Eigenschaft des -Objekts.

Im folgenden Beispiel wird ein erforderlicher ComputerName-Parameter deklariert, der ein -Objekt akzeptiert, das von der Pipeline an die Funktion übergeben wird.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

ValueFromPipelineByPropertyName-Argument

Das ValueFromPipelineByPropertyName Argument gibt an, dass der Parameter Eingaben von einer Eigenschaft eines Pipelineobjekts akzeptiert. Die Objekteigenschaft muss denselben Namen oder Alias wie der Parameter haben.

Wenn die Funktion beispielsweise über einen ComputerName-Parameter verfügt und das übergebene Objekt über eine ComputerName-Eigenschaft verfügt, wird der Wert der ComputerName-Eigenschaft dem ComputerName-Parameter der Funktion zugewiesen.

Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der obligatorisch ist und Eingaben aus der ComputerName-Eigenschaft des Objekts akzeptiert, die über die Pipeline an die Funktion übergeben wird.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipelineByPropertyName=$true)]
    [String[]]
    $ComputerName
)

Hinweis

Ein Typparameter, der Pipelineeingaben ( ) oder ( ) akzeptiert, ermöglicht die Verwendung von Skriptblöcken mit verzögerter Bindung by Value by PropertyName für den Parameter.

Der Skriptblock für die verzögerungsbasierte Bindung wird automatisch während parameterBinding ausgeführt. Das Ergebnis wird an den -Parameter gebunden. Die Verzögerte Bindung funktioniert nicht für Parameter, die als Typ oder ScriptBlock definiert System.Object sind. Der Skriptblock wird übergeben, ohne aufgerufen zu werden.

Informationen zu Skriptblöcken mit verzögerter Bindung finden Sie hier about_Script_Blocks.md.

ValueFromRemainingArguments-Argument

Das -Argument gibt an, dass der -Parameter alle Werte des Parameters im Befehl akzeptiert, die anderen Parametern der ValueFromRemainingArguments Funktion nicht zugewiesen sind.

Im folgenden Beispiel werden ein obligatorischer Value-Parameter und ein Remaining-Parameter deklariert, der alle verbleibenden Parameterwerte akzeptiert, die an die Funktion übermittelt werden.

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory = $true, Position=0)]
         $Value,
         [string[]]
         [Parameter(Position=1, ValueFromRemainingArguments)]
         $Remaining)
     "Found $($Remaining.Count) elements"
     for ($i = 0; $i -lt $Remaining.Count; $i++)
     {
        "${i}: $($Remaining[$i])"
     }
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two

Hinweis

Vor PowerShell 6.2 wurde die ValueFromRemainingArguments-Auflistung als einzelne Entität unter Index 0 verbunden.

HelpMessage-Argument

Das HelpMessage -Argument gibt eine Zeichenfolge an, die eine kurze Beschreibung des Parameters oder seines Werts enthält. PowerShell zeigt diese Meldung in der Eingabeaufforderung an, die angezeigt wird, wenn ein obligatorischer Parameterwert in einem Befehl fehlt. Dieses Argument hat keine Auswirkungen auf optionale Parameter.

Im folgenden Beispiel werden ein obligatorischer ComputerName-Parameter und eine Hilfemeldung deklariert, in der der erwartete Parameterwert erläutert wird.

Wenn keine andere kommentarbasierte Hilfesyntax für die Funktion (z. B. ) vorhanden ist, .SYNOPSIS wird diese Meldung auch in der Ausgabe Get-Help angezeigt.

Param(
    [Parameter(Mandatory=$true,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [String[]]
    $ComputerName
)

Alias-Attribut

Das Alias-Attribut legt einen alternativen Namen für den Parameter fest. Es gibt keine Beschränkung für die Anzahl von Aliasen, die Sie einem Parameter zuweisen können.

Das folgende Beispiel zeigt eine Parameterdeklaration, die dem obligatorischen ComputerName-Parameter die CN- und MachineName-Aliase hinzufügt.

Param(
    [Parameter(Mandatory=$true)]
    [Alias("CN","MachineName")]
    [String[]]
    $ComputerName
)

SupportsWildcards-Attribut

Das SupportsWildcards-Attribut wird verwendet, um anzugeben, dass der Parameter Platzhalterwerte akzeptiert. Das folgende Beispiel zeigt eine Parameterdeklaration für einen obligatorischen Path-Parameter, der Platzhalterwerte unterstützt.

Param(
    [Parameter(Mandatory=$true)]
    [SupportsWildcards()]
    [String[]]
    $Path
)

Die Verwendung dieses Attributs aktiviert nicht automatisch die Platzhalterunterstützung. Der Cmdlet-Entwickler muss den Code implementieren, um die Platzhaltereingabe zu verarbeiten. Die unterstützten Platzhalter können je nach zugrunde liegender API oder PowerShell-Anbieter variieren. Weitere Informationen finden Sie unter about_Wildcards.

Parameter- und Variablenvalidierungsattribute

Validierungsattribute leiten PowerShell an, die Parameterwerte zu testen, die Benutzer übermitteln, wenn sie die erweiterte Funktion aufrufen. Wenn die Parameterwerte beim Test fehlschlagen, wird ein Fehler generiert, und die Funktion wird nicht aufgerufen. Die Parametervalidierung wird nur auf die bereitgestellte Eingabe angewendet, und andere Werte wie Standardwerte werden nicht überprüft.

Sie können auch die Validierungsattribute verwenden, um die Werte einzuschränken, die Benutzer für Variablen angeben können. Wenn Sie einen Typkonverter zusammen mit einem Validierungsattribut verwenden, muss der Typkonverter vor dem Attribut definiert werden.

[int32][AllowNull()] $number = 7

AllowNull-Validierungsattribut

Das AllowNull-Attribut lässt zu, dass der Wert eines obligatorischen Parameters $null ist. Im folgenden Beispiel wird ein ComputerInfo-Hashtabellenparameter deklariert, der einen NULL-Wert aufweisen kann.

Param(
    [Parameter(Mandatory=$true)]
    [AllowNull()]
    [hashtable]
    $ComputerInfo
)

Hinweis

Das AllowNull-Attribut funktioniert nicht, wenn der Typkonverter auf string festgelegt ist, da der Zeichenfolgentyp keinen NULL-Wert akzeptiert. Sie können das AllowEmptyString-Attribut für dieses Szenario verwenden.

AllowEmptyString-Validierungsattribut

Mit dem AllowEmptyString-Attribut kann der Wert eines obligatorischen Parameters eine leere Zeichenfolge () "" sein. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Zeichenfolgenwert haben kann.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyString()]
    [String]
    $ComputerName
)

AllowEmptyCollection-Validierungsattribut

Mit dem AllowEmptyCollection-Attribut kann der Wert eines obligatorischen Parameters eine leere Auflistung @() sein. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Auflistungswert haben kann.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyCollection()]
    [String[]]
    $ComputerName
)

ValidateCount-Validierungsattribut

Das ValidateCount-Attribut gibt die minimale und maximale Anzahl von Parameterwerten an, die ein Parameter akzeptiert. PowerShell generiert einen Fehler, wenn die Anzahl der Parameterwerte im Befehl, der die Funktion aufruft, außerhalb dieses Bereichs liegt.

Die folgende Parameterdeklaration erstellt einen ComputerName-Parameter, der ein bis fünf Parameterwerte akzeptiert.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
)

ValidateLength-Validierungsattribut

Das ValidateLength-Attribut gibt die minimale und maximale Anzahl von Zeichen in einem Parameter- oder Variablenwert an. PowerShell generiert einen Fehler, wenn die Länge eines für einen Parameter oder eine Variable angegebenen Werts außerhalb des Bereichs liegt.

Im folgenden Beispiel muss jeder Computername ein bis zehn Zeichen enthalten.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateLength(1,10)]
    [String[]]
    $ComputerName
)

Im folgenden Beispiel muss der Wert der Variablen mindestens ein Zeichen und maximal $number zehn Zeichen lang sein.

[Int32][ValidateLength(1,10)]$number = '01'

Hinweis

In diesem Beispiel wird der Wert 01 von in einfache Anführungszeichen umschlossen. Das ValidateLength-Attribut akzeptiert keine Zahl, ohne in Anführungszeichen umschlossen zu sein.

ValidatePattern-Validierungsattribut

Das ValidatePattern-Attribut gibt einen regulären Ausdruck an, der mit dem Parameter- oder Variablenwert verglichen wird. PowerShell generiert einen Fehler, wenn der Wert nicht mit dem Muster für reguläre Ausdrücke übereinstimmt.

Im folgenden Beispiel muss der Parameterwert eine vierstellige Zahl enthalten, und jede Ziffer muss eine Zahl 0 bis 9 sein.

Param(
    [Parameter(Mandatory=$true)]
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [String[]]
    $ComputerName
)

Im folgenden Beispiel muss der Wert der Variablen $number genau eine vierstellige Zahl sein, und jede Ziffer muss eine Zahl 0 bis 9 sein.

[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111

ValidateRange-Validierungsattribut

Das ValidateRange-Attribut gibt einen numerischen Bereich oder einen ValidateRangeKind-Enumerationswert für jeden Parameter- oder Variablenwert an. PowerShell generiert einen Fehler, wenn ein Wert außerhalb dieses Bereichs liegt.

Die ValidateRangeKind-Enumeration ermöglicht die folgenden Werte:

  • Positiv: Eine Zahl größer als 0 (null).
  • Negativ: Eine Zahl kleiner als 0 (null).
  • NonPositive: Eine Zahl kleiner oder gleich 0 (null).
  • NonNegative: Eine Zahl, die größer oder gleich 0 (null) ist.

Im folgenden Beispiel muss der Wert des Attempts-Parameters zwischen null und zehn sein.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateRange(0,10)]
    [Int]
    $Attempts
)

Im folgenden Beispiel muss der Wert der Variablen $number zwischen null und zehn sein.

[Int32][ValidateRange(0,10)]$number = 5

Im folgenden Beispiel muss der Wert der Variablen $number größer als 0 (null) sein.

[Int32][ValidateRange("Positive")]$number = 1

ValidateScript-Validierungsattribut

Das ValidateScript-Attribut gibt ein Skript an, das zum Überprüfen eines Parameters oder Variablenwerts verwendet wird. PowerShell übergibt den Wert an das Skript und generiert einen Fehler, wenn das Skript zurückgibt $false oder wenn das Skript eine Ausnahme auslöst.

Wenn Sie das ValidateScript-Attribut verwenden, wird der überprüfte Wert der $_ Variablen zugeordnet. Sie können die $_ Variable verwenden, um auf den Wert im Skript zu verweisen.

Im folgenden Beispiel muss der Wert des EventDate-Parameters größer oder gleich dem aktuellen Datum sein.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]
    $EventDate
)

Im folgenden Beispiel muss der Wert der Variablen größer oder gleich dem aktuellen Datum und der $date aktuellen Uhrzeit sein.

[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)

Hinweis

Wenn Sie ValidateScript verwenden, können Sie keinen $null Wert an den Parameter übergeben. Wenn Sie einen NULL-Wert übergeben, kann ValidateScript das Argument nicht überprüfen.

ValidateSet-Attribut

Das ValidateSet-Attribut gibt einen Satz gültiger Werte für einen Parameter oder eine Variable an und aktiviert die Vervollständigung mit der Tabulatoren. PowerShell generiert einen Fehler, wenn ein Parameter- oder Variablenwert nicht mit einem Wert in der Menge übereinstimmen soll. Im folgenden Beispiel kann der Wert des Detail-Parameters nur Niedrig, Durchschnitt oder Hoch sein.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet("Low", "Average", "High")]
    [String[]]
    $Detail
)

Im folgenden Beispiel muss der Wert der Variablen $flavor entweder Chocolate, Chocolatey oder Chocolate sein.

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[String]$flavor = "Strawberry"

Die Überprüfung erfolgt immer dann, wenn diese Variable auch innerhalb des Skripts zugewiesen wird. Beispielsweise führt folgendes zur Laufzeit zu einem Fehler:

Param(
    [ValidateSet("hello", "world")]
    [String]$Message
)

$Message = "bye"

Dynamische validateSet-Werte

Sie können eine Klasse verwenden, um die Werte für ValidateSet zur Laufzeit dynamisch zu generieren. Im folgenden Beispiel werden die gültigen Werte für die Variable über eine Klasse namens SoundNames generiert, die drei Dateisystempfade auf verfügbare $Sound Sounddateien überprüft:

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [String[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [String[]] $SoundNames
    }
}

Die [SoundNames] -Klasse wird dann wie folgt als dynamischer ValidateSet-Wert implementiert:

Param(
    [ValidateSet([SoundNames])]
    [String]$Sound
)

Hinweis

Die IValidateSetValuesGenerator -Klasse wurde in PowerShell 6.0 eingeführt.

ValidateNotNull-Validierungsattribut

Das ValidateNotNull-Attribut gibt an, dass der Parameterwert nicht sein $null darf. PowerShell generiert einen Fehler, wenn der Parameterwert $null ist.

Das ValidateNotNull-Attribut ist für die Verwendung konzipiert, wenn der Parameter optional ist und der Typ nicht definiert ist oder über einen Typkonverter verfügt, der einen NULL-Wert wie das Objekt nicht implizit konvertieren kann. Wenn Sie einen Typ angeben, der implizit einen NULL-Wert wie eine Zeichenfolge konvertiert, wird der NULL-Wert auch bei Verwendung des ValidateNotNull-Attributs in eine leere Zeichenfolge konvertiert. Verwenden Sie für dieses Szenario ValidateNotNullOrEmpty.

Im folgenden Beispiel kann der Wert des ID-Parameters nicht $null sein.

Param(
    [Parameter(Mandatory=$false)]
    [ValidateNotNull()]
    $ID
)

ValidateNotNullOrEmpty-Validierungsattribut

Das ValidateNotNullOrEmpty-Attribut gibt an, dass der Parameterwert nicht sein $null darf und keine leere Zeichenfolge ( ) sein "" darf. PowerShell generiert einen Fehler, wenn der Parameter in einem Funktionsaufruf verwendet wird, aber sein Wert $null , eine leere Zeichenfolge ( ) oder ein "" leeres Array @() ist.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [String[]]
    $UserName
)

ValidateDrive-Validierungsattribut

Das ValidateDrive-Attribut gibt an, dass der Parameterwert den Pfad darstellen muss, der nur auf zulässige Laufwerke verweist. PowerShell generiert einen Fehler, wenn sich der Parameterwert auf andere Laufwerke als die zulässigen bezieht. Das Vorhandensein des Pfads mit Ausnahme des Laufwerks selbst wird nicht überprüft.

Wenn Sie einen relativen Pfad verwenden, muss sich das aktuelle Laufwerk in der Liste der zulässigen Laufwerke befinden.

Param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [String]$Path
)

ValidateUserDrive-Validierungsattribut

Das ValidateUserDrive-Attribut gibt an, dass der Parameterwert den Pfad darstellen muss, der auf User laufwerk verweist. PowerShell generiert einen Fehler, wenn der Pfad auf ein anderes Laufwerk verweist. Das Validierungsattribut testet nur, ob der Laufwerksteil des Pfads vorhanden ist.

Wenn Sie einen relativen Pfad verwenden, muss das aktuelle Laufwerk User sein.

function Test-UserDrivePath{
    [OutputType([bool])]
    Param(
      [Parameter(Mandatory=, Position=0)][ValidateUserDrive()][String]$Path
      )
    $True
}

Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

Sie können User das Laufwerk in JEA-Sitzungskonfigurationen (Just Enough Administration) definieren. In diesem Beispiel erstellen wir das Laufwerk Benutzer: .

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True

ValidateTrustedData-Validierungsattribut

Dieses Attribut wurde in PowerShell 6.1.1 hinzugefügt.

Zu diesem Zeitpunkt wird das -Attribut intern von PowerShell selbst verwendet und ist nicht für die externe Verwendung vorgesehen.

Dynamische Parameter

Dynamische Parameter sind Parameter eines Cmdlets, einer Funktion oder eines Skripts, die nur unter bestimmten Bedingungen verfügbar sind.

Beispielsweise verfügen mehrere Anbieter-Cmdlets über Parameter, die nur verfügbar sind, wenn das Cmdlet im Anbieterlaufwerk oder in einem bestimmten Pfad des Anbieterlaufwerks verwendet wird. Beispielsweise ist der Encoding-Parameter auf den Cmdlets , und nur verfügbar, wenn er Add-Content in einem Get-Content Set-Content Dateisystemlaufwerk verwendet wird.

Sie können auch einen Parameter erstellen, der nur angezeigt wird, wenn ein anderer Parameter im Funktionsbefehl verwendet wird oder wenn ein anderer Parameter über einen bestimmten Wert verfügt.

Dynamische Parameter können nützlich sein, verwenden sie jedoch nur bei Bedarf, da sie für Benutzer schwierig zu finden sein können. Um einen dynamischen Parameter zu finden, muss sich der Benutzer im Anbieterpfad befinden, den ArgumentList-Parameter des Cmdlets verwenden oder den Get-Command Path-Parameter von Get-Help verwenden.

Verwenden Sie das Schlüsselwort , um einen dynamischen Parameter für eine Funktion oder ein Skript DynamicParam zu erstellen.

Die Syntax ist wie folgt:

DynamicParam {<statement-list>}

Verwenden Sie in der Anweisungsliste eine -Anweisung, um die Bedingungen anzugeben, unter denen If der Parameter in der Funktion verfügbar ist.

Verwenden Sie New-Object das Cmdlet , um ein System.Management.Automation.RuntimeDefinedParameter-Objekt zu erstellen, das den Parameter repräsentiert und seinen Namen angibt.

Sie können einen Befehl verwenden, um ein New-Object System.Management.Automation.ParameterAttribute-Objekt zu erstellen, um Attribute des Parameters wie Mandatory, Position oder ValueFromPipeline oder dessen Parametersatz zu darstellen.

Das folgende Beispiel zeigt eine Beispielfunktion mit Standardparametern namens Name und Pfad und einem optionalen dynamischen Parameter mit dem Namen DP1. Der DP1-Parameter befindet sich im PSet1 Parametersatz und hat den Typ Int32 . Der DP1-Parameter ist in der Get-Sample Funktion nur verfügbar, wenn der Wert des Path-Parameters mit beginnt und HKLM: angibt, dass er im Registrierungslaufwerk verwendet HKEY_LOCAL_MACHINE wird.

function Get-Sample {
  [CmdletBinding()]
  Param([String]$Name, [String]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $attributes.Mandatory = $false
      $attributeCollection = New-Object `
        -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)

      $dynParam1 = New-Object -Type `
        System.Management.Automation.RuntimeDefinedParameter("DP1", [Int32],
          $attributeCollection)

      $paramDictionary = New-Object `
        -Type System.Management.Automation.RuntimeDefinedParameterDictionary
      $paramDictionary.Add("DP1", $dynParam1)
      return $paramDictionary
    }
  }
}

Weitere Informationen finden Sie unter RuntimeDefinedParameter.

Switch-Parameter

Switchparameter sind Parameter ohne Parameterwert. Sie sind nur wirksam, wenn sie verwendet werden und nur einen Effekt haben.

Beispielsweise ist der NoProfile-Parameter von powershell.exe ein switch-Parameter.

Um einen Switchparameter in einer Funktion zu erstellen, geben Sie den Switch Typ in der Parameterdefinition an.

Beispiel:

Param([Switch]<ParameterName>)

Alternativ können Sie eine andere Methode verwenden:

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

Switchparameter sind einfach zu verwenden und werden gegenüber booleschen Parametern bevorzugt, die eine schwierigere Syntax aufweisen.

Um beispielsweise einen switch-Parameter zu verwenden, gibt der Benutzer den Parameter in den Befehl ein.

-IncludeAll

Um einen booleschen Parameter zu verwenden, gibt der Benutzer den Parameter und einen booleschen Wert ein.

-IncludeAll:$true

Wählen Sie beim Erstellen von Switchparametern den Parameternamen sorgfältig aus. Stellen Sie sicher, dass der Parametername dem Benutzer die Auswirkung des Parameters mitteilt. Vermeiden Sie mehrdeutige Begriffe, z. B. Filter oder Maximum, die implizieren können, dass ein Wert erforderlich ist.

ArgumentCompleter-Attribut

Mit dem ArgumentCompleter-Attribut können Sie einem bestimmten Parameter Tabstoppvervollständigungswerte hinzufügen. Für jeden Parameter, der die Tabstoppvervollständigung erfordert, muss ein ArgumentCompleter-Attribut definiert werden. Ähnlich wie bei DynamicParameters werden die verfügbaren Werte zur Laufzeit berechnet, wenn der Benutzer die TAB-TASTE nach dem Parameternamen drückt.

Um ein ArgumentCompleter-Attribut hinzuzufügen, müssen Sie einen Skriptblock definieren, der die Werte bestimmt. Der Skriptblock muss die folgenden Parameter in der unten angegebenen Reihenfolge annehmen. Die Namen des Parameters spielen keine Rolle, da die Werte positionell bereitgestellt werden.

Die Syntax ist wie folgt:

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ( $commandName,
                $parameterName,
                $wordToComplete,
                $commandAst,
                $fakeBoundParameters )
        # Perform calculation of tab completed values here.
    })]
)

ArgumentCompleter-Skriptblock

Die Skriptblockparameter werden auf die folgenden Werte festgelegt:

  • $commandName (Position 0): Dieser Parameter wird auf den Namen des Befehls festgelegt, für den der Skriptblock die Vervollständigung der Tabulatoren angibt.
  • $parameterName (Position 1): Dieser Parameter wird auf den Parameter festgelegt, dessen Wert die Vervollständigung der Tabulatoren erfordert.
  • $wordToComplete (Position 2): Dieser Parameter wird auf den Wert festgelegt, den der Benutzer angegeben hat, bevor er die TAB-TASTE gedrückt hat. Ihr Skriptblock sollte diesen Wert verwenden, um Werte für die Vervollständigung der Tabulatoren zu bestimmen.
  • $commandAst (Position 3): Dieser Parameter wird auf die abstrakte Syntaxstruktur (Abstract Syntax Tree, AST) für die aktuelle Eingabezeile festgelegt. Weitere Informationen finden Sie unter Ast-Klasse.
  • $fakeBoundParameters (Position 4): Dieser Parameter wird auf eine Hashtabelle festgelegt, die den für das Cmdlet enthält, bevor der Benutzer $PSBoundParameters die TAB-TASTE gedrückt hat. Weitere Informationen finden Sie unter about_Automatic_Variables.

Der ArgumentCompleter-Skriptblock muss die Registrierung der Werte mithilfe der Pipeline, z. B. ForEach-Object , oder einer anderen geeigneten Where-Object Methode, entsperren. Das Zurückgeben eines Array von Werten bewirkt, dass PowerShell das gesamte Array als Einen-Tab-Vervollständigungswert behandelt.

Im folgenden Beispiel wird dem Value-Parameter die Vervollständigung mit der Tabulatoren hinzufügt. Wenn nur der Value-Parameter angegeben wird, werden alle möglichen Werte oder Argumente für Value angezeigt. Wenn der Type-Parameter angegeben wird, zeigt der Value-Parameter nur die möglichen Werte für diesen Typ an.

Darüber hinaus stellt der Operator sicher, dass nur Apple zurückgegeben wird, wenn der Benutzer den folgenden Befehl eintipp und die -like TAB-Vervollständigung verwendet.

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory=$true)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

Weitere Informationen

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute