about_Functions_Advanced_Parameters

主题
    about_Functions_Advanced_Parameters

简短说明
    说明如何向声明了 CmdletBinding 属性的函数添加静态或动态参数。

详细说明
    您可以在编写函数时声明自己的参数，并且可以使编写的函数能够访问可用于已编译 cmdlet 的通用
    参数。有关 Windows PowerShell 通用参数的详细信息，请参阅 about_CommonParameters。


静态参数
    以下示例显示了定义 ComputerName 参数的参数声明。此参数具有以下特征：

        - 它是必需的。
        - 它接受管道输入。
        - 它接受字符串数组输入。

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

    Parameter 属性是声明参数时的唯一一个必需属性。不过，您也可以声明 Alias 属性和几个验证参
    数。可添加到参数声明的属性数目没有限制。


  Parameter 属性

      Parameter 属性用于声明函数的参数。
      此属性具有以下用于定义形式参数特征（如形式参数是必需的还是可选的）的命名实际参数。


    必需命名参数

        必需实际参数表示在函数运行时形式参数是必需的。如果未指定此实际参数，则形式参数是可选的。
        以下示例显示了在函数运行时必需的参数的声明。

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


    位置命名参数

        位置实际参数指定形式参数的位置。如果未指定此实际参数，则在设置形式参数时必须明确指定
        该形式参数的名称或别名。此外，如果函数中的所有参数都没有指定位置，则 Windows PowerShell 运行时
        会按收到这些参数的顺序为每个参数分配位置。

        以下示例显示了一个形式参数的声明，在运行 cmdlet 时必须将该形式参数的值指定为第一个实
        际参数。请注意，无论是否指定参数名称，都可以运行此函数。

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


    ParameterSetName 命名参数

        ParameterSetName 实际参数指定形式参数所属的形式参数集。如果未指定参数集，则参数属于
        函数定义的所有参数集。此行为意味着每个参数集必须有一个不属于任何其他参数集的唯一参数。
        以下示例显示了属于两个不同参数集的两个参数的参数声明。

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

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

        有关参数集的详细信息，请参阅 MSDN Library 中的"Cmdlet 参数集"，网址为 
        https://go.microsoft.com/fwlink/?LinkId=142183。


    ValueFromPipeline 命名参数

        ValueFromPipeline 实际参数指定形式参数通过管道对象接受输入。如果 cmdlet 访问完整
        对象，而不仅仅是对象的属性，则应指定此参数。以下示例显示了一个必需参数 ComputerName 
        的参数声明，该参数接受通过管道传递给函数的输入对象。

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


    ValueFromPipelineByPropertyName 命名参数

        valueFromPipelineByPropertyName 实际参数指定形式参数通过管道对象的属性接受输入。
        在满足以下条件时，应指定此属性：

            - 参数访问通过管道传递的对象的属性。

            - 属性与参数具有相同的名称或别名。

        例如，如果函数具有 ComputerName 参数，并且通过管道传递的对象具有 ComputerName 属
        性，则将 ComputerName 属性的值赋予函数的 ComputerName 参数。

        以下示例显示了 ComputerName 参数的参数声明，该参数通过传递给 cmdlet 的输入对象的 
        ComputerName 属性接受输入。

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


    ValueFromRemainingArguments 命名参数

        ValueFromRemainingArguments 实际参数指定形式参数接受未绑定到函数形式参数的其余所
        有实际参数。以下示例显示了 ComputerName 形式参数的参数声明，该形式参数接受传递给函数
        的输入对象的其余所有实际参数。

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


    HelpMessage 命名参数

        HelpMessage 实际参数指定包含对形式参数的简短说明的消息。以下示例显示了提供参数说明的参
        数声明。

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage="An array of computer names.")] 
                      [String[]]
            $ComputerName
          ) 


  Alias 属性

      Alias 属性为参数指定另一个名称。可分配给参数的别名数目没有限制。以下示例显示了将别名
      "CN"添加到 ComputerName 参数的必需参数声明。

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


  参数验证属性

      这些属性定义 Windows PowerShell 运行时如何验证高级函数的参数。


    AllowNull 验证属性

        AllowNull 属性允许将 cmdlet 必需形式参数的实际参数设置为 Null。在以下示例中，
        ComputerName 参数可包含 Null 值，即使此参数是必需参数也如此。

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


    AllowEmptyString 验证属性

        AllowEmptyString 属性允许将空字符串作为 cmdlet 必需形式参数的实际参数。在以下示例
        中，ComputerName 参数可以包含空字符串 ("")，即使此参数是必需参数也如此。

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


    AllowEmptyCollection 验证属性

        AllowEmptyCollection 属性允许将空集合作为必需形式参数的实际参数。

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


    ValidateCount 验证属性

        ValidateCount 属性指定形式参数可接受的实际参数的最小和最大数目。如果实际参数的数目
        超出该范围，则 Windows PowerShell 运行时会生成错误。在以下示例中，ComputerName 形
        式参数可具有一到五个实际参数。

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


    ValidateLength 验证属性

        ValidateLength 属性指定形式参数的实际参数的最小和最大长度。如果形式参数的实际参数的
        长度超出该范围，则 Windows PowerShell 运行时会生成错误。在以下示例中，指定的计算机
        名称必须包含 1 到 10 个字符。

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


    ValidatePattern 验证属性

        ValidatePattern 属性指定对形式参数的实际参数模式进行验证的正则表达式。如果形式参数
        的实际参数与此模式不匹配，则 Windows PowerShell 运行时会生成错误。在以下示例中，形式
        参数的实际参数必须是一个四位数，并且每一位必须是 0 到 9 中的一个数字。

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


    ValidateRange 验证属性

        ValidateRange 属性指定形式参数的实际参数的最小值和最大值。如果形式参数的实际参数超
        出该范围，则 Windows PowerShell 运行时会生成错误。在以下示例中，形式参数的实际参数不
        能小于 0 也不能大于 10。


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


    ValidateScript 验证属性

        ValidateScript 属性指定用于对形式参数的实际参数进行验证的脚本。如果脚本结果为 
        false 或脚本引发异常，则 Windows PowerShell 运行时会生成错误。在以下示例中，Count 
        参数的值必须小于 4。

        Param
          (
            [parameter()]
            [Int]
            [ValidateScript({$_ -lt 4})]
            $Count
          ) 


    ValidateSet 属性

        ValidateSet 属性为形式参数的实际参数指定一组有效值。如果形式参数的实际参数与该值集中
        的值不匹配，则 Windows PowerShell 运行时会生成错误。
        在以下示例中，形式参数的实际参数只能包含名字 Steve、Mary 和 Carl。

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange("Steve", "Mary", "Carl")] $UserName
          ) 


    ValidateNotNull 验证属性


        ValidateNotNull 属性指定形式参数的实际参数不能设置为 Null。如果参数值为 Null，则 
        Windows PowerShell 运行时会生成错误。

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


    ValidateNotNullOrEmpty 验证属性

        ValidateNotNullOrEmpty 属性指定形式参数的实际参数不能设置为 Null，也不能为空。如
        果指定了参数，但参数值为 Null、空字符串或空数组，则 Windows PowerShell 运行时会生成
        错误。

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

动态参数  
      
        动态参数是只在特定条件下可用的 cmdlet、函数或脚本的参数。
      
        例如，有几个提供程序 cmdlet 就具有只在提供程序路径中使用了 cmdlet 时
        才可用的参数。一个较常见的动态参数是 Set-Item cmdlet 的 Encoding 参数，
        它只在 FileSystem 提供程序中使用了 Set-Item cmdlet 时可用。
      
        要为函数或脚本创建动态参数，请使用 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。DP1 参数只是在 Path 参数值包含
       “HKLM:”（表明 HKEY_LOCAL_MACHINE 注册表驱动器中正在使用
        它）时在 Sample 函数中可用。
     
      
        function Sample { 
          Param ([String]$Name, [String]$Path) 
      
          DynamicParam 
          { 
            if ($path -match "*HKLM*:") 
            { 
              $dynParam1 = new-object  
                System.Management.Automation.RuntimeDefinedParameter("dp1", 
                [Int32], $attributeCollection) 
      
              $attributes = new-object System.Management.Automation.ParameterAttribute 
              $attributes.ParameterSetName = 'pset1' 
              $attributes.Mandatory = $false 
      
              $attributeCollection = new-object  
                -Type System.Collections.ObjectModel.Collection``1[System.Attribute] 
              $attributeCollection.Add($attributes) 
     
              $paramDictionary = new-object  
                System.Management.Automation.RuntimeDefinedParameterDictionary 
              $paramDictionary.Add("dp1", $dynParam1) 
             
              return $paramDictionary 
            } End if 
          } 
        }   
      
        有关详细信息，请参阅 MSDN (Microsoft Developer Network) 
        库中的“RuntimeDefinedParameter 类”，网址是：
        https://go.microsoft.com/fwlink/?LinkID=145130。
      

另请参阅
    about_Advanced 函数
    
    about_Functions_Advanced_Methods  
    about_Functions_CmdletBindingAttribute