about_Parameters

發行項
03/19/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參數。 Position Path 的設定為 0，這表示它是位置參數。 Exclude 的設定名稱為 。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 Name 參數接受多個值。下列命令都是有效的：

Get-Service -Name winrm, netlogon

$s = "winrm", "netlogon"
Get-Service -Name $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 Valueby PropertyName）的具型別參數，可讓您在 參數上使用延遲系結腳本區塊。

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

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

接受通配符

此設定指出參數的值是否可以包含通配符，以便參數值可以比對目標容器中的多個現有專案。

一般參數

常見的參數是您可以搭配任何 Cmdlet 使用的參數。如需常見參數的詳細資訊，請參閱 about_CommonParameters。