about_Functions_Advanced_Parameters
Kurze Beschreibung
Erläutert das Hinzufügen von Parametern zu erweiterten Funktionen.
Lange Beschreibung
Sie können Parameter zu den erweiterten Funktionen hinzufügen, die Sie schreiben, und Parameterattribute und Argumente verwenden, um die Parameterwerte einzuschränken, die von Benutzern der Funktion mit dem Parameter übermittelt werden.
Die Parameter, die Sie Zu Ihrer Funktion hinzufügen, stehen Benutzern zusätzlich zu den allgemeinen Parametern zur Verfügung, die PowerShell allen Cmdlets und erweiterten Funktionen automatisch hinzufügt. Weitere Informationen zu den allgemeinen PowerShell-Parametern finden Sie unter about_CommonParameters.
Ab PowerShell 3.0 können Sie mithilfe von Splatting @Args die Parameter in einem Befehl darstellen. Splatting ist für einfache und erweiterte Funktionen gültig. Weitere Informationen finden Sie unter about_Functions und about_Splatting.
Typkonvertierung von Parameterwerten
Wenn Sie Zeichenfolgen als Argumente für Parameter bereitstellen, 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 verwendet. Die aktuelle Kultur wird geändert, um deutsche Einstellungen zu verwenden.
An den Parameter wird ein deutsch formatiertes Datum ü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 die kulturinvariante Analyse, was zu folgendem Fehler führt.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
Statische Parameter
Statische Parameter sind Parameter, die immer in der Funktion 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:
- Es ist obligatorisch (erforderlich).
- Es übernimmt Eingaben aus der Pipeline.
- Es verwendet ein Array von Zeichenfolgen als Eingabe.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Switch-Parameter
Switch-Parameter sind Parameter, die keinen Parameterwert annehmen. Stattdessen vermitteln sie einen booleschen True-or-False-Wert durch ihre Anwesenheit oder Abwesenheit, sodass wenn ein Switch-Parameter vorhanden ist, ein wahrer Wert und wenn er nicht vorhanden ist, einen falschen Wert aufweist.
Beispielsweise ist der Recurse-ParameterGet-ChildItem ein Switch-Parameter.
Um einen Switch-Parameter in einer Funktion zu erstellen, geben Sie den switch Typ in der Parameterdefinition an.
Ihre Funktion kann z. B. eine Option zum Ausgeben von Daten als Bytearray haben:
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 aufweisen.
Wenn Sie beispielsweise einen Switch-Parameter verwenden möchten, gibt der Benutzer den Parameter in den Befehl ein.
-IncludeAll
Um einen booleschen Parameter zu verwenden, gibt der Benutzer den Parameter und einen booleschen Wert ein.
-IncludeAll $true
Wählen Sie beim Erstellen von Switchparametern den Parameternamen sorgfältig aus. Stellen Sie sicher, dass der Parametername die Auswirkung des Parameters an den Benutzer kommuniziert. Vermeiden Sie mehrdeutige Ausdrücke, z . B. "Filter " oder "Maximum ", die möglicherweise einen Wert bedeuten, erforderlich ist.
Überlegungen zum Wechseln des Parameterentwurfs
Switch-Parameter sollten keine Standardwerte erhalten. Sie sollten immer auf "false" festgelegt sein.
Schalterparameter werden standardmäßig von Positionsparametern ausgeschlossen. Auch wenn andere Parameter implizit positional sind, sind Schalterparameter nicht zulässig. Sie können dies im Parameter-Attribut außer Kraft setzen, aber benutzer werden verwirren.
Switch-Parameter sollten so entworfen werden, dass das Festlegen eines Befehls von seinem Standardverhalten auf einen weniger gängigen oder komplizierteren Modus wechselt. Das einfachste Verhalten eines Befehls sollte das Standardverhalten sein, das die Verwendung von Switchparametern nicht erfordert.
Switch-Parameter sollten nicht obligatorisch sein. Der einzige Fall, in dem es erforderlich ist, einen Switchparameter obligatorisch zu machen, ist, wenn ein Parametersatz unterschieden werden muss.
Das explizite Festlegen eines Wechsels von 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. Zum 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 z. B. nur für das Get-ContentAdd-ContentDateisystemlaufwerk verfügbar, und Set-Content cmdlets sind nur 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 sie nur bei Bedarf verwenden, da sie für Benutzer schwer zu erkennen sind. 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-Help.
Verwenden Sie die 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 hat einen Typ von Int32. Der KeyCount-Parameter ist nur in der Get-Sample Funktion verfügbar, wenn der Wert des Path-Parameters beginnt mit HKLM:, der 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 für den RuntimeDefinedParameter-Typ .
Attribute von Parametern
In diesem Abschnitt werden die Attribute beschrieben, die Sie Zu 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 auf die Anzahl der Attribute, 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 keines 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, um als erweiterte Funktion erkannt zu werden.
Das Parameter-Attribut weist Argumente auf, 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 dessen Wert einschließen, müssen parameter ohne dazwischen liegende 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 standard auf False , wenn sie aus dem Parameter-Attribut weggelassen werden. Legen Sie den Argumentwert auf $true das Argument fest 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, ist 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 ist, 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 nicht benannten Parameterwerte im Befehl.
Wenn das Position Argument nicht angegeben ist, 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 $False. Das Position Argument hat Vorrang vor dem Wert des PositionalBinding Arguments des CmdletBinding-Attributs . Weitere Informationen finden Sie in PositionalBindingabout_Functions_CmdletBindingAttribute.
Der Wert des Position Arguments wird als ganze Zahl angegeben. Ein Positionswert von 0 stellt die erste Position im Befehl dar, ein Positionswert von 1 stellt die zweite Position im Befehl usw. dar.
Wenn eine Funktion keine Positionsparameter aufweist, weist PowerShell jedem Parameter basierend auf der Reihenfolge, in der die Parameter deklariert werden, Positionen zu. Verlassen Sie sich als bewährte Methode jedoch nicht auf diese Aufgabe. Wenn Parameter positional sein sollen, verwenden Sie das Position Argument.
Im folgenden Beispiel wird der ComputerName-Parameter deklariert. Es verwendet das Position Argument mit dem Wert 0. -ComputerName Wenn der Wert aus dem Befehl weggelassen wird, muss der Wert daher der erste oder nur unbenannte Parameterwert im Befehl sein.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName-Argument
Das ParameterSetName Argument gibt den Parametersatz an, zu dem ein Parameter gehört. Wenn kein Parametersatz angegeben ist, gehört der Parameter zu allen Parametersätzen, die von der Funktion definiert werden. Um eindeutig zu sein, muss jeder Parametersatz mindestens einen Parameter aufweisen, der kein Element eines anderen Parametersatzes ist.
Hinweis
Für ein Cmdlet oder eine Funktion gibt es einen Grenzwert von 32 Parametersätzen.
Im folgenden Beispiel wird 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 mehrere Parametersätze einzuschließen, fügen Sie zusätzliche Parameterattribute hinzu.
Im folgenden Beispiel wird der Parameter "Summary" explizit den Computer Sätzen und User Parametersätzen 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 About Parameter Sets.
ValueFromPipeline-Argument
Das ValueFromPipeline Argument gibt an, dass der Parameter Eingaben aus einem Pipelineobjekt akzeptiert. Geben Sie dieses Argument an, wenn die Funktion das gesamte Objekt akzeptiert, nicht nur eine Eigenschaft des Objekts.
Im folgenden Beispiel wird ein 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 aus einer Eigenschaft eines Pipelineobjekts akzeptiert. Die Objekteigenschaft muss denselben Namen oder Alias wie der Parameter haben.
Wenn die Funktion beispielsweise einen ComputerName-Parameter aufweist und das Piped-Objekt eine ComputerName-Eigenschaft aufweist, wird der Wert der ComputerName-Eigenschaft dem ComputerName-Parameter der Funktion zugewiesen.
Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der obligatorisch ist, und akzeptiert Eingaben aus der ComputerName-Eigenschaft des Objekts, die an die Funktion über die Pipeline übergeben wird.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Erwägen 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'"
}
Dann wäre eine Demonstration der Rohrleitung eines Objekts mit der ComputerName-Eigenschaft :
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Hinweis
Ein typierter 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-Ausführung automatisch ausgeführt. Das Ergebnis ist an den Parameter gebunden. Die Verzögerungsbindung funktioniert nicht für Parameter, die als " 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.
ValueFromRe Standard ingArguments-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 wird ein Wertparameter deklariert, der obligatorisch ist, und einen Re Standard ing-Parameter, der alle an die Funktion übermittelten Parameterwerte für "re Standard" akzeptiert.
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 des zugehörigen 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 wird ein obligatorischer ComputerName-Parameter und eine Hilfemeldung deklariert, die den erwarteten Parameterwert erläutert.
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 Auswirkung auf optionale Parameter.
Alias-Attribut
Das Alias-Attribut stellt einen alternativen Namen für den Parameter her. Es gibt keine Beschränkung für die Anzahl der Aliase, die Sie einem Parameter zuweisen können.
Das folgende Beispiel zeigt eine Parameterdeklaration, die den CN - und MachineName-Aliasen zum obligatorischen ComputerName-Parameter hinzufügt.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Credential-Attribut
Das Attribut "Credential " wird verwendet, um anzugeben, dass der Parameter Anmeldeinformationen akzeptiert. Das folgende Beispiel zeigt eine Parameterdeklaration, die das Attribut "Credential " 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
Der 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. Zum 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
}
Wird verwendet 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. - Value - Der Standardwert des Parameters.
Beide Argumente sind optional. Wenn Sie keine Argumente angeben, wird Get-Help der 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 Attribut "System.Obsolete ", um Parameter zu markieren, die nicht mehr unterstützt werden. Dies kann hilfreich sein, wenn Sie einen Parameter aus einer Funktion entfernen möchten, vorhandene Skripts, die die Funktion verwenden, jedoch nicht unterbrechen möchten.
Betrachten Sie beispielsweise eine Funktion mit einem NoTypeInformation-Switchparameter , 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, die die Änderung erläutert.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
SupportsWild Karte s-Attribut
Das Attribut SupportsWild Karte s wird verwendet, um anzugeben, dass der Parameter wild Karte Werte akzeptiert. Das folgende Beispiel zeigt eine Parameterdeklaration für einen obligatorischen Path-Parameter, der wild Karte Werte unterstützt.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
Die Verwendung dieses Attributs aktiviert nicht automatisch wild Karte Unterstützung. Der Cmdlet-Entwickler muss den Code implementieren, um die Wild Karte Eingabe zu verarbeiten. Die unterstützten Wild Karte können je nach zugrunde liegender API oder PowerShell-Anbieter variieren. Weitere Informationen finden Sie unter about_Wild Karte s.
Argumentabschlussattribute
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 den Tabstoppabschluss benötigt. Das ArgumentCompletions-Attribut ähnelt ValidateSet. Beide Attribute verwenden eine Liste der Werte, die angezeigt werden sollen, wenn der Benutzer die TAB-TASTE hinter 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 den Abschluss der Registerkarte erfordert. Wie dynamische Parameter werden die verfügbaren Werte zur Laufzeit berechnet, wenn der Benutzer die TAB-TASTE hinter dem Parameternamen drückt.
Weitere Informationen finden Sie unter about_Functions_Argument_Completion.
Parameter- und Variablenüberprüfungsattribute
Überprüfungsattribute leiten PowerShell an, um die Parameterwerte zu testen, die Benutzer übermitteln, wenn sie die erweiterte Funktion aufrufen. Wenn die Parameterwerte den Test nicht bestehen, wird ein Fehler generiert, und die Funktion wird nicht aufgerufen. Die Parameterüberprüfung wird nur auf die bereitgestellte Eingabe angewendet, und alle anderen Werte wie Standardwerte werden nicht überprüft.
Sie können auch die Überprüfungsattribute verwenden, um die Werte einzuschränken, die Benutzer für Variablen angeben können.
[AllowNull()] [int]$number = 7
Validierungsattribute können auf jede Variable und nicht nur auf Parameter angewendet werden. Sie können die Überprüfung für eine beliebige Variable innerhalb eines Skripts definieren.
Hinweis
Wenn Sie Attribute mit einer typierten Variable 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 eigene Anweisung behandelt.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Wenn Sie ein Überprüfungsattribut nach einem Typ deklarieren, wird der zugewiesene Wert vor der Typkonvertierung überprüft, was zu unerwarteten Überprüfungsfehlern 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 Validation-Attribut
Mit dem AllowNull-Attribut kann der Wert eines obligatorischen Parameters angegeben werden $null. Im folgenden Beispiel wird ein Hashtable ComputerInfo-Parameter deklariert, der einen Nullwert aufweisen kann.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Hinweis
Das AllowNull-Attribut funktioniert nicht, wenn der Typkonverter auf Zeichenfolge festgelegt ist, da der Zeichenfolgentyp keinen NULL-Wert akzeptiert. Sie können das AllowEmptyString-Attribut für dieses Szenario verwenden.
AllowEmptyString-Überprüfungsattribut
Mit dem AllowEmptyString-Attribut kann der Wert eines obligatorischen Parameters eine leere Zeichenfolge ("") sein. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Zeichenfolgenwert aufweisen kann.
param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]$ComputerName
)
AllowEmptyCollection-Überprüfungsattribut
Mit dem AllowEmptyCollection-Attribut kann der Wert eines obligatorischen Parameters eine leere Auflistung @()sein. Im folgenden Beispiel wird ein ComputerName-Parameter deklariert, der einen leeren Auflistungswert aufweisen kann.
param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]$ComputerName
)
ValidateCount-Überprüfungsattribut
Das ValidateCount-Attribut gibt die minimale und maximale Anzahl von Parameterwerten an, die ein Parameter akzeptiert. PowerShell generiert einen Fehler, wenn sich die Anzahl der Parameterwerte im Befehl, der die Funktion aufruft, außerhalb dieses Bereichs befindet.
Die folgende Parameterdeklaration erstellt einen ComputerName-Parameter , der einen bis fünf Parameterwerte akzeptiert.
param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]$ComputerName
)
ValidateLength-Überprüfungsattribut
Das ValidateLength-Attribut gibt die minimale und maximale Anzahl von Zeichen in einem Parameter oder Variablenwert an. PowerShell generiert einen Fehler, wenn sich die Länge eines für einen Parameter oder eine Variable angegebenen Werts außerhalb des Bereichs befindet.
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 lang und maximal zehn Zeichen lang sein.
[ValidateLength(1,10)] [string] $text = 'valid'
ValidatePattern-Überprüfungsattribute
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 null 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 null bis neun sein.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
ValidateRange-Überprüfungsattribut
Das ValidateRange-Attribut gibt einen numerischen Bereich oder einen ValidateRangeKind-Enumerationswert für jeden Parameter oder Variablenwert an. PowerShell generiert einen Fehler, wenn sich ein beliebiger Wert außerhalb dieses Bereichs befindet.
Die ValidateRangeKind-Enumeration ermöglicht die folgenden Werte:
Positive- Eine Zahl größer als Null.Negative- Eine Zahl kleiner als Null.NonPositive- Eine Zahl kleiner oder gleich Null.NonNegative- Eine Zahl größer oder gleich Null.
Im folgenden Beispiel muss der Wert des Parameters "Attempts " zwischen Null und 0 sein.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]$Attempts
)
Im folgenden Beispiel muss der Wert der Variablen $number zwischen Null und Zehn betragen.
[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-Überprüfungsattribut
Das ValidateScript-Attribut gibt ein Skript an, das zum Überprüfen eines Parameters oder Variablenwerts verwendet wird. PowerShell gibt 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 zu überprüfende Wert der $_ Variablen zugeordnet. Sie können die $_ Variable verwenden, um auf den Wert im Skript zu verweisen.
Im folgenden Beispiel muss der Wert des EventDate-Parameters größer oder gleich dem aktuellen Datum sein.
param(
[Parameter(Mandatory)]
[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 $null Wert an den Parameter übergeben. Wenn Sie einen Nullwert übergeben, kann ValidateScript das Argument nicht überprüfen.
Überschreiben der Standardfehlermeldung
Ab PowerShell 6 können Sie die Standardfehlermeldung außer Kraft setzen, 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 scriptBlock, um den Eingabewert zu überprüfen.
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, meldet die Fehlermeldung, 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 den Abschluss der Registerkarte. PowerShell generiert einen Fehler, wenn ein Parameter oder Variablenwert nicht mit einem Wert im Satz übereinstimmt. Im folgenden Beispiel kann der Wert des Detailparameters 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 Schokolade, Erdbeere oder Vanille sein.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
Die Überprüfung erfolgt immer dann, wenn diese Variable auch innerhalb des Skripts zugewiesen wird. Die folgenden Ergebnisse ergeben z. B. zur Laufzeit einen Fehler:
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
In diesem Beispiel wird der folgende Fehler zur Laufzeit zurückgegeben:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
Aktivieren Sie ValidateSet auch die Registerkartenerweiterung von Werten für diesen Parameter. Weitere Informationen finden Sie unter about_Tab_Expansion.
Dynamische ValidateSet-Werte mit 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 mit dem Namen SoundNames generiert, die drei Dateisystempfade auf verfügbare Audiodateien ü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 Validation-Attribut
Das ValidateNotNull-Attribut gibt an, dass der Parameterwert nicht sein $nullkann. Wenn der Wert lautet $null, löst PowerShell eine Ausnahme aus.
Das ValidateNotNull-Attribut ist so konzipiert, dass er verwendet wird, wenn der Parameter optional ist und der Typ nicht definiert ist oder einen Typkonverter aufweist, der einen Nullwert wie das Objekt nicht implizit konvertieren kann. Wenn Sie einen Typ angeben, der implizit einen Nullwert konvertiert, z. B. eine Zeichenfolge, wird der Nullwert 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-Überprüfungsattribut
Das ValidateNotNullOrEmpty-Attribut gibt an, dass der zugewiesene Wert keines der folgenden Werte sein kann:
$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
)
ValidateNotNullOrWhiteSpace-Validierungsattribut
Das ValidateNotNullOrWhiteSpace-Attribut gibt an, dass der zugewiesene Wert keines der folgenden Werte sein kann:
$null- eine leere Zeichenfolge (
"") - ein leeres Array
@() - eine Zeichenfolge, die nur Leerzeichen enthält, z. B. Tabstopps, Leerzeichen, Wagenrücklauf und Zeilenumbruch
- ein Array, das alle Zeichenfolgen enthält, die leer sind oder nur Leerzeichen enthalten
Wenn der Wert ungültig ist, löst PowerShell eine Ausnahme aus.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[string[]]$UserName
)
ValidateDrive-Überprüfungsattribute
Das ValidateDrive-Attribut gibt an, dass der Parameterwert den Pfad darstellen muss, der nur auf zulässige Laufwerke verweist. PowerShell generiert einen Fehler, wenn sich der Parameterwert auf andere Laufwerke als die zulä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 der zulässigen Laufwerke befinden.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
ValidateUserDrive-Überprüfungsattribut
Das ValidateUserDrive-Attribut gibt an, dass der Parameterwert im User Laufwerk dargestellt werden muss. PowerShell generiert einen Fehler, wenn sich der Pfad auf ein anderes Laufwerk bezieht. Das Überprüfungsattribut testet nur auf das Vorhandensein des Laufwerkpräfixes des Pfads.
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 Just Enough Administration (JEA)-Sitzungskonfigurationen definieren User . In diesem Beispiel wird das Laufwerk "User:" erstellt.
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-Überprüfungsattribut
Dieses Attribut wurde in PowerShell 6.1.1 hinzugefügt.
Zu diesem Zeitpunkt wird das Attribut intern von PowerShell selbst verwendet und ist nicht für die externe Verwendung vorgesehen.
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für