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 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
'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 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
)
Switch-Parameter
Switchparameter sind Parameter, die keinen Parameterwert annehmen. Stattdessen übermitteln sie einen booleschen wert true-or-false durch ihre Anwesenheit oder Abwesenheit, sodass ein Switch-Parameter, wenn er vorhanden ist, über einen true-Wert verfügt und wenn er nicht vorhanden ist, einen false-Wert hat.
Der Recurse-Parameter von Get-ChildItem ist beispielsweise ein Switchparameter.
Um einen Switchparameter in einer Funktion zu erstellen, geben Sie den switch Typ in der Parameterdefinition an.
Ihre Funktion kann beispielsweise eine Option zum Ausgeben von Daten als Bytearray haben:
Param([switch]$AsByteArray)
Switch-Parameter sind einfach zu verwenden und werden vor booleschen Parametern bevorzugt, die eine weniger natürliche Syntax für PowerShell 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.
Überlegungen zum Switchparameterentwurf
Switchparameter sollten keine Standardwerte erhalten. Sie sollten immer auf false festgelegt werden.
Schalterparameter werden standardmäßig von Positionsparametern ausgeschlossen. Auch wenn andere Parameter implizit positional sind, sind Switchparameter nicht vorhanden. Sie können dies im Parameter-Attribut überschreiben, aber dies führt zu Verwirrung bei den Benutzern.
Schalterparameter sollten so konzipiert sein, dass sie durch das Festlegen von Befehlen von seiner Standardfunktionalität in einen weniger häufigen oder komplizierteren Modus verschoben werden. Das einfachste Verhalten eines Befehls sollte das Standardverhalten sein, das keine Verwendung von Switchparametern erfordert.
Switch-Parameter sollten nicht obligatorisch sein. Der einzige Fall, in dem es erforderlich ist, einen Switch-Parameter obligatorisch zu machen, ist, wenn er erforderlich ist, um einen Parametersatz zu unterscheiden.
Das explizite Festlegen eines Schalters aus einem booleschen Wert kann mit
-MySwitch:$boolValueund beim Splatting mit$params = @{ MySwitch = $boolValue }erfolgen.Switch-Parameter sind vom Typ
SwitchParameter, der implizit in Boolean konvertiert wird. Die Parametervariable kann direkt in einem bedingten Ausdruck verwendet werden. Beispiel:if ($MySwitch) { ... }Es ist nicht erforderlich, zu schreiben
if ($MySwitch.IsPresent) { ... }
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.
Das folgende Beispiel zeigt eine Funktion mit den Standardparametern Name und Pfad sowie einen optionalen dynamischen Parameter mit dem Namen KeyCount. Der KeyCount-Parameter befindet sich im ByRegistryPath Parametersatz und weist den Typ von auf Int32. Der KeyCount-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:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [Int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
Weitere Informationen finden Sie in der Dokumentation zum RuntimeDefinedParameter-Typ .
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)]
[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 steht für die erste Position im Befehl, der Positionswert 1 für 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. Das Argument wird mit dem Position Wert 0 verwendet. -ComputerName Wenn im Befehl nicht angegeben 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, um eindeutig zu sein, 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,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter()]
[switch]
$Summary
)
Sie können nur einen ParameterSetName Wert in jedem Argument und nur ein ParameterSetName Argument in jedem Parameter-Attribut angeben. Um anzugeben, dass ein Parameter in mehr als einem Parametersatz angezeigt wird, fügen Sie zusätzliche Parameterattribute hinzu.
Im folgenden Beispiel wird den Parametersätzen und User explizit der Computer Summary-Parameter hinzugefügt. Der Summary-Parameter ist im Computer Parametersatz optional und im User Parametersatz obligatorisch.
Param(
[Parameter(Mandatory,
ParameterSetName="Computer")]
[string[]]
$ComputerName,
[Parameter(Mandatory,
ParameterSetName="User")]
[string[]]
$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, 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 von der Pipeline an die Funktion übergeben wird.
Param(
[Parameter(Mandatory,
ValueFromPipeline)]
[string[]]
$ComputerName
)
ValueFromPipelineByPropertyName-Argument
Das ValueFromPipelineByPropertyName Argument gibt an, dass der Parameter Eingaben von einer Eigenschaft eines Pipelineobjekts akzeptiert. Die Objekteigenschaft muss den gleichen 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 obligatorischer ComputerName-Parameter deklariert, der Eingaben von der ComputerName-Eigenschaft des Objekts akzeptiert, die über die Pipeline an die Funktion übergeben wird.
Param(
[Parameter(Mandatory,
ValueFromPipelineByPropertyName)]
[string[]]
$ComputerName
)
Hinweis
Ein typisierter Parameter, der pipelineeingaben (by Value) oder (by PropertyName) akzeptiert, ermöglicht die Verwendung von Verzögerungsbindungsskriptblöcken für den Parameter.
Der Delay Bind-Skriptblock wird während der ParameterBinding 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, 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,
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)]
[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)]
[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.
Attribute für die Vervollständigung von Argumenten
ArgumentCompletions-Attribut
Mit dem ArgumentCompletions-Attribut können Sie einem bestimmten Parameter Tabstopp-Vervollständigungswerte hinzufügen. Ein ArgumentCompletions-Attribut muss für jeden Parameter definiert werden, der die Tabulatorvervollständigung erfordert. Das ArgumentCompletions-Attribut ähnelt ValidateSet. Beide Attribute verwenden eine Liste von Werten, die angezeigt werden sollen, wenn der Benutzer die TAB-TASTE nach dem Parameternamen drückt. Im Gegensatz zu ValidateSet werden die Werte jedoch nicht überprüft.
Dieses Attribut wurde in PowerShell 6.0 eingeführt.
Weitere Informationen finden Sie unter about_Functions_Argument_Completion.
ArgumentCompleter-Attribut
Mit dem ArgumentCompleter-Attribut können Sie einem bestimmten Parameter Tabstopp-Vervollständigungswerte hinzufügen. Ein ArgumentCompleter-Attribut muss für jeden Parameter definiert werden, der eine Tabstopp-Vervollständigung erfordert. Ähnlich wie bei DynamicParameters werden die verfügbaren Werte zur Laufzeit berechnet, wenn der Benutzer die TAB-TASTE nach dem Parameternamen drückt.
Weitere Informationen finden Sie unter about_Functions_Argument_Completion.
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
Hinweis
Validierungsattribute können auf jede Variable angewendet werden, nicht nur auf Parameter. Sie können die Validierung für jede Variable innerhalb eines Skripts definieren.
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)]
[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)]
[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)]
[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)]
[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)]
[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)]
[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)]
[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)]
[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)]
[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"
In diesem Beispiel wird zur Laufzeit der folgende Fehler zurückgegeben:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Mit wird ValidateSet auch die Registerkartenerweiterung von Werten für diesen Parameter aktiviert. Weitere Informationen finden Sie unter about_Tab_Expansion.
Dynamische ValidateSet-Werte mithilfe von Klassen
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
)
Hinweis
Die IValidateSetValuesGenerator -Klasse wurde in PowerShell 6.0 eingeführt.
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()]
[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)]
[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. Die Existenz 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 das User Laufwerk verweist. 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 den 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 . In diesem Beispiel erstellen wir das Laufwerk User:.
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
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
ValidateTrustedData-Validierungsattribut
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.