Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Redaktionelle Notiz
Wichtig
Die Windows PowerShell Language Specification 3.0 wurde im Dezember 2012 veröffentlicht und basiert auf Windows PowerShell 3.0. Diese Spezifikation spiegelt nicht den aktuellen Status von PowerShell wider. Es ist nicht geplant, diese Dokumentation zu aktualisieren, um den aktuellen Zustand widerzuspiegeln. Diese Dokumentation wird hier zur historischen Referenz vorgestellt.
Das Spezifikationsdokument steht als Microsoft Word-Dokument im Microsoft Download Center unter: https://www.microsoft.com/download/details.aspx?id=36389 zur Verfügung. Dieses Word-Dokument wurde hier auf Microsoft Learn für die Präsentation umgewandelt. Während der Konvertierung wurden einige redaktionelle Änderungen vorgenommen, um die Formatierung für die Docs-Plattform zu berücksichtigen. Einige Tippfehler und kleinere Fehler wurden korrigiert.
Ein Attributobjekt ordnet vordefinierte Systeminformationen einem Zielelement zu, bei dem es sich um einen Parameterblock oder einen Parameter handeln kann (§8.10). Jedes Attributobjekt verfügt über einen Attributtyp.
Von einem Attribut bereitgestellte Informationen werden auch als Metadaten bezeichnet. Metadaten können vom Befehl oder der Ausführungsumgebung untersucht werden, um zu steuern, wie die Befehle Daten verarbeiten oder bevor sie von externen Tools ausgeführt werden, um zu steuern, wie der Befehl selbst verarbeitet oder verwaltet wird.
Mehrere Attribute können auf dasselbe Zielelement angewendet werden.
12.1 Attributspezifikation
Tipp
Die ~opt~ Notation in den Syntaxdefinitionen gibt an, dass die lexikalische Entität in der Syntax optional ist.
attribute-list:
attribute
attribute-list new-lines~opt~ attribute
attribute:
[ new-lines~opt~ attribute-name ( attribute-arguments new-lines~opt~ ) new-lines~opt~ ]
type-literal
attribute-name:
type-spec
attribute-arguments:
attribute-argument
attribute-argument new-lines~opt~ ,
attribute-arguments
attribute-argument:
new-lines~opt~ expression
new-lines~opt~ simple-name
new-lines~opt~ simple-name = new-lines~opt~ expression
Ein Attribut besteht aus einem Attributnamen (attribute-name) und einer optionalen Liste von positionellen und benannten Argumenten.
Die Positionsargumente (falls vorhanden) stellen die benannten Argumente voraus. Ein benanntes Argument besteht aus einem einfachen Namen (simple-name), optional gefolgt von einem Gleichheitszeichen und einem Ausdruck. Wenn der Ausdruck ausgelassen wird, wird der Wert $true angenommen.
Der Attributname ist ein reservierter Attributtyp (§12.3) oder ein implementierungsdefinierter Attributtyp.
12.2 Attributinstanzen
Eine Attributinstanz ist ein Objekt eines Attributtyps. Die Instanz stellt zur Laufzeit ein Attribut dar.
Um ein Objekt eines Attributtyps Azu erstellen, verwenden Sie die Notation A(). Ein Attribut wird deklariert, indem seine Instanz in []eingeschlossen wird, wie in [A()]. Einige Attributtypen verfügen über Positions- und benannte Parameter (§8.14), genau wie Funktionen und Cmdlets. Beispiel:
[A(10,IgnoreCase=$true)]
enthält eine Instanz des Typs A, die mit einem positionellen Parameter mit dem Argumentwert 10 und einem benannten Parameter (IgnoreCase) mit dem Argumentwert $true erstellt wird.
12.3 Reservierte Attribute
Die in den folgenden Abschnitten beschriebenen Attribute können verwendet werden, um das Verhalten von PowerShell-Funktionen, -Filtern, -Skripts und -Cmdlets zu erweitern oder zu ändern.
12.3.1 Alias-Attribut
Dieses Attribut wird in einem Skriptparameter verwendet, um einen alternativen Namen für einen Parameter anzugeben. Ein Parameter verfügt möglicherweise über mehrere Aliase, und jeder Aliasname muss innerhalb einer Parameterlisteeindeutig sein. Eine mögliche Verwendung besteht darin, für einen Parameter in verschiedenen Parametersätzen unterschiedliche Namen zu haben (siehe ParameterSetName).
Das Attributargument hat typ string[].
Erwägen Sie einen Funktionsaufruf Test1, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[Alias("CN")]
[Alias("Name", "System")]
[string[]] $ComputerName
)
Test1 "Mars", "Saturn" # pass argument by position
Test1 -ComputerName "Mars", "Saturn" # pass argument by name
Test1 -CN "Mars", "Saturn" # pass argument using first alias
Test1 -Name "Mars", "Saturn" # pass argument using second alias
Test1 -Sys "Mars", "Saturn" # pass argument using third alias
Erwägen Sie einen Funktionsaufruf Test2, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
[Alias('PSPath')]
[string] $LiteralPath
)
Get-ChildItem "E:\*.txt" | Test2 -LiteralPath { $_ ; "`n`t";
$_.FullName + ".bak" }
Get-ChildItem "E:\*.txt" | Test2
Das Cmdlet Get-ChildItem (Alias dir) fügt dem zurückgegebenen Objekt eine neue NoteProperty vom Typ string namens PSPath hinzu.
12.3.2 Attribut „AllowEmptyCollection“
Dieses Attribut wird in einem Skriptparameter (script-parameter) verwendet, um eine leere Sammlung als Argument eines obligatorischen Parameters zu ermöglichen.
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[AllowEmptyCollection()]
[string[]] $ComputerName
)
Test "Red", "Green" # $ComputerName has Length 2
Test "Red" # $ComputerName has Length 1
Test -Comp @() # $ComputerName has Length 0
12.3.3 Attribut „AllowEmptyString“
Dieses Attribut wird in einem Skriptparameter verwendet, um eine leere Zeichenfolge als Argument eines obligatorischen Parameters zuzulassen.
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[AllowEmptyString()]
[string] $ComputerName
)
Test "Red" # $ComputerName is "Red"
Test "" # empty string is permitted
Test -Comp "" # empty string is permitted
12.3.4 Attribut „AllowNull“
Dieses Attribut wird in einem Skriptparameter (script-parameter) verwendet, um „$null“ als Argument eines obligatorischen Parameters zu ermöglichen, für den keine implizite Konvertierung verfügbar ist.
Sehen Sie sich den Funktionsaufruf „Test“ an, der den folgenden Parameterblock enthält und wie folgt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[AllowNull()]
[int[]] $Values
)
Test 10, 20, 30 # $values has Length 3, values 10, 20, 30
Test 10, $null, 30 # $values has Length 3, values 10, 0, 30
Test -Val $null # $values has value $null
Beachten Sie, dass für den oben genannten zweiten Fall dieses Attribut nicht erforderlich ist; es gibt bereits eine implizite Konvertierung von $null zu einem int.
12.3.5 Attribut „CmdletBinding“
Dieses Attribut wird in der Attributliste (attribute-list) des Parameterblocks (param-block) einer Funktion verwendet, um anzugeben, dass die Funktion ähnlich wie ein Cmdlet funktioniert. Insbesondere ermöglicht es Funktionen den Zugriff auf eine Reihe von Methoden und Eigenschaften über die $PSCmdlet Variable mithilfe von Anfangs-, Prozess- und Endnamenblöcken (§8.10.7).
Wenn dieses Attribut vorhanden ist, führen Positionsargumente ohne übereinstimmende Positionsparameter dazu, dass die Parameterbindung fehlschlägt und $args nicht definiert ist. (Ohne dieses Attribut würde „$args“ alle nicht übereinstimmenden, positionellen Argumentwerte übernehmen.)
Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| „SupportsShouldProcess“ (benannt) | Typ: bool; Standardwert: $false Gibt an, ob die Funktion Aufrufe der ShouldProcess-Methode unterstützt, die verwendet wird, um den Benutzer zur Eingabe von Feedback aufzufordern, bevor die Funktion eine Änderung am System vorgibt. Ein Wert von $true zeigt an, dass dies der Fall ist. Der Wert „$false“ gibt an, dass dies nicht unterstützt wird. |
| ConfirmImpact (benannt) | Typ: Zeichenfolge; Standardwert: "Mittel" Gibt die Auswirkungsebene der ausgeführten Aktion an. Der Aufruf der ShouldProcess-Methode zeigt eine Bestätigungsaufforderung nur an, wenn das ConfirmImpact-Argument größer oder gleich dem Wert der $ConfirmPreference Einstellungsvariable ist. Die möglichen Werte dieses Arguments sind: Keine: Unterdrückt alle Bestätigungsanforderungen. Niedrig: Die ausgeführte Aktion hat ein geringes Risiko, Daten zu verlieren. Mittel: Die ausgeführte Aktion hat ein mittleres Risiko, Daten zu verlieren. Hoch: Die ausgeführte Aktion hat ein hohes Risiko, Daten zu verlieren. Der Wert von $ConfirmPreference kann festgelegt werden, sodass nur Cmdlets mit gleicher oder höherer Auswirkung eine Bestätigung anfordern können, bevor sie ihren Vorgang ausführen. Wenn „$ConfirmPreference“ beispielsweise auf „Medium“ festgelegt ist, können Cmdlets mit der Auswirkungsstufe „Medium“ oder „High“ eine Bestätigung anfordern. Anforderungen von Cmdlets mit niedriger Auswirkungsstufe werden unterdrückt. |
| „DefaultParameterSetName“ (benannt) | Typ: Zeichenfolge; Standardwert: "__AllParameterSets" Gibt den Parameter an, der verwendet werden soll, wenn er nicht anhand der Argumente bestimmt werden kann. Weitere Informationen finden Sie im Abschnitt zum Attribut „Parameter“ im Eintrag zum benannten Argument „ParameterSetName“ ([§12.3.7][§12.3.7]). |
| „PositionalBinding“ (benannt) | Typ: bool; Standardwert: $true Gibt an, ob die positionelle Bindung unterstützt wird. Der Wert dieses Arguments wird ignoriert, wenn einige Parameter Nicht-Standardwerte für das benannte Argument Position oder das benannte Argument ParameterSetName im Attribut Parameter festlegen ([§12.3.7][§12.3.7]). Andernfalls, wenn das Argument $false ist, sind keine Parameter positional, andernfalls werden Parametern basierend auf der Reihenfolge, in der die Parameter angegeben werden, eine Position zugewiesen. |
Im Folgenden finden Sie ein Beispiel für das Framework für die Verwendung dieses Attributs:
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Low")]
param ( ... )
begin { ... }
Get-process { ... }
end { ... }
12.3.6 Das OutputType-Attribut
Dieses Attribut wird in der Attributliste (attribute-list) des Parameterblocks (param-block) verwendet, um die zurückgegebenen Typen anzugeben. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| Typ (Position 0) | Typ: „string[]“ oder ein Array von Typliteralen Eine Liste der Typen der zurückgegebenen Werte. |
| „ParameterSetName“ (benannt) | Typ: „string[]“ Gibt die Parametersätze an, die die durch die entsprechenden Elemente des Type-Parameters angegebenen Typen zurückgeben. |
Hier sind mehrere Beispiele für die Verwendung dieses Attributs:
[OutputType([int])] param ( ... )
[OutputType("double")] param ( ... )
[OutputType("string","string")] param ( ... )
12.3.7 Das Parameter-Attribut
Dieses Attribut wird in einem Skriptparameter (script-parameter) verwendet. Die folgenden benannten Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parameter | Zweck |
|---|---|
| „HelpMessage“ (benannt) | Typ: Zeichenfolge Dieses Argument gibt eine Nachricht an, die eine kurze Beschreibung des Parameters enthalten soll. Diese Meldung wird auf eine implementierungsdefinierte Weise verwendet, wenn die Funktion oder das Cmdlet ausgeführt wird, aber ein obligatorischer Parameter, der mit einer Hilfenachricht versehen ist, kein entsprechendes Argument aufweist. Das folgende Beispiel zeigt eine Parameterdeklaration, die eine Beschreibung des Parameters bereitstellt. param ( [Parameter(Verpflichtend = $true; Windows PowerShell: Wenn ein erforderlicher Parameter nicht angegeben wird, fordert die Runtime den Benutzer zur Eingabe eines Parameterwerts auf. Das Dialogfeld mit der Eingabeaufforderung enthält den HelpMessage-Text. |
| „Mandatory“ (benannt) | Typ: bool; Standardwert: $false Dieses Argument gibt an, ob der Parameter innerhalb des angegebenen Parametersatzes erforderlich ist (siehe ParameterSetName-Argument unten). Ein Wert von $true gibt an, dass es zutrifft. Ein Wert von $false zeigt an, dass es nicht so ist. param ( [Parameter(Verpflichtend = $true)] Windows PowerShell: Wenn ein erforderlicher Parameter nicht angegeben wird, fordert die Runtime den Benutzer zur Eingabe eines Parameterwerts auf. Das Dialogfeld mit der Eingabeaufforderung enthält den HelpMessage-Text (sofern verfügbar). |
| „ParameterSetName“ (benannt) | Typ: Zeichenfolge; Standardwert: "__AllParameterSets" Es ist möglich, eine einzelne Funktion oder ein cmdlet zu schreiben, die verschiedene Aktionen für verschiedene Szenarien ausführen kann. Dies wird ermöglicht, indem verschiedene Gruppen von Parametern verfügbar gemacht werden, abhängig von der Aktion, die Sie ergreifen möchten. Solche Parametergruppierungen werden als Parametersätzegenannt. Das Argument ParameterSetName gibt den Parametersatz an, zu dem ein Parameter gehört. Dieses Verhalten bedeutet, dass jeder Parametersatz über einen eindeutigen Parameter verfügen muss, der kein Element eines anderen Parametersatzes ist. Fügen Sie für Parameter, die zu mehreren Parametersätzen gehören, ein Parameter-Attribut für jeden Parametersatz hinzu. Dadurch kann der Parameter für jeden Parametersatz unterschiedlich definiert werden. Ein Parametersatz, der mehrere Positionsparameter enthält, muss eindeutige Positionen für jeden Parameter definieren. Keine zwei Positionsparameter können dieselbe Position angeben. Wenn kein Parametersatz für einen Parameter angegeben ist, gehört der Parameter zu allen Parametersätzen. Wenn mehrere Parametersätze definiert sind, wird das benannte Argument DefaultParameterSetName des Attributs CmdletBinding ([§12.3.5][§12.3.5]) verwendet, um den Standardparametersatz anzugeben. Die Runtime verwendet den Standardparametersatz, wenn der zu verwendende Parametersatz nicht anhand der vom Befehl bereitgestellten Informationen bestimmt werden kann, oder die Runtime löst eine Ausnahme aus, wenn kein Standardparametersatz angegeben wurde. Das folgende Beispiel zeigt die Funktion „Test“ mit einer Parameterdeklaration von zwei Parametern, die zu zwei verschiedenen Parametersätzen gehören, und einem dritten Parameter, der zu beiden Sätzen gehört: param ( [Parameter(Verpflichtend = $true; [Parameter(Verpflichtend = $true; [Parameter(Verpflichtend = $true; if ($PSCmdlet.ParameterSetName -eq "Computer") elseif ($PSCmdlet.ParameterSetName -eq "User") Testen -ComputerName "Mars","Venus" -SharedParam 10 |
| Position (genannt) | Typ: int Dieses Argument gibt die Position des Parameters in der Argumentliste an. Wenn dieses Argument nicht angegeben ist, muss der Parametername oder sein Alias explizit angegeben werden, wenn der Parameter festgelegt wird. Wenn keiner der Parameter einer Funktion Positionen aufweist, werden den einzelnen Parametern positionen basierend auf der Reihenfolge zugewiesen, in der sie empfangen werden. Das folgende Beispiel zeigt die Deklaration eines Parameters, dessen Wert als erstes Argument angegeben werden muss, wenn die Funktion aufgerufen wird. param ( [Parameter(Position = 0)] |
| „ValueFromPipeline“ (benannt) | Typ: bool; Standardwert: $false Dieses Argument gibt an, ob der Parameter Eingaben aus einem Pipelineobjekt akzeptiert. Ein Wert von $true zeigt an, dass dies der Fall ist. Ein Wert von $false gibt an, dass dies nicht der Fall ist. Geben Sie $true an, wenn die Funktion oder das Cmdlet auf das vollständige Objekt zugreift, nicht nur auf eine Eigenschaft des Objekts. Nur ein Parameter in einem Parametersatz kann ValueFromPipeline als $true deklarieren. Das folgende Beispiel zeigt die Parameterdeklaration eines obligatorischen Parameters, $ComputerName, das das Eingabeobjekt akzeptiert, das von der Pipeline an die Funktion übergeben wird. param ( [Parameter(Verpflichtend = $true; Ein Beispiel für die Verwendung dieses Parameters in Verbindung mit dem Alias-Attribut finden Sie unter [§12.3.1][§12.3.1]. |
| „ValueFromPipelineByPropertyName“ (benannt) | Typ: bool; Standardwert: $false Dieses Argument gibt an, ob der Parameter seinen Wert aus einer Eigenschaft eines Pipelineobjekts verwendet, die entweder denselben Namen oder denselben Alias wie dieser Parameter aufweist. Ein Wert von $true zeigt an, dass dies der Fall ist. Ein Wert von $false gibt an, dass dies nicht der Fall ist. Geben Sie $true an, wenn die folgenden Bedingungen erfüllt sind: Der Parameter greift auf eine Eigenschaft des piped-Objekts zu, und die Eigenschaft hat denselben Namen wie der Parameter, oder die Eigenschaft hat denselben Alias wie der Parameter. Bei einem Parameter, für den „ValueFromPipelineByPropertyName“ auf „$true“ festgelegt ist, muss kein Parameter im selben Satz enthalten sein, für den „ValueFromPipeline“ auf „$true“ festgelegt ist. Wenn eine Funktion einen Parameter $ComputerName hat und das piped-Objekt eine ComputerName-Eigenschaft aufweist, wird der Wert der ComputerName-Eigenschaft dem $ComputerName Parameter der Funktion zugewiesen: param ( [Parameter(Verpflichtend = $true; Mehrere Parameter in einem Parametersatz können „ValueFromPipelineByPropertyName“ als „$true“ definieren. Obwohl ein einzelnes Eingabeobjekt nicht an mehrere Parameter gebunden werden kann, können unterschiedliche Eigenschaften in diesem Eingabeobjekt an verschiedene Parameter gebunden werden. Beim Binden eines Parameters mit einer Eigenschaft eines Eingabeobjekts sucht die Laufzeitumgebung zunächst nach einer Eigenschaft mit demselben Namen wie der Parameter. Wenn eine solche Eigenschaft nicht existiert, sucht die Laufzeitumgebung in der Reihenfolge ihrer Deklaration nach Aliasen für diesen Parameter und wählt den ersten solchen Alias aus, für den eine Eigenschaft existiert. Process-Date [Parameter(ValueFromPipelineByPropertyName=$true)] [Parameter(ValueFromPipelineByPropertyName=$true)] prozess { ... } |
| „ValueFromRemainingArguments“ (benannt) | Typ: bool; Standardwert: $false Dieses Argument gibt an, ob der Parameter alle verbleibenden Argumente akzeptiert, die nicht an die Parameter der Funktion gebunden sind. Ein Wert von $true zeigt an, dass dies der Fall ist. Ein Wert von $false gibt an, dass dies nicht der Fall ist. Das folgende Beispiel zeigt einen Parameter $Others, der alle verbleibenden Argumente des Eingabeobjekts akzeptiert, das an die Funktion Test übergeben wird: param ( [Parameter(Obligator = $true)][int] $p 1, Test 10 20 # $Others hat Länge 0 |
Eine Implementierung kann auch andere Attribute definieren.
Die folgenden Attribute werden ebenfalls bereitgestellt:
- HelpMessageBaseName: Gibt den Speicherort an, an dem sich Ressourcenbezeichner befinden. Beispielsweise könnte dieser Parameter eine Ressourcensammlung angeben, die Hilfemeldungen enthält, die lokalisiert werden sollen.
- HelpMessageResourceId: Gibt den Ressourcenbezeichner für eine Hilfemeldung an.
12.3.8 Das PSDefaultValue-Attribut
Dieses Attribut wird in einem Skriptparameter (script-parameter) verwendet, um zusätzliche Informationen über den Parameter zur Verfügung zu stellen. Das Attribut wird auf eine implementierungsdefinierte Weise verwendet. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| „Help“ (benannt) | Typ: Zeichenfolge Dieses Argument gibt eine Nachricht an, die eine kurze Beschreibung des Standardwerts eines Parameters enthalten soll. Diese Meldung wird auf durch die Implementierung definierte Weise verwendet. Windows PowerShell: Die Nachricht wird als Teil der Beschreibung des Parameters für das Hilfethema verwendet, das vom Cmdlet [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) angezeigt wird. |
| „Value“ (benannt) | Typ: Objekt Dieses Argument gibt einen Wert an, der als Standardwert eines Parameters vorgesehen ist. Der Wert wird auf implementierungsdefinierte Weise verwendet. Windows PowerShell: Der Wert wird als Teil der Beschreibung des Parameters für das Hilfethema verwendet, das vom Cmdlet [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help angezeigt wird, wenn die Help-Eigenschaft nicht angegeben ist. |
12.3.9 Attribut „SupportsWildcards“
Dieses Attribut wird in einem Skriptparameter (script-parameter) verwendet, um zusätzliche Informationen über den Parameter zur Verfügung zu stellen. Das Attribut wird auf eine implementierungsdefinierte Weise verwendet.
Dieses Attribut wird als Teil der Beschreibung des Parameters für den Hilfeinhalt verwendet, der vom Cmdlet Get-Help angezeigt wird.
12.3.10 Attribut „ValidateCount“
Dieses Attribut wird in einem Skriptparameter verwendet, um die minimale und maximale Anzahl von Argumentwerten anzugeben, die der Parameter akzeptieren kann. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| Mindestlänge (Position 0) | Typ: int Dieses Argument gibt die mindestanzahl zulässiger Argumentwerte an. |
| „MaxLength“ (Position 1) | Typ: int Dieses Argument gibt die maximale Anzahl zulässiger Argumentwerte an. |
Wenn dieses Attribut nicht vorhanden ist, kann die entsprechende Argumentwertliste des Parameters eine beliebige Länge aufweisen.
Sehen Sie sich den Funktionsaufruf „Test“ an, der den folgenden Parameterblock enthält und wie folgt aufgerufen wird:
param (
[ValidateCount(2, 5)]
[int[]] $Values
)
Temp 10, 20, 30
Temp 10 # too few argument values
Temp 10, 20, 30, 40, 50, 60 # too many argument values
[ValidateCount(3, 4)]$Array = 1..3
$Array = 10 # too few argument values
$Array = 1..100 # too many argument values
12.3.11 Attribut „ValidateLength“
Dieses Attribut wird in einem Skript-Parameter oder einer Variable verwendet, um die minimale und maximale Länge des Arguments des Parameters anzugeben, die vom Typ Zeichenfolge sein muss. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| Mindestlänge (Position 0) | Typ: int Dieses Argument gibt die mindest zulässige Anzahl von Zeichen an. |
| „MaxLength“ (Position 1) | Typ: int Dieses Argument gibt die maximale Anzahl zulässiger Zeichen an. |
Wenn dieses Attribut nicht vorhanden ist, kann das entsprechende Argument des Parameters eine beliebige Länge aufweisen.
Sehen Sie sich den Funktionsaufruf „Test“ an, der den folgenden Parameterblock enthält und wie folgt aufgerufen wird:
param ( [Parameter(Mandatory = $true)]
[ValidateLength(3,6)]
[string[]] $ComputerName )
Test "Thor","Mars" # length is ok
Test "Io","Mars" # "Io" is too short
Test "Thor","Jupiter" # "Jupiter" is too long
12.3.12 Das ValidateNotNull-Attribut
Dieses Attribut wird in einem Skriptparameter (script-parameter) oder einer Variablen verwendet, um anzugeben, dass das Argument des Parameters nicht $null oder eine Sammlung mit einem Element mit NULL-Wert sein kann.
Sehen Sie sich den Funktionsaufruf Test an, der den folgenden Parameterblock enthält und wie folgt aufgerufen wird:
param (
[ValidateNotNull()]
[string[]] $Names
)
Test "Jack", "Jill" # ok
Test "Jane", $null # $null array element value not allowed
Test $null # null array not allowed
[ValidateNotNull()]$Name = "Jack" # ok
$Name = $null # null value not allowed
12.3.13 Attribut „ValidateNotNullOrEmpty“
Dieses Attribut wird in einem Skriptparameter (script-parameter) oder einer Variablen verwendet, um anzugeben, dass das Argument des Parameters nicht „$null“, eine leere Zeichenfolge, ein leeres Array oder eine Sammlung sein kann, die ein Element mit $null-Wert oder einer leeren Zeichenfolge enthält.
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[ValidateNotNullOrEmpty()]
[string[]] $Names
)
Test "Jack", "Jill" # ok
Test "Mary", "" # empty string not allowed
Test "Jane", $null # $null array element value not allowed
Test $null # null array not allowed
Test @() # empty array not allowed
[ValidateNotNullOrEmpty()]$Name = "Jack" # ok
$Name = "" # empty string not allowed
$Name = $null # null value not allowed
12.3.14 Das ValidatePattern-Attribut
Dieses Attribut wird in einem Skriptparameter (script-parameter) oder einer Variablen verwendet, um einen regulären Ausdruck für den Abgleich mit dem Muster des Parameterarguments anzugeben. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| RegexString (Position 0) | Typ: Zeichenfolge Ein regulärer Ausdruck, der zum Überprüfen des Arguments des Parameters verwendet wird |
| Optionen (mit Namen versehen) | Typ: „Regular-Expression-Option“ Die zulässigen Werte finden Sie unter [§4.2.6.4][§4.2.6.4]. |
Wenn es sich bei dem Argument um eine Auflistung handelt, muss jedes Element in der Auflistung mit dem Muster übereinstimmen.
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[ValidatePattern('\^[A-Z][1-5][0-9]$')]
[string] $Code,
[ValidatePattern('\^(0x|0X)([A-F]|[a-f]|[0-9])([A-F]|[a-f]|[0-9])$')]
[string] $HexNum,
[ValidatePattern('\^[+|-]?[1-9]$')]
[int] $Minimum
)
Test -C A12 # matches pattern
Test -C A63 # does not match pattern
Test -H 0x4f # matches pattern
Test -H "0XB2" # matches pattern
Test -H 0xK3 # does not match pattern
Test -M -4 # matches pattern
Test -M "+7" # matches pattern
Test -M -12 # matches pattern, but is too long
[ValidatePattern('\^[a-z][a-z0-9]\*$')]$ident = "abc"
$ident = "123" # does not match pattern
12.3.15 Attribut „ValidateRange“
Dieses Attribut wird in einem Skriptparameter oder einer Variablen verwendet, um die Mindest- und Höchstwerte des Arguments des Parameters festzulegen. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| MinRange (Position 0) | Typ: Objekt Dieses Argument gibt den zulässigen Minimalwert an. |
| „MaxRange“ (Position 1) | Typ: Objekt Dieses Argument gibt den maximal zulässigen Wert an. |
Wenn dieses Attribut nicht vorhanden ist, gibt es keine Bereichseinschränkung.
Erwägen Sie einen Funktionsaufruf Test1, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[ValidateRange(1, 10)]
[int] $StartValue
)
Test1 2
Test1 -St 7
Test1 -3 # value is too small
Test1 12 # value is too large
Sehen Sie sich den Funktionsaufruf „Test2“ an, der den folgenden Parameterblock enthält und wie folgt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[ValidateRange("b", "f")]
[string] $Name
)
Test2 "Bravo" # ok
Test2 "Alpha" # value compares less than the minimum
Test2 "Hotel" # value compares greater than the maximum
Erwägen Sie einen Funktionsaufruf Test3, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[ValidateRange(0.002, 0.003)]
[double] $Distance
)
Test3 0.002
Test3 0.0019 # value is too small
Test3 "0.005" # value is too large
[ValidateRange(13, 19)]$teenager = 15
$teenager = 20 # value is too large
12.3.16 Das ValidateScript-Attribut
Dieses Attribut wird in einem Skriptparameter oder einer Variable genutzt, um ein Skript zur Überprüfung des Argumentes des Parameters anzugeben.
Das Argument an Position 1 ist ein Skriptblockausdruck (script-block-expression).
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param (
[Parameter(Mandatory = $true)]
[ValidateScript( { ($_ -ge 1 -and $_ -le 3) -or ($_ -ge 20) })]
[int] $Count
)
Test 2 # ok, valid value
Test 25 # ok, valid value
Test 5 # invalid value
Test 0 # invalid value
[ValidateScript({$_.Length --gt 7})]$password = "password" # ok
$password = "abc123" # invalid value
12.3.17 Das ValidateSet-Attribut
Dieses Attribut wird in einem Skriptparameter (script-parameter) oder einer Variablen verwendet, um eine Gruppe gültiger Werte für das Argument des Parameters anzugeben. Die folgenden Argumente werden verwendet, um die Merkmale des Parameters zu definieren:
| Parametername | Zweck |
|---|---|
| „ValidValues“ (Position 0) | Typ: „string[]“ Die Gruppe gültiger Werte. |
| „IgnoreCase“ (benannt) | Typ: bool; Standardwert: $true Gibt an, ob die Groß- und Kleinschreibung für Parameter vom Typ „string“ ignoriert werden soll. |
Wenn der Parameter einen Arraytyp aufweist, muss jedes Element des entsprechenden Argumentarrays mit einem Element des Wertsatzes übereinstimmen.
Erwägen Sie einen Funktionsaufruf Test, der den folgenden Paramblock aufweist und wie gezeigt aufgerufen wird:
param ( [ValidateSet("Red", "Green", "Blue")]
[string] $Color,
[ValidateSet("up", "down", "left", "right", IgnoreCase =
$false)]
[string] $Direction
)
Test -Col "RED" # case is ignored, is a member of the set
Test -Col "white" # case is ignored, is not a member of the set
Test -Dir "up" # case is not ignored, is a member of the set
Test -Dir "Up" # case is not ignored, is not a member of the set
[ValidateSet(("Red", "Green", "Blue")]$color = "RED" # ok, case is ignored
$color = "Purple" # case is ignored, is not a member of the set
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
