關於參數

發行項
06/21/2023

簡短描述

描述如何在 PowerShell 中使用命令參數。

完整描述

大部分的 PowerShell 命令，例如 Cmdlet、函式和腳本，都依賴參數來允許使用者選取選項或提供輸入。參數會遵循命令名稱，並具有下列格式：

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

參數的名稱前面會加上連字號 (-) ，向 PowerShell 發出訊號，指出連字號後面的字是參數名稱。參數名稱和值可以以空格或冒號字元分隔。某些參數不需要或接受參數值。其他參數需要值，但不需要命令中的參數名稱。

參數的類型和這些參數的需求會有所不同。若要尋找命令參數的相關資訊，請使用 Get-Help Cmdlet。例如，若要尋找 Cmdlet 參數 Get-ChildItem 的相關資訊，請輸入：

Get-Help Get-ChildItem

若要尋找腳本參數的相關資訊，請使用腳本檔案的完整路徑。例如：

Get-Help $home\Documents\Scripts\Get-Function.ps1

Cmdlet 會 Get-Help 傳回命令的各種詳細資料，包括描述、命令語法、參數的相關資訊，以及示範如何在命令中使用參數的範例。

您也可以使用 Cmdlet 的 Get-Help Parameter 參數來尋找特定參數的相關資訊。或者，您可以使用 Parameter 參數搭配萬用字元 ( * ) 值來尋找命令所有參數的相關資訊。例如，下列命令會取得 Cmdlet 所有參數 Get-Member 的相關資訊：

Get-Help Get-Member -Parameter *

預設參數值

選擇性參數具有預設值，這是在命令中未指定參數時所使用或假設的值。

例如，許多 Cmdlet 的 ComputerName 參數預設值是本機電腦的名稱。因此，除非指定 ComputerName 參數，否則會在命令中使用本機電腦名稱稱。

若要尋找預設參數值，請參閱 Cmdlet 的說明主題。參數描述應該包含預設值。

您也可以為 Cmdlet 或進階函式的任何參數設定自訂預設值。如需設定自訂預設值的相關資訊，請參閱 about_Parameters_Default_Values。

參數屬性資料表

當您使用 Cmdlet的Get-Help Full、Parameter或Online參數時， Get-Help 會顯示參數屬性資料表，其中包含參數的詳細資訊。

此資訊包含使用參數所需的詳細資料。例如，Cmdlet 的說明 Get-ChildItem 主題包含其 Path 參數的下列詳細資料：

-path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

參數資訊包括參數語法、參數的描述，以及參數屬性。下列各節說明參數屬性。

必要參數

此設定會指出參數是否為必要，也就是說，使用此 Cmdlet 的所有命令是否都必須包含此參數。當值為 True 且命令中遺漏參數時，PowerShell 會提示您輸入參數的值。

參數位置

Position如果設定設定為正整數，則不需要參數名稱。這種類型的參數稱為位置參數，而數位表示參數必須與其他位置參數相對顯示的位置。具名參數可以列在 Cmdlet 名稱之後的任何位置。如果您包含位置參數的參數名稱，參數可以列在 Cmdlet 名稱之後的任何位置。

例如， Get-ChildItem Cmdlet 具有 Path 和 Exclude 參數。 PositionPath的設定為0，這表示它是位置參數。 [排除] 的 Position 設定名為。

這表示 Path 不需要參數名稱，但其參數值必須是命令中的第一個或唯一未命名的參數值。不過，因為 Exclude 參數是具名參數，所以您可以將它放在命令中的任何位置。

由於這兩個參數的 Position 設定，您可以使用下列任一命令：

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

如果您要包含另一個位置參數而不包含參數名稱，則必須依照設定所 Position 指定的順序放置該參數。

參數類型

此設定會指定參數值的 Microsoft .NET Framework類型。例如，如果類型為 Int32，則參數值必須是整數。如果類型為字串，則參數值必須是字元字串。如果字串包含空格，值必須以引號括住，否則空格前面必須加上逸出字元 ( ' ) 。

預設值

此設定會指定參數在未提供其他值時會假設的值。例如，Path 參數的預設值通常是目前的目錄。必要的參數永遠不會有預設值。對於許多選擇性參數，沒有預設值，因為如果未使用參數，參數就不會有任何作用。

接受多個值

此設定指出參數是否接受多個參數值。當參數接受多個值時，您可以在命令中輸入逗號分隔清單做為參數的值，或在變數中 (陣列) 儲存逗號分隔清單，然後將變數指定為參數值。

例如，Cmdlet 的 Get-Service ServiceName 參數會接受多個值。下列命令都是有效的：

Get-Service -servicename winrm, netlogon

$s = "winrm", "netlogon"
Get-Service -servicename $s

接受管線輸入

此設定指出您是否可以使用管線運算子 () | 將值傳送至參數。

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

當參數為「True (by Value) 」時，PowerShell 會先嘗試將任何管線值與該參數產生關聯，然後再嘗試其他方法來解譯命令。

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

例如，只有當值具有名為Name的屬性時，才可以使用管線將值傳送至Name參數。

注意

接受管線輸入 () by Value 或 () by PropertyName 的具型別參數，可讓您在參數上使用 延遲系結 腳本區塊。

延遲系結腳本區塊會在ParameterBinding期間自動執行。結果會系結至參數。延遲系結 不適用於 定義為類型 ScriptBlock 或 System.Object 的參數，腳本區塊會在不叫用 的情況下 通過。

您可以在這裡閱讀 延遲系結 腳本區塊 about_Script_Blocks.md