Informationen zu erweiterten Parametern für Funktionen

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 einzuschränken, 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 automatisch zu allen Cmdlets und erweiterten Funktionen hinzufügt. Weitere Informationen zu den allgemeinen PowerShell-Parametern finden Sie unter about_CommonParameters.

Ab PowerShell 3.0 können Sie splatting mit @Args verwenden, um die Parameter in einem Befehl darzustellen. 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 kulturinvariante Analysen von Parameterwerten durch.

Im Gegensatz dazu wird eine kulturabhängige Konvertierung während der Parameterbindung für kompilierte Cmdlets ausgeführt.

In diesem Beispiel erstellen wir ein Cmdlet und eine Skriptfunktion, die einen [datetime] Parameter annehmen. Die aktuelle Kultur wird geändert, um deutsche Einstellungen zu verwenden. Ein deutsch formatiertes Datum 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 kultursensitive 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 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 was not recognized as a valid
 DateTime."
At line:13 char:15
+ Get-Date_Func $dateStr
+               ~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func

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 mit den folgenden Merkmalen:

• Dies ist obligatorisch (erforderlich).
• Sie nimmt Eingaben aus der Pipeline an.
• Als Eingabe wird ein Array von Zeichenfolgen verwendet.

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 Begrenzung 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 als erweiterte Funktion erkannt zu werden, muss eine Funktion entweder über das CmdletBinding-Attribut oder das Parameter-Attribut oder beides verfügen.

Das Parameter-Attribut enthält 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 dazwischenliegendes 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 nach Name 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 weiterhin die Klammern erforderlich, die dem Attributnamen folgen.

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. Es verwendet das Mandatory Argument, um den Parameter obligatorisch zu machen.

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

Argument "Position"

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

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

Standardmäßig sind alle Funktionsparameter positional. 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 PositionalBinding Arguments des CmdletBinding-Attributs auf fest $False. Das Position Argument hat Vorrang vor dem Wert des PositionalBinding Arguments des CmdletBinding-Attributs . Weitere Informationen finden Sie PositionalBinding unter about_Functions_CmdletBindingAttribute.

Der Wert des Position Arguments wird als ganze Zahl angegeben. Ein Positionswert von 0 stellt die erste Position im Befehl dar, ein Positionswert von 1 die zweite Position im Befehl usw.

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

Im folgenden Beispiel wird der ComputerName-Parameter deklariert. Es verwendet das Position Argument mit dem Wert 0. -ComputerName Wenn der Befehl nicht angegeben wird, muss der Wert daher der erste oder nur 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 ist, gehört der Parameter zu allen von der Funktion definierten Parametersätzen. Um eindeutig zu sein, muss jeder Parametersatz mindestens einen Parameter enthalten, der kein Member eines anderen Parametersatzes ist.

Hinweis

Für ein Cmdlet oder eine Funktion gibt es einen 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 nur einen ParameterSetName Wert in jedem Argument und nur ein ParameterSetName Argument in jedem Parameter-Attribut angeben. Fügen Sie zusätzliche Parameterattribute hinzu, um anzugeben, dass ein Parameter in mehr als einem Parametersatz angezeigt wird.

Im folgenden Beispiel wird dem Parametersatz und User explizit der ComputerSummary-Parametersatz hinzugefügt. Der Summary-Parameter ist im Computer Parametersatz optional 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 von 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 ComputerName-Parameter deklariert, der obligatorisch ist und ein Objekt akzeptiert, das aus 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 aufweisen.

Wenn die Funktion beispielsweise über einen ComputerName-Parameter und das piped -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 typisierter Parameter, der die Pipelineeingabe (by Value) oder (by PropertyName) akzeptiert, ermöglicht die Verwendung von Verzögerungsbindungsskriptblöcken für den Parameter.

Der Verzögerungsbindungsskriptblock wird während des ParameterBindings automatisch ausgeführt. Das Ergebnis ist an den Parameter gebunden. Die Verzögerungsbindung funktioniert nicht für Parameter, die als Typ ScriptBlock oder System.Objectdefiniert sind. Der Skriptblock wird übergeben, ohne aufgerufen zu werden.

Informationen zu Verzögerungsbindungsskriptblöcken finden Sie hier about_Script_Blocks.md.

ValueFromRemainingArguments-Argument

Das ValueFromRemainingArguments Argument gibt an, dass der Parameter alle Werte des Parameters im Befehl akzeptiert, die anderen Parametern der 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 verknüpft.

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 vorhanden ist (z. B .SYNOPSIS. ), wird diese Meldung auch in der Get-Help Ausgabe angezeigt.

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

Alias-Attribut

Das Alias-Attribut erstellt einen alternativen Namen für den Parameter. 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 Aliase CN und MachineName hinzufügt.

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

SupportsWildcards-Attribut

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

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

Die Verwendung dieses Attributs aktiviert nicht automatisch die Unterstützung von Wildcards. Der Cmdletentwickler muss den Code implementieren, um die Wildcardeingabe 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 weisen PowerShell an, die Parameterwerte zu testen, die Benutzer beim Aufrufen der erweiterten Funktion übermitteln. Wenn die Parameterwerte beim Test fehlschlagen, wird ein Fehler generiert, und die Funktion wird nicht aufgerufen. Die Parametervalidierung wird nur auf die angegebene Eingabe angewendet, und alle anderen 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 ist $null. Im folgenden Beispiel wird ein ComputerInfo-Parameter mit Hashtabelle 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 für dieses Szenario das Attribut AllowEmptyString verwenden.

AllowEmptyString-Validierungsattribut

Das AllowEmptyString-Attribut lässt zu, dass der Wert eines obligatorischen Parameters eine leere Zeichenfolge ("") ist. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Zeichenfolgenwert aufweisen kann.

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

AllowEmptyCollection-Validierungsattribut

Das AllowEmptyCollection-Attribut lässt zu, dass der Wert eines obligatorischen Parameters eine leere Auflistung @()ist. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Auflistungswert aufweisen 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 Werts, der für einen Parameter oder eine Variable angegeben ist, 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 $number mindestens ein Zeichen und maximal zehn Zeichen lang sein.

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

Hinweis

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

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 neun 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 neun 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, die größer als 0 (null) ist.
• Negativ : Eine Zahl, die kleiner als 0 (null) ist.
• Nichtpositiv : Eine Zahl, die kleiner oder gleich 0 ist.
• NichtNegativ : Eine Zahl, die größer oder gleich 0 ist.

Im folgenden Beispiel muss der Wert des Parameters "Attempts " zwischen 0 und zehn sein.

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

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

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

Im folgenden Beispiel muss der Wert der Variablen $number größer als 0 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 leitet den Wert an das Skript weiter 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 Wert, der überprüft wird, 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 $date größer oder gleich dem aktuellen Datum und der 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 ermöglicht die Vervollständigung der Registerkarte. PowerShell generiert einen Fehler, wenn ein Parameter- oder Variablenwert nicht mit einem Wert in der Gruppe übereinstimmt. Im folgenden Beispiel kann der Wert des Detail-Parameters nur Niedrig, Mittelwert oder Hoch sein.

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

Im folgenden Beispiel muss der Wert der Variablen $flavor entweder Chocolate, Strawberry oder Vanilla 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 $Sound über eine Klasse namens SoundNames generiert, die drei Dateisystempfade auf verfügbare 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
)

ValidateNotNull-Validierungsattribut

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

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 ein 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 sein $null.

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

ValidateNotNullOrEmpty-Validierungsattribut

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

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

ValidateDrive-Validierungsattribut

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

Wenn Sie relativen Pfad verwenden, muss sich das aktuelle Laufwerk in der Liste zulässiger 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 das Laufwerk verweist User . PowerShell generiert einen Fehler, wenn der Pfad auf ein anderes Laufwerk verweist. Das Validierungsattribut testet nur, dass der Laufwerkteil des Pfads vorhanden ist.

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

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 Laufwerk in JEA-Sitzungskonfigurationen (Just Enough Administration) definieren User . Für dieses 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

Validierungsattribut ValidateTrustedData

Dieses Attribut wurde in PowerShell 6.1.1 hinzugefügt.

Derzeit 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. Der Codierungsparameter ist beispielsweise nur für die Add-ContentCmdlets , Get-Contentund Set-Content verfügbar, wenn er in einem 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 einen bestimmten Wert aufweist.

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

Um einen dynamischen Parameter für eine Funktion oder ein Skript zu erstellen, verwenden Sie den DynamicParam Schlüsselwort (keyword).

Die Syntax lautet wie folgt:

DynamicParam {<statement-list>}

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

Verwenden Sie das New-Object Cmdlet, um ein System.Management.Automation.RuntimeDefinedParameter-Objekt zu erstellen, um den Parameter darzustellen und seinen Namen anzugeben.

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

Das folgende Beispiel zeigt eine Beispielfunktion mit Standardparametern namens Name und Pfad sowie einen optionalen dynamischen Parameter namens DP1. Der DP1-Parameter befindet sich im PSet1 Parametersatz und weist den Typ auf Int32. Der DP1-Parameter ist nur in der Get-Sample Funktion verfügbar, wenn der Wert des Path-Parameters mit HKLM:beginnt, was angibt, dass er im HKEY_LOCAL_MACHINE Registrierungslaufwerk verwendet 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.

Der NoProfile-Parameter von powershell.exe ist beispielsweise ein Switchparameter.

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

Switch-Parameter sind einfach zu verwenden und werden vor booleschen Parametern bevorzugt, die eine schwierigere Syntax aufweisen.

Um beispielsweise einen Switch-Parameter zu verwenden, gibt der Benutzer den Parameter im 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 Auswirkungen des Parameters übermittelt. Vermeiden Sie mehrdeutige Begriffe wie Filter oder Maximum , die implizieren, 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 eine Registerkartenvervollständigung erfordert, muss ein ArgumentCompleter-Attribut definiert werden. Ähnlich wie Bei DynamicParameters werden die verfügbaren Werte zur Laufzeit berechnet, wenn der Benutzer tab 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 verwenden. Die Namen des Parameters spielen keine Rolle, da die Werte positionell bereitgestellt werden.

Die Syntax lautet wie folgt:

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

ArgumentCompleter-Skriptblock

Die Skriptblockparameter sind auf die folgenden Werte festgelegt:

• $commandName (Position 0): Dieser Parameter wird auf den Namen des Befehls festgelegt, für den der Skriptblock die Tabulatorvervollständigung bereitstellt.
• $parameterName (Position 1): Dieser Parameter wird auf den Parameter festgelegt, dessen Wert die Tabulatorvervollständigung erfordert.
• $wordToComplete (Position 2): Dieser Parameter ist auf den Wert festgelegt, den der Benutzer angegeben hat, bevor er die Tabulatortaste gedrückt hat. Ihr Skriptblock sollte diesen Wert verwenden, um Tabstopp-Vervollständigungswerte zu bestimmen.
• $commandAst (Position 3): Dieser Parameter ist auf die Abstrakte Syntaxstruktur (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 $PSBoundParameters für das Cmdlet enthält, bevor der Benutzer die Tabulatortaste gedrückt hat. Weitere Informationen finden Sie unter about_Automatic_Variables.

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

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

Darüber hinaus stellt der -like Operator sicher, dass nur Apple zurückgegeben wird, wenn der Benutzer den folgenden Befehl eingibt und die Tabstopp-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