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 屬性可用來宣告函數的參數。
      這個屬性具有下列的具名引數，可用來定義參數的特性，例如該參數是必要項或選
      擇項。


    Mandatory 具名引數

        Mandatory 引數指出參數在函數在執行時為必要項。如果未指定這個引數，參數
        就是選擇性的參數。下列範例示範如何宣告函數執行時必要的參數。

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


    Position 具名引數

        Position 引數會指定參數的位置。如果未指定此引數，則必須在設定參數時明
        確地指定參數名稱或其別名。此外，如果函數的參數中沒有一個具有位置，則
        Windows PowerShell 執行階段會根據接收。

        下列範例示範如何宣告參數，在 cmdlet 執行時，此參數的值必須指定為第一個
        引數。請注意，不論是否指定了參數的名稱，這個函數都可以執行。

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


    ParameterSetName 具名引數

        ParameterSetName 引數會指定參數所屬的參數集。如果沒有指定任何參數集，
        則此參數會屬於函數所定義的所有參數集。這項行為代表每個參數集都必須具
        有一個唯一的參數，且該參數並非任何其他參數集的成員。下列範例示範如何
        宣告兩個分屬不同參數集的參數。

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName=”電腦”)] [String[]]
            $ComputerName
          ) 

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName=”使用者”)] [String[]]
            $UserName
          ) 

        如需參數集的詳細資訊，請參閱 MSDN 文件庫中的＜Cmdlet 參數集＞
        (https://go.microsoft.com/fwlink/?LinkId=142183)(英文)。


    ValueFromPipeline 具名引數

        ValueFromPipeline 引數會指定參數接受來自管線物件的輸入。如果 Cmdlet 存
        取完整的物件，而不只是物件的屬性，請指定這個引數。下列範例示範如何宣告
        ComputerName 強制參數，此參數會接受從管線傳遞到函數的輸入物件。

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


    ValueFromPipelineByPropertyName 具名引數

        valueFromPipelineByPropertyName 引數會指定參數接受來自管線物件屬性的輸
        入。如果下列條件為 true，請指定這個屬性：

            - 參數會存取管線物件的屬性。

            - 該屬性的名稱與參數相同，或者別名與參數相同。

        例如，如果函數具有 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=”電腦名稱的陣列。”)] [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 執行階段就會產生錯誤。
        下列範例中，指定的電腦名稱必須具有一到十個字元。

        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 {<陳述式-清單>}

    在陳述式清單中，使用 If 陳述式指定在何種情況下可在函數中使用參數。

    使用 New-Object Cmdlet 建立 
    System.Management.Automation.RuntimeDefinedParameter 物件以代表參
    數並指定其名稱。

    您也可以使用 New-Object 命令建立 
    System.Management.Automation.ParameterAttribute 物件以代表參數的屬
    性，例如 Mandatory、Position 或 ValueFromPipeline，或是其參數集。

    下列範例說明 Sample 函數，其中包含名為 Name 和 Path 的標準參數，以及名
    為 DP1 動態參數 (選用)。DP1 參數位於 PSet1 參數集中，型別為 Int32。只有
    當 Path 參數值包含 "HKLM:" (表示其目前用於 HKEY_LOCAL_MACHINE 登錄磁碟
    機) 時才能在 Sample 函數中使用 DP1 參數。


    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_Functions
    about_Functions_CmdletBindingAttribute
    about_Functions_Advanced_Methods