關於參數

發行項
05/09/2024

簡短描述

描述如何在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