about_Functions_Advanced_Parameters

应用到: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

主题

在此处插入分区正文。

简短说明

说明如何向高级函数添加形参。

详细说明

你可以向你编写的高级函数添加形参，并使用形参属性和实参限制函数用户与该形参一起提交的形参值。

除了 Windows PowerShell® 自动添加到所有 cmdlet 和高级函数的常用形参，也会想用户提供你添加到函数的形参。有关 Windows PowerShell 常用形参的详细信息，请参阅 about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216)。

从 Windows PowerShell 3.0 开始，你可以使用带有 @Args 的展开表示命令中的形参。此技术对简单和高级函数有效。有关详细信息，请参阅 about_Functions (https://go.microsoft.com/fwlink/?LinkID=113231) 和 about_Splatting (https://go.microsoft.com/fwlink/?LinkID=262720)。

静态形参

静态形参是始终在函数中可用的形参。Windows PowerShell cmdlet 和脚本中的大部分形参是静态形参。

以下示例显示具有以下特征的 ComputerName 形参的声明：

它是强制的（必需的）。

它采用来自管道的输入。

它采用字符串的数组作为输入。

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

形参的属性

本部分介绍可添加到函数形参的属性。

所有属性都是可选的。但是，如果你省略 CmdletBinding 属性，那么若要识别为高级函数，该函数必须包含 Parameter 属性。

你可以在每个形参声明中添加一个或多个属性。对你可添加到形参声明的属性数量没有限制。

Parameter 属性

Parameter 属性用于声明函数形参的属性。

Parameter 属性是可选的，并且如果你的函数的形参都不需要属性，你可以省略它，但是若要识别为高级函数（而不是简单函数），函数必须具有 CmdletBinding 属性或 Parameter 属性或两者皆有。

Parameter 属性具有定义参数特征的实参，例如形参是强制的还是可选的。

使用以下语法声明 Parameter 属性、实参和实参值。括起该实参及其值的括号必须跟在“Parameter”后面，并且中间没有空格。

        Param
          (
            [parameter(Argument=value)]
            $ParameterName
          )

使用逗号来分隔括号内的实参。使用以下语法声明 Parameter 属性的两个实参。

        Param
          (
            [parameter(Argument1=value1,
                       Argument2=value2)]

          )

如果你使用不带有实参的 Parameter 属性（作为使用 CmdletBinding 属性的替代方法），则仍然需要跟在该属性名称后的括号。

        Param
          (
            [parameter()]
            $ParameterName
          )

Mandatory 实参

Mandatory 实参指示形参是必需的。如果未指定实参，则该形参是可选形参。

以下示例声明 ComputerName 形参。它使用 Mandatory 实参使形参成为强制形参。

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          )

Position 实参

Position 实参确定在命令中使用形参时形参名称是否是必需的。当形参声明包含 Position 实参时，可以省略形参名称，并且 Windows PowerShell 在命令中的未命名形参值列表中通过其位置（或顺序）来标识未命名的形参值。

如果未指定 Position 实参，则每当在命令中使用形参时，形参名称（或形参名称别名或缩写）必须在形参值之前。

默认情况下，所有函数形参都是位置形参。Windows PowerShell 以形参在函数中声明的顺序将位置编号分配到形参。若要禁用此功能，请将 CmdletBinding 属性的 PositionalBinding 实参的值设置为 $False。Position 实参优先于声明它的形参的 PositionalBinding 实参值。有关详细信息，请参阅 about_Functions_CmdletBindingAttribute 中的 PositionalBinding。

Position 实参的值指定为整数。位置值为 0 表示命令中的第一个位置，位置值为 1 表示命令中的第二个位置，依此类推。

如果函数没有位置形参，则 Windows PowerShell 根据声明这些形参的顺序将位置分配给每个形参。但是，作为最佳实践，请不要依赖此分配。当你希望形参成为位置形参时，请使用 Position 实参。

以下示例声明 ComputerName 形参。它使用值为 0 的 Position 实参。因此，当从命令中省略“-ComputerName”时，其值必须是命令中的第一个或唯一未命名的形参值。

        Param
          (
            [parameter(Position=0)]
            [String[]]
            $ComputerName
          )

注意：

当 Get-Help cmdlet 显示相应的“Position?”形参属性时，位置值递增 1。例如，Position 实参值为 0 的形参具有形参属性“Position?1."

ParameterSetName 实参

ParameterSetName 实参指定形参所属的形参集。如果未指定任何形参集，则该形参属于由函数定义的所有形参集。因此，若要成为唯一，每个形参集都必须具有至少一个不属于任何其他形参集的形参。

以下示例声明 Computer 形参集中的 ComputerName 形参、User 形参集中的 UserName 形参和这两个形参集中的 Summary 形参。

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false)]
            [Switch]
            $Summary
          )

你只能在每个实参中指定一个 ParameterSetName 值，并且只能在每个 Parameter 属性中指定一个 ParameterSetName 实参。若要指示形参显示在多个形参集中，请添加其他 Parameter 属性。

以下示例将 Summary 形参明确添加到 Computer 和 User 形参集。Summary 形参在一个形参集中是强制的，在另一个形参集中是可选的。

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false, ParameterSetName="Computer")]
            [parameter(Mandatory=$true, ParameterSetName="User")]
            [Switch]
            $Summary
          )
        

有关形参集的详细信息，请参阅位于 MSDN 库中的“Cmdlet 形参集”，网址为 https://go.microsoft.com/fwlink/?LinkId=142183。

ValueFromPipeline 实参

ValueFromPipeline 实参指示形参接受管道对象中的输入。如果函数接受整个对象而不只是该对象的一个属性，则指定此实参。

以下示例声明强制性的 ComputerName 形参，并接受从管道传递到函数的对象。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

ValueFromPipelineByPropertyName 实参

valueFromPipelineByPropertyName 实参指示形参接受来自管道对象的属性的输入。对象属性必须具有与该形参相同的名称或别名。

例如，如果函数具有 ComputerName 形参并且管道对象具有 ComputerName 属性，则 ComputerName 属性的值将分配给该函数的 ComputerName 形参。

以下示例声明强制性的 ComputerName 形参，并接受来自通过管道传递给函数的对象的 ComputerName 属性的输入。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)]
            [String[]]
            $ComputerName
          )

ValueFromRemainingArguments 实参

ValueFromRemainingArguments 实参指示形参接受命令中未分配给函数的其他形参的所有形参值。

以下示例声明强制性的 ComputerName 形参，并接受已提交到函数的所有剩余形参值。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)]
            [String[]]
            $ComputerName
          )

HelpMessage 实参

HelpMessage 实参指定包含形参或其值的简短说明的字符串。Windows PowerShell 在提示中显示此消息，该提示在强制形参值从命令中丢失时显示。此实参对可选形参没影响。

以下示例声明强制 ComputerName 形参和说明预期形参值的帮助消息。

        Param
          (
            [parameter(mandatory=$true,
                       HelpMessage="Enter one or more computer names separated by commas.")]
            [String[]]
            $ComputerName
          )

ALIAS 属性

Alias 属性为形参建立备用名称。对可分配给形参的别名数量没有限制。

以下示例显示将“CN”和“MachineName”别名添加到强制 ComputerName 形参的形参声明。

        Param
          (
            [parameter(Mandatory=$true)]
            [alias("CN","MachineName")]
            [String[]]
            $ComputerName
          )

PARAMETER 和 VARIABLE 验证属性

验证属性指示 Windows PowerShell 测试用户在调用高级函数时提交的形参值。如果形参值未通过测试，将生成错误，并且不调用该函数。你还可使用一些验证属性限制用户可为变量指定的值。

AllowNull 验证属性

AllowNull 属性允许强制形参的值为 null ($null)。以下示例声明可具有 Null 值的 ComputerName 形参。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowNull()]
            [String]
            $ComputerName
          )

AllowEmptyString 验证属性

AllowEmptyString 属性允许强制形参的值为空字符串 ("")。以下示例声明可具有一个空字符串值的 ComputerName 形参。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyString()]
            [String]
            $ComputerName
          )

AllowEmptyCollection 验证属性

AllowEmptyCollection 属性允许强制形参的值为空集合 (@())。以下示例声明可具有空集合值的 ComputerName 形参。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyCollection()]
            [String[]]
            $ComputerName
          )

ValidateCount 验证属性

ValidateCount 属性指定形参可接受的最小和最大形参值。如果调用函数的命令中的形参值数量在该范围之外，则 Windows PowerShell 将生成错误。

以下示例声明创建采用 1 到 5 的形参值的 ComputerName 形参。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateCount(1,5)]
            [String[]]
            $ComputerName
          )

ValidateLength 验证属性

ValidateLength 属性指定形参或变量值中的最小和最大字符数。如果为形参或变量指定的值的长度在该范围之外，则 Windows PowerShell 将生成错误。

在以下示例中，每个计算机名称都必须具有 1 到 10 个字符。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateLength(1,10)]
            [String[]]
            $ComputerName
          )

在以下示例中，变量 $number 的值的长度最小必须为 1 个字符，最大必须为 10 个字符。

        [Int32][ValidateLength(1,10)]$number = 01

ValidatePattern 验证属性

ValidatePattern 属性指定与形参或变量值比较的正则表达式。如果该值不与正则表达式模式匹配，则 Windows PowerShell 将生成错误。

在以下示例中，形参值必须是一个四位数，并且每一位都必须是 0 到 9 的数字。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            [String[]]
            $ComputerName
          )

在以下示例中，变量 $number 的值必须是一个四位数，并且每一位都必须是 0 到 9 的数字。

        [Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111

ValidateRange 验证属性

ValidateRange 属性为每个形参或变量值指定数值范围。如果任何值在该范围之外，则 Windows PowerShell 将生成错误。在以下示例中，Attempts 形参的值必须在 0 和 10 之间。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateRange(0,10)]
            [Int]
            $Attempts
          )

在以下示例中，变量 $number 的值必须在 0 和 10 之间。

        [Int32][ValidateRange(0,10)]$number = 5

ValidateScript 验证属性

ValidateScript 属性指定用于验证形参或变量值的脚本。Windows PowerShell 将值通过管道传送到脚本，如果该脚本返回“false”或引发异常，则将生成错误。

当你使用 ValidateScript 属性时，要验证的值将映射到 $_ 变量。你可以使用 $_ 变量引用脚本中的值。

在以下示例中，EventDate 形参的值必须大于或等于当前日期。

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

在以下示例中，变量 $date 的值必须大于或等于当前日期和时间。

       [DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)

ValidateSet 属性

ValidateSet 属性为形参或变量指定一组有效的值。如果形参或变量值与集中的值不匹配，则 Windows PowerShell 将生成错误。在以下示例中，Detail 形参的值只能为“Low”、“Average”或“High”。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateSet("Low", "Average", "High")]
            [String[]]
            $Detail
          )

在以下示例中，变量 $flavor 的值必须为 Chocolate、Strawberry 或 Vanilla。

        [String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry

ValidateNotNull 验证属性

ValidateNotNull 属性指定形参值无法为 null ($null)。如果形参值为 null，则 Windows PowerShell 将生成错误。

ValidateNotNull 属性设计用于未指定形参值类型或指定类型将接受 Null 值的情况。（如果你指定一个不会接受 null 值的类型（例如字符串），则将在没有 ValidateNotNull 属性的情况下拒绝 null 值，因为它与指定类型不匹配。）

在以下示例中，ID 形参的值不能为 null。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNull()]
            $ID
          )

ValidateNotNullOrEmpty 验证属性

ValidateNotNullOrEmpty 属性指定形参值不能为 null ($null) 并且不能为空字符串 ("")。如果在函数调用中使用该形参，但其值为 null、空字符串或空数组，则 Windows PowerShell 将生成错误。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNullOrEmpty()]
            [String[]]
            $UserName
          )

动态参数

动态形参是仅在特定条件下可用的 cmdlet、函数或脚本的形参。

例如，多个提供程序 cmdlet 具有仅在提供程序驱动器或提供程序驱动器的特定路径中使用该 cmdlet 时可用的参数。例如，仅当在文件系统驱动器中使用时，Encoding 形参才可用于 Add-Content、Get-Content 和 Set-Content cmdlet。

你还可以创建一个形参，该形参仅在函数命令中使用其他形参或其他形参具有特定值时显示。

动态形参可能非常有用，但仅在必要时使用它们，因为它们可能难以让用户发现。若要查找动态形参，用户必须在提供程序路径中，使用 Get-Command cmdlet 的 ArgumentList 形参，或使用 Get-Help 的 Path 形参。

若要为函数或脚本创建动态形参，请使用 DynamicParam 关键字。

语法如下所示：

      DynamicParam {<statement-list>}

在语句列表中，使用 If 语句指定形参在函数中可用的条件。

使用 New-Object cmdlet 创建 System.Management.Automation.RuntimeDefinedParameter 对象以表示该形参并指定其名称。

你还可以使用 New-Object 命令创建 System.Management.Automation.ParameterAttribute 对象以表示形参的属性，例如 Mandatory、Position 或 ValueFromPipeline 或其形参集。

以下示例显示带有名为 Name 和 Path 的标准形参和名为 DP1 的可选动态形参的示例函数。DP1 形参在 PSet1 形参集中，并且类型为 Int32。仅当 Path 形参的值包含“HKLM:”（指示正在 HKEY_LOCAL_MACHINE 注册表驱动器中使用它）时，DP1 形参才在 Sample 函数中可用。

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $attributes.Mandatory = $false
                $attributeCollection = new-object `
                    -Type System.Collections.ObjectModel.Collection[System.Attribute]
                $attributeCollection.Add($attributes)

                $dynParam1 = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
            
                $paramDictionary = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameterDictionary
                $paramDictionary.Add("dp1", $dynParam1)
                return $paramDictionary
            }
        }
    }

有关详细信息，请参阅 MSDN (Microsoft Developer Network) 库中的“RuntimeDefinedParameter 类”，网址为 https://go.microsoft.com/fwlink/?LinkID=145130。

Switch 形参

Switch 形参是不带有形参值的形参。它们仅在使用时有效，并且只有一个效果。

例如，PowerShell.exe 的 -NoProfile 形参是 Switch 形参。

若要在函数中创建 Switch 形参，请在形参定义中指定 Switch 类型。

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

Switch 形参易于使用，并且优先于 Boolean 形参，后者具有更复杂的语法。

例如，若要使用 Switch 形参，用户需在命令中键入该形参。

        -IncludeAll

若要使用 Boolean 形参，用户需键入该形参和布尔值。

        -IncludeAll:$true

在创建 Switch 形参时，请谨慎选择形参名称。请确保形参名称可向用户指明该形参的效果，并避免可能暗示某个值为必需值的模糊术语（例如筛选或最大）。

另请参阅

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute