about_Functions_Advanced_Parameters

Kurzbeschreibung

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.

Wenn Sie das attribut CmdletBinding verwenden, fügt PowerShell automatisch die allgemeinen Parameter hinzu. Sie können keine Parameter erstellen, die dieselben Namen wie die allgemeinen Parameter verwenden. Weitere Informationen 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.

Parameterdeklaration

Parameter sind Variablen, die in der param() Anweisung einer Funktion oder eines Skriptblocks deklariert werden. Sie können das optionale [Parameter()]-Attribut allein oder in Kombination mit dem attribut [Alias()] oder einem der Parameterüberprüfungsattribute verwenden.

Parameternamen folgen den Regeln für Variablennamen. Parameternamen bestehen aus Dezimalziffern, alphabetischen Zeichen und Unterstrichen. Eine vollständige Liste der Benennungsregeln finden Sie unter about_Variables.

Betrachten Sie das folgende Beispiel:

function TestFunction {
    param (
        [switch] $100,
        [string] $200
    )

    "100: $100"
    "200: $200"
}

Wenn Sie versuchen, die Parameter zu verwenden, interpretiert PowerShell sie als positionaler Parameter übergebene Zeichenfolgen.

PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello

Die Ausgabe zeigt, dass PowerShell den Wert -100 an die $200 Parametervariable gebunden hat. Die verbleibenden Positionswerte sind an $argsgebunden. Um das Problem zu umgehen, können Sie mithilfe von Splatting die Parameterwerte übergeben.

PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:

Weitere Informationen finden Sie unter 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."

Weitere Informationen finden Sie unter about_Type_Conversion.

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
)

Parameter wechseln

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, einen true Wert und wenn er nicht vorhanden ist, einen false Wert aufweist.

Beispielsweise ist der Recurse Parameter von Get-ChildItem ein Schalterparameter.

Um einen Switchparameter in einer Funktion zu erstellen, geben Sie den [switch] Typ in der Parameterdefinition an. Das folgende Beispiel zeigt die Definition eines Switchparameters, mit dem eine Option zum Ausgeben von Daten als Bytearray bereitgestellt werden kann:

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.

Um einen Switch-Parameter zu verwenden, schließen Sie den Parameter in den Befehl ein. Zum Beispiel:

-IncludeAll

Um einen booleschen Parameter zu verwenden, müssen Sie den Parameter und einen booleschen Wert angeben.

-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 maximal zulässige, die einen Wert bedeuten könnten.

Überlegungen zum Wechseln des Parameterentwurfs

• Legen Sie keinen Standardwert für einen Switch-Parameter fest. Switch-Parameter ist immer auf "false" festgelegt.

• Stellen Sie keine Schalterparameter positional fest. Switch-Parameter werden standardmäßig von Positionsparametern ausgeschlossen. Sie können dies im attribut Parameter außer Kraft setzen, die Benutzer jedoch verwirren.

• Entwurfsschalterparameter, sodass die Verwendung des Parameters das Standardverhalten des Befehls in einen weniger gängigen oder komplizierteren Modus ändert. Das einfachste Verhalten eines Befehls sollte das Standardverhalten sein, das die Verwendung von Switchparametern nicht erfordert.

• Stellen Sie keine Parameter für Die Option obligatorisch fest. Der einzige Fall, in dem es hilfreich ist, einen Switch-Parameter obligatorisch zu machen, ist, wenn es erforderlich ist, einen Parametersatz zu unterscheiden.

• Verwenden Sie die Switch-Parametervariable direkt in einem bedingten Ausdruck. Der SwitchParameter Typ wird implizit in boolean konvertiert. Zum Beispiel:

  if ($MySwitch) { ... }
  

• Basieren Sie immer auf dem Vom Schalter gesteuerten Verhalten auf dem Wert des Schalters, nicht auf das Vorhandensein des Parameters. Es gibt mehrere Möglichkeiten zum Testen des Vorhandenseins eines Switchparameters:

  • $PSBoundParameters enthält den Namen des Switchparameters als Schlüssel.
  • $MyInvocation.BoundParameters enthält den Namen des Switchparameters als Schlüssel.
  • $PSCmdlet.ParameterSetName, wenn der Switch einen eindeutigen Parametersatz definiert

  Beispielsweise ist es möglich, einen expliziten Wert für den Schalter mithilfe von -MySwitch:$false oder Splatting bereitzustellen. Wenn Sie nur testen, ob der Parameter vorhanden ist, verhält sich der Befehl so, als ob der Schalterwert anstelle von $true$false ist.

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. Beispielsweise ist der parameter Encoding für die Add-Content, Get-Contentund Set-Content Cmdlets 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 parameter ArgumentList des Cmdlets Get-Command verwenden oder den parameter Path von Get-Helpverwenden.

Verwenden Sie das schlüsselwort dynamicparam, 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 Pathsowie einen optionalen dynamischen Parameter namens KeyCount. Der parameter KeyCount befindet sich im ByRegistryPath Parametersatz und weist einen Typ von Int32auf. Der KeyCount-Parameter ist nur in der Get-Sample Funktion verfügbar, wenn der Wert des Path-Parameters mit HKLM:beginnt und 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 attribut CmdletBinding weglassen, muss die Funktion das attribut Parameter 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.

Parameter-Attribut

Das attribut Parameter wird verwendet, um die Attribute von Funktionsparametern zu deklarieren.

Das Parameter--Attributs 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 das attribut CmdletBinding Attribut oder das attribut Parameter oder beides aufweisen.

Das attribut Parameter 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 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 attributs Parameter zu deklarieren.

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

Die booleschen Argumenttypen des attributs Parameter Attribut standardmäßig auf False, wenn sie aus dem attribut Parameter weggelassen werden. Legen Sie den Argumentwert auf $true fest, oder listen Sie das Argument einfach anhand des Namens auf. Beispielsweise sind die folgenden Parameter- Attribute gleichwertig.

param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

Wenn Sie das attribut Parameter ohne Argumente verwenden, sind die Klammern, die dem Attributnamen folgen, weiterhin erforderlich, um das attribut CmdletBinding Attribut zu verwenden.

param(
    [Parameter()]
    $ParameterName
)

Obligatorisches Argument

Das argument Mandatory gibt an, dass der Parameter erforderlich ist. Wenn dieses Argument nicht angegeben ist, ist der Parameter optional.

Im folgenden Beispiel wird der parameter ComputerName deklariert. Es verwendet das argument Mandatory, um den Parameter obligatorisch zu machen.

param(
    [Parameter(Mandatory)]
    [string[]]$ComputerName
)

Position-Argument

Das argument Position bestimmt, ob der Parametername erforderlich ist, wenn der Parameter in einem Befehl verwendet wird. Wenn eine Parameterdeklaration das argument Position 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 argument Position 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 arguments PositionalBinding des CmdletBinding- attributs auf $falsefest. Das argument Position hat Vorrang vor dem Wert des PositionalBinding Arguments des attributs CmdletBinding. Weitere Informationen finden Sie unter PositionalBinding in about_Functions_CmdletBindingAttribute.

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

Wenn eine Funktion 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 argument Position.

Im folgenden Beispiel wird der parameter ComputerName deklariert. Es verwendet das argument Position mit dem Wert 0. Wenn -ComputerName 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 argument ParameterSetName 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.

Im folgenden Beispiel wird ein ComputerName Parameter im Computer Parametersatz deklariert, ein UserName Parameter im User Parametersatz und ein Summary Parameter in beiden Parametersätzen.

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 Parameter Attribute hinzu.

Im folgenden Beispiel wird der Parameter Summary Computer und User Parametersätzen explizit hinzugefügt. Der parameter "Summary" 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 argument ValueFromPipeline 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 argument ValueFromPipelineByPropertyName 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 über einen ComputerName-Parameter verfügt und das weitergeleitete Objekt eine ComputerName-Eigenschaft aufweist, wird der Wert der eigenschaft ComputerName 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'

ValueFromRemainingArguments-Argument

Das argument ValueFromRemainingArguments 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 Value Parameter deklariert, der obligatorisch ist, und einen Remaining-Parameter, der alle verbleibenden Parameterwerte akzeptiert, die an die Funktion übermittelt werden.

function Test-Remainder {
    param(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(ValueFromRemainingArguments, Position=1)]
        [string[]]$Remaining
    )

    "Value = $Value"
    "Found $($Remaining.Count) remaining values"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}

PS> Test-Remainder first one two three

Value = first
Found 3 remaining values
0: one
1: two
2: three

Ab PowerShell 6.2 werden Sammlungen anders behandelt, wenn sie an ValueFromRemainingArguments übergeben werden. Wenn Sie nur eine Auflistung übergeben, wird jeder Wert in der Auflistung als separates Element behandelt.

PS> Test-Remainder first one, two, three

Value = first
Found 3 remaining values
0: one
1: two
2: three

Wenn Sie mehrere Werte übergeben, bei denen mindestens eine Sammlung nicht ist, wird die Auflistung als einzelnes Element behandelt.

PS> Test-Remainder first one, two three four

Value = first
Found 3 remaining values
0: one two
1: three
2: four

HelpMessage-Argument

Das argument HelpMessage 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 EINGABETASTE.

Im folgenden Beispiel wird 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 Auswirkung auf optionale Parameter.

DontShow-Argument

Der DontShow-Wert wird in der Regel verwendet, um die Abwärtskompatibilität für einen Befehl zu unterstützen, bei dem ein veralteter Parameter nicht entfernt werden kann. Wenn sie DontShow auf True festlegen, wird der Parameter für die Registerkartenerweiterung und IntelliSense vom Benutzer ausgeblendet.

PowerShell v7 (und höher) verwendet DontShow, um die folgenden veralteten Parameter auszublenden:

• Der NoTypeInformation Parameter von ConvertTo-Csv und Export-Csv
• Der parameter Raw von Format-Hex
• Der UseBasicParsing Parameter von Invoke-RestMethod und Invoke-WebRequest

Das argument DontShow hat die folgenden Nebenwirkungen:

• Betrifft alle Parametersätze für den zugeordneten Parameter, auch wenn ein Parametersatz vorhanden ist, in dem DontShow nicht verwendet wird.
• Blendet allgemeine Parameter aus dem Abschluss der Registerkarte und IntelliSense aus. DontShow blendet die optionalen allgemeinen Parameter nicht aus: WhatIf, Confirmoder UseTransaction.

Alias-Attribut

Das attribut Alias richtet einen alternativen Namen für den Parameter ein. 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 die CN- und MachineName Aliase 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.The following example shows a parameter declaration that uses the Credential attribute.

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Experimental-Attribut

Verwenden Sie das Attribut Experimental, um Code als experimentell zu deklarieren. Eine vollständige Beschreibung des Attributs finden Sie unter about_Experimental_Features.

PSDefaultValue-Attribut

Die PSDefaultValue gibt den Standardwert eines Befehlsparameters in einem Skript an. Diese Informationen werden vom Cmdlet Get-Help 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
}

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 attribut PSDefaultValue weist zwei Argumente auf:

• Hilfe- – Eine Zeichenfolge, die den Standardwert beschreibt. Diese Informationen werden vom Cmdlet Get-Help angezeigt.
• Value - Der Standardwert des Parameters.

Beide Argumente sind optional. Wenn Sie keine Argumente angeben, zeigt Get-Help den dem Parameter zugewiesenen Wert an.

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 Cmdlet Test-Connection einen erweiterten Typ zurück. Sie können das attribut PSTypeName verwenden, um den Typ des Parameters auf den erweiterten Typ zu beschrä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 zum Markieren von Parametern, 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 z. B. 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
)

SupportsWildcards-Attribut

Das SupportsWildcards- Attributs 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
)

Durch die Verwendung dieses Attributs wird die Unterstützung von Wildcards nicht automatisch aktiviert. Der Cmdlet-Entwickler 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.

Argumentabschlussattribute

ArgumentCompletions-Attribut

Mit dem ArgumentCompletions Attributs können Sie einem bestimmten Parameter Tabstopp-Vervollständigungswerte hinzufügen. Ein ArgumentCompletions Attributs muss für jeden Parameter definiert werden, der den Tabstoppabschluss benötigt. Das attribut ArgumentCompletions ähnelt ValidateSet. Beide Attribute verwenden eine Liste von Werten, die angezeigt werden sollen, wenn der Benutzer nach dem Parameternamen TAB- drückt. Im Gegensatz zu ValidateSetwerden 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 Tabstoppabschluss erfordert. Wie dynamischen Parameterwerden die verfügbaren Werte zur Laufzeit berechnet, wenn der Benutzer nach dem Parameternamen TAB- 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.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

[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

Das attribut AllowNull ermöglicht die $nulldes Werts eines obligatorischen Parameters. Im folgenden Beispiel wird eine Hashtabelle ComputerInfo Parameter deklariert, der einen null--Wert aufweisen kann.

param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]$ComputerInfo
)

AllowEmptyString-Überprüfungsattribut

Das AllowEmptyString--Attribut ermöglicht dem Wert eines obligatorischen Parameters eine leere Zeichenfolge (""). Im folgenden Beispiel wird ein ComputerName Parameter deklariert, der einen leeren Zeichenfolgenwert aufweisen kann.

param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]$ComputerName
)

AllowEmptyCollection-Überprüfungsattribut

Das attribut AllowEmptyCollection ermöglicht es dem Wert eines obligatorischen Parameters, eine leere Auflistung @()zu 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 attribut ValidateCount 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 attribut ValidateLength 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 attribut ValidatePattern 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 attribut ValidateRange 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 0.
• Negative – Eine Zahl kleiner als 0.
• NonPositive - Eine Zahl kleiner oder gleich Null.
• NonNegative - Eine Zahl größer oder gleich Null.

Im folgenden Beispiel muss der Wert der Attempts Parameter 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 Null sein.

[ValidateRange("Positive")] [int]$number = 1

ValidateScript-Überprüfungsattribut

Das attribut ValidateScript 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 $false zurückgibt oder wenn das Skript eine Ausnahme auslöst.

Wenn Sie das attribut ValidateScript 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 parameters EventDate 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)

Überschreiben der Standardfehlermeldung

Ab PowerShell 6 können Sie die standardfehlermeldung außer Kraft setzen, die generiert wird, wenn ein angegebener Wert mit dem argument ErrorMessage ungültig ist. Geben Sie eine zusammengesetzte Formatzeichenfolgean. Die 0 Indexkomponente verwendet den Eingabewert. Die 1 Indexkomponente verwendet die ScriptBlock- verwendet, 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 Formatzeichenfolgenkomponentenanwenden.

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 attribut ValidateSet 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 parameters Detail nur "Low", "Average" oder "High" 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.

Wenn Sie ValidateSet auch die Registerkartenerweiterung von Werten für diesen Parameter aktivieren. Weitere Informationen finden Sie unter about_Tab_Expansion.

Dynamische ValidateSet-Werte mit Klassen

Sie können eine class 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 einen class namens SoundNames generiert, der 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
)

ValidateNotNull Validation-Attribut

Das attribut ValidateNotNull gibt an, dass der Parameterwert nicht $nullwerden kann. Wenn der Wert $nullist, löst PowerShell eine Ausnahme aus.

Das attribut ValidateNotNull ist so konzipiert, dass er verwendet wird, wenn der Parameter optional ist und der Typ nicht definiert ist oder über einen Typkonverter verfügt, der einen Nullwert wie Objektnicht 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 attribut ValidateNotNullOrEmpty.

Im folgenden Beispiel kann der Wert des parameters ID nicht $nullwerden.

param(
    [Parameter()]
    [ValidateNotNull()]
    $Id
)

ValidateNotNullOrEmpty-Überprüfungsattribut

Das attribut ValidateNotNullOrEmpty 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 attribut ValidateNotNullOrWhiteSpace 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 attribut ValidateDrive 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 attribut ValidateUserDrive 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 Usersein.

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 User Laufwerk in Just Enough Administration (JEA)-Sitzungskonfigurationen definieren. 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 wird intern von PowerShell selbst verwendet und ist nicht für die externe Verwendung vorgesehen.

Dieses Attribut wurde in PowerShell 6.1.1 hinzugefügt.

Siehe auch

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute