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 eine kulturinvariante Analyse 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 datum im deutschen Format wird an den Parameter übergeben.
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
Wie oben gezeigt, verwenden Cmdlets kulturabhängige 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 übernimmt Eingaben aus der Pipeline.
- Es verwendet ein Array von Zeichenfolgen als Eingabe.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Switch-Parameter
Switchparameter sind Parameter, die keinen Parameterwert annehmen. Stattdessen übermitteln sie einen booleschen True-or-False-Wert durch ihre Anwesenheit oder Abwesenheit, sodass, wenn ein switch-Parameter vorhanden ist, einen true-Wert und wenn er nicht vorhanden ist, einen false-Wert aufweist.
Der Recurse-Parameter von Get-ChildItem ist beispielsweise ein switch-Parameter.
Um einen switch-Parameter in einer Funktion zu erstellen, geben Sie den switch Typ in der Parameterdefinition an.
Ihre Funktion kann beispielsweise über eine Option zum Ausgeben von Daten als Bytearray verfügen:
param([switch]$AsByteArray)
Switch-Parameter sind einfach zu verwenden und werden gegenüber booleschen Parametern bevorzugt, die eine weniger natürliche Syntax für PowerShell haben.
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 die Auswirkung des Parameters an den Benutzer kommuniziert. Vermeiden Sie mehrdeutige Begriffe wie Filter oder Maximum , die bedeuten können, dass ein Wert erforderlich ist.
Überlegungen zum Switchparameterentwurf
Switchparameter sollten keine Standardwerte erhalten. Sie sollten immer auf false festgelegt sein.
Switch-Parameter sind standardmäßig von Positionsparametern ausgeschlossen. Auch wenn andere Parameter implizit positioniert sind, sind switch-Parameter nicht vorhanden. Sie können dies im Parameter-Attribut überschreiben, aber dies führt zu Verwirrung bei den Benutzern.
Switch-Parameter sollten so entworfen werden, dass durch ihre Einstellung ein Befehl von seinem Standardverhalten in einen weniger häufigen oder komplizierteren Modus verschoben wird. Das einfachste Verhalten eines Befehls sollte das Standardverhalten sein, für das keine Switchparameter erforderlich sind.
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 Wechsels von einem booleschen Wert kann mit
-MySwitch:$boolValueund in der Splatting mit$params = @{ MySwitch = $boolValue }erfolgen.Switch-Parameter sind vom Typ
SwitchParameter, der implizit in boolesche Werte konvertiert. 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 Encoding-Parameter 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.
Verwenden Sie den DynamicParam Schlüsselwort (keyword), um einen dynamischen Parameter für eine Funktion oder ein Skript zu erstellen.
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 Standardparametern namens Name und Path sowie einen optionalen dynamischen Parameter namens KeyCount. Der KeyCount-Parameter befindet sich im ByRegistryPath Parametersatz und weist den Typ auf Int32. Der KeyCount-Parameter ist in der Get-Sample Funktion nur 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 Beschränkung für die Anzahl von Attributen, die Sie einer Parameterdeklaration hinzufügen können.
Parameterattribut
Das Parameter-Attribut wird verwendet, um die Attribute von Funktionsparametern zu deklarieren.
Das Parameter-Attribut ist optional, und Sie können es weglassen, wenn keiner der Parameter Ihrer Funktionen Attribute benötigt. Um jedoch als erweiterte Funktion und nicht als einfache Funktion erkannt zu werden, muss eine Funktion entweder über das CmdletBinding-Attribut oder das Parameter-Attribut oder beides verfügen.
Das Parameter-Attribut verfügt über Argumente, die die Merkmale des Parameters definieren, z. B. ob der Parameter obligatorisch oder optional ist.
Verwenden Sie die folgende Syntax, um das Parameter-Attribut , ein Argument und einen Argumentwert zu deklarieren. Die Klammern, die das Argument und seinen Wert einschließen, müssen Parameter ohne dazwischen liegendes 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)]
$ParameterName
)
Die booleschen Argumenttypen des Parameter-Attributs sind standardmäßig False , wenn sie im Parameter-Attribut ausgelassen werden. Legen Sie den Argumentwert auf fest, $true oder listen Sie das Argument einfach anhand des Namens auf. Die folgenden Parameterattribute sind z. B. gleichwertig.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Wenn Sie das Parameter-Attribut ohne Argumente verwenden, sind als Alternative zur Verwendung des CmdletBinding-Attributs 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
)
Position-Argument
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 ist, muss der Parametername oder ein Parameternamenalias 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. 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, 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 einen Parameter in mehr als einen Parametersatz einzuschließen, 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
)
Betrachten Sie eine Implementierung einer Funktion mit diesem Argument:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Eine Demonstration für das Piping eines Objekts mit der ComputerName-Eigenschaft wäre dann:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
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.Object definiert sind. Der Skriptblock wird übergeben, ohne aufgerufen zu werden. Weitere Informationen zu Verzögerungsbindungsskriptblöcken finden Sie unter about_Script_Blocks.
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(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$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
HelpMessage-Argument
Das HelpMessage Argument gibt eine Zeichenfolge an, die eine kurze Beschreibung des Parameters oder seines Werts enthält. Wenn Sie den Befehl ohne den obligatorischen Parameter ausführen, werden Sie von PowerShell zur Eingabe aufgefordert. Um die Hilfenachricht anzuzeigen, geben Sie an der Eingabeaufforderung ein !? , und drücken Sie die EINGABETASTE.
Im folgenden Beispiel werden ein obligatorischer ComputerName-Parameter und eine Hilfemeldung deklariert, in der der erwartete Parameterwert erläutert wird.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Beispielausgabe:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
Wenn keine kommentarbasierte Hilfe für die Funktion vorhanden ist, wird diese Meldung in der Get-Help -Full Ausgabe angezeigt.
Dieses Argument hat keine Auswirkungen auf optionale Parameter.
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
)
Credential-Attribut
Das Credential-Attribut wird verwendet, um anzugeben, dass der Parameter Anmeldeinformationen akzeptiert. Das folgende Beispiel zeigt eine Parameterdeklaration, die das Credential-Attribut verwendet.
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Experimentelles Attribut
Verwenden Sie das Experimental-Attribut , um Code als experimentell zu deklarieren. Eine vollständige Beschreibung des Attributs finden Sie unter about_Experimental_Features.
PSDefaultValue-Attribut
PsDefaultValue gibt den Standardwert eines Befehlsparameters in einem Skript an. Diese Informationen werden vom Get-Help Cmdlet angezeigt. Um die Standardwertinformationen anzuzeigen, muss die Funktion kommentarbasierte Hilfe enthalten. Beispiel:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Verwenden Sie Get-Help , um die Standardwertinformationen anzuzeigen.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
PSDefaultValue-Attributargumente
Das PSDefaultValue-Attribut weist zwei Argumente auf:
- Hilfe : Eine Zeichenfolge, die den Standardwert beschreibt. Diese Informationen werden vom
Get-HelpCmdlet angezeigt. - Wert : Der Standardwert des Parameters.
Beide Argumente sind optional. Wenn Sie keine Argumente angeben, wird der Get-Help dem Parameter zugewiesene Wert angezeigt.
PSTypeName-Attribut
Sie können keine erweiterten Typnamen in einer Typdeklaration verwenden. Mit dem PSTypeName*-Attribut können Sie den Typ des Parameters auf den erweiterten Typ einschränken.
In diesem Beispiel gibt das Test-Connection Cmdlet einen erweiterten Typ zurück. Sie können das PSTypeName-Attribut verwenden, um den Typ des Parameters auf den erweiterten Typ einzuschränken.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
System.Obsolete-Attribut
Verwenden Sie das System.Obsolete-Attribut , um Parameter zu markieren, die nicht mehr unterstützt werden. Dies kann nützlich sein, wenn Sie einen Parameter aus einer Funktion entfernen möchten, aber keine vorhandenen Skripts unterbrechen möchten, die die Funktion verwenden.
Betrachten Sie beispielsweise eine Funktion, die über einen NoTypeInformation-Switchparameter verfügt, der steuert, ob Typinformationen in der Ausgabe enthalten sind. Sie möchten dieses Verhalten als Standard festlegen und den Parameter aus der Funktion entfernen. Sie möchten jedoch keine vorhandenen Skripts unterbrechen, die die Funktion verwenden. Sie können den Parameter als veraltet markieren und eine Meldung hinzufügen, in der die Änderung erläutert wird.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
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. Wie 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 bereitgestellte 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.
[AllowNull()] [int]$number = 7
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.
Hinweis
Wenn Sie Attribute mit einer typisierten Variablen verwenden, empfiehlt es sich, das Attribut vor dem Typ zu deklarieren.
Wenn Sie einen Typ mit einem Zeilenumbruch vor dem Attribut- und Variablennamen deklarieren, wird der Typ als seine eigene Anweisung behandelt.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Wenn Sie ein Validierungsattribut nach einem Typ deklarieren, wird der zugewiesene Wert vor der Typkonvertierung überprüft, was zu unerwarteten Validierungsfehlern führen kann.
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
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 $text mindestens ein Zeichen und maximal zehn Zeichen lang sein.
[ValidateLength(1,10)] [string] $text = 'valid'
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]{4}")]
[string[]]$ComputerName
)
Im folgenden Beispiel muss der Wert der Variablen $ticketID genau eine vierstellige Zahl sein, und jede Ziffer muss eine Zahl 0 bis neun sein.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 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.
[ValidateRange(0,10)] [int]$number = 5
Im folgenden Beispiel muss der Wert der Variablen $number größer als 0 sein.
[ValidateRange("Positive")] [int]$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 kleiner oder gleich dem aktuellen Datum und der aktuellen Uhrzeit sein.
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
Hinweis
Wenn Sie ValidateScript verwenden, können Sie keinen Wert an den Parameter übergeben $null . Wenn Sie einen NULL-Wert übergeben , kann ValidateScript das Argument nicht überprüfen.
Überschreiben der Standardfehlermeldung
Ab PowerShell 6 können Sie die Standardfehlermeldung überschreiben, die generiert wird, wenn ein angegebener Wert mit dem ErrorMessage Argument ungültig ist. Geben Sie eine zusammengesetzte Formatzeichenfolge an. Die 0 Indexkomponente verwendet den Eingabewert.
Die 1 Indexkomponente verwendet den ScriptBlock , der zum Überprüfen des Eingabewerts verwendet wird.
Im folgenden Beispiel muss der Wert des EventDate-Parameters größer oder gleich dem aktuellen Datum und der aktuellen Uhrzeit sein. Wenn der Wert ungültig ist, meldet die Fehlermeldung, dass das angegebene Datum und die angegebene Uhrzeit zu alt sind.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Wenn der angegebene Wert ein vergangenes Datum ist, wird die benutzerdefinierte Fehlermeldung zurückgegeben.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
Sie können weitere Formatierungen in der Zeichenfolge mit optionalen Formatzeichenfolgenkomponenten anwenden.
Im folgenden Beispiel muss der Wert des EventDate-Parameters größer oder gleich dem aktuellen Datum und der aktuellen Uhrzeit sein. Wenn der Wert ungültig ist, wird in der Fehlermeldung gemeldet, dass das angegebene Datum zu alt ist.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Wenn der angegebene Wert ein vergangenes Datum ist, wird die benutzerdefinierte Fehlermeldung zurückgegeben.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
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. Wenn der Wert ist $null, löst PowerShell eine Ausnahme aus.
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 einen NULL-Wert implizit konvertiert, z. B. eine Zeichenfolge, wird der NULL-Wert auch bei Verwendung des ValidateNotNull-Attributs in eine leere Zeichenfolge konvertiert. Verwenden Sie für dieses Szenario das ValidateNotNullOrEmpty-Attribut .
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 zugewiesene Wert keinen der folgenden Werte sein darf:
$null- eine leere Zeichenfolge (
"") - ein leeres Array (
@())
Wenn der Wert ungültig ist, löst PowerShell eine Ausnahme aus.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
ValidateDrive-Validierungsattribut
Das ValidateDrive-Attribut gibt an, dass der Parameterwert den Pfad darstellen muss, der nur auf zulässige Laufwerke verweist. PowerShell generiert einen Fehler, wenn sich der Parameterwert auf andere Laufwerke als das zulässige 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 im User Laufwerk dargestellt werden muss. PowerShell generiert einen Fehler, wenn der Pfad auf ein anderes Laufwerk verweist. Das Validierungsattribut testet nur, dass das Laufwerkpräfix 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
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.