共用方式為

about_Parameters_Default_Values

  • 發行項

適用於: Windows PowerShell 3.0

主題

about_Parameters_Default_Values

簡短描述

描述如何為 Cmdlet 和進階函式的參數設定自訂的預設值。

詳細描述

$PSDefaultParameterValues 喜好設定變數可讓您為任何 Cmdlet 和進階函式指定自訂的預設值。除非您在命令中指定其他值，否則 Cmdlet 和函式會使用自訂的預設值。

Cmdlet 和進階函式的作者會為其參數設定標準預設值。通常標準預設值都很有用，但不一定適合所有環境。

如果您幾乎每次使用此命令時，都必須指定相同的替代參數值，或是很難記住特定參數值 (例如電子郵件伺服器名稱或專案 GUID) 時，此功能會特別好用。

如果可以預測所需預設值的變化，您可以指定指令碼區塊，針對不同情況下的參數提供不同的預設值。

$PSDefaultParameterValues 是在 Windows PowerShell 3.0 中引進。

語法

$PSDefaultParameterValues 喜好設定變數的語法如下所示：

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"="<DefaultValue>"}

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"={<ScriptBlock>}}

       $PSDefaultParameterValues["Disabled"]=$true | $false

CmdletName 和 ParameterName 值中可允許萬用字元。

$PSDefaultParameterValues 的值是 System.Management.Automation.DefaultParameterDictionary，這是一種驗證機碼格式的雜湊表。請輸入雜湊表，其中機碼是由 Cmdlet 名稱和參數名稱組成 (以冒號 (:) 分隔)，而值是自訂的預設值。

若要從 $PSDefaultParameterValues 設定、變更、新增或移除項目，請使用您要用來編輯標準雜湊表的方法。

<CmdletName> 必須是 Cmdlet 名稱，或是使用 CmdletBinding 屬性的進階函式名稱。您不能使用 $PSDefaultParameterValues 來指定指令碼或簡單函式的預設值。

預設值可以是物件或指令碼區塊。如果值為指令碼區塊，則 Windows PowerShell 會評估指令碼區塊，並使用其結果做為參數值。當指定的參數使用指令碼區塊值時，請以第二組大括弧來括住指令碼區塊值，例如：$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

如需雜湊表的相關資訊，請參閱 about_Hash_Tables。如需指令碼區塊的相關資訊，請參閱 about_Script_Blocks。如需喜好設定變數的相關資訊，請參閱 about_Preference_Variables。

範例

下列命令會為 Send-MailMessage Cmdlet 的 SmtpServer 參數設定自訂預設值。

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"}

若要為多個參數設定預設值，請使用分號 (;) 將每個「名稱=值」組隔開。下列命令會為 Get-WinEvent Cmdlet 的 LogName 參數新增自訂預設值。

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
               "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"}

您可以在 Cmdlet 和參數的名稱中使用萬用字元。下列命令會在所有命令中，將 Verbose 一般參數設為 $true。您可以使用 $true 和 $false 來設定切換參數的值，例如 Verbose。

        $PSDefaultParameterValues = @{"*:Verbose"=$true}

如果參數使用多個值 (陣列)，您可以將多個值設為預設值。下列命令會將 Invoke-Command Cmdlet 的 ComputerName 參數預設值設為 "Server01" 和 "Server02"。

        $PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"}

您可以使用指令碼區塊，針對不同情況下的參數，指定不同的預設值。Windows PowerShell 會評估指令碼區塊，並使用其結果做為預設參數值。

當主機程式為 Windows PowerShell 主控台時，下列命令會將 Format-Table Cmdlet 的 Autosize 參數預設值設為 $true。

        $PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name –eq "ConsoleHost"){$true}}}

如果參數使用指令碼區塊值，請使用另一組大括弧來括住指令碼區塊。當 Windows PowerShell 評估外部指令碼區塊時，結果就是內部指令碼區塊，其已設為預設參數值。

下列命令會設定 Invoke-Command 的 ScriptBlock 參數預設值。因為指令碼區塊是以第二組大括弧括住，所以括住的指令碼區塊會傳遞至 Invoke-Command Cmdlet。

        $PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog –Log System}}}

如何設定 $PSDefaultParameterValues

$PSDefaultParameterValues 是喜好設定變數，因此只存在於設定該變數的工作階段中。它沒有預設值。

若要設定 $PSDefaultParameterValues，請在命令列輸入變數名稱，以及一個或多個「機碼-值」組。

如果您輸入另一個 $PSDefaultParameterValues 命令，其值會取代原始值。不保留原始值。

若要儲存 $PSDefaultParameterValues 供未來工作階段使用，請新增 $PSDefaultParameterValues 命令至您的 Windows PowerShell 設定檔。如需詳細資訊，請參閱 about_Profiles。

如何取得 $PSDefaultParameterValues

若要取得 $PSDefaultParameterValues 的值，請在命令提示字元中輸入：$PSDefaultParameterValues

例如，第一個命令會設定 $PSDefaultParameterValues 的值。第二個命令會取得 $PSDefaultParameterValues 的值。

        PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
                "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
                "Get-*:Verbose"=$true}

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

若要取得 <CmdletName:ParameterName> 機碼的值，請使用下列命令語法：

       $PSDefaultParameterValues["<CmdletName:ParameterName>"]

例如：

       PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
       Server01AB234x5

如何新增值至 $PSDefaultParameterValues

若要在 $PSDefaultParameterValues 中新增或移除值，請使用您要用於標準雜湊表的方法。

例如，若要新增值至 $PSDefaultParameterValues，而不影響現有的值，請使用雜湊表的 Add 方法。

Add 方法的語法如下所示：

        <HashTable>.Add(Key, Value)

其中 Key 是 "<CmdletName>:<ParameterName>"，而值是參數值。

您可以使用下列命令格式，在 $PSDefaultParameterValues 上呼叫 Add 方法。請務必使用逗號 (,) 將機碼和值分隔，而不是使用等號 (=)。

        $PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")

例如，下列命令會新增 "PowerShell"，做為 Get-Process Cmdlet 的 Name 參數預設值。

        $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

下列範例會顯示此命令的效果。

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

        PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Get-Process:Name               PowerShell
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

如何從 $PSDefaultParameterValues 移除值

若要從 $PSDefaultParameterValues 移除值，請使用雜湊表的 Remove 方法。

Remove 方法的語法如下所示：

        <HashTable>.Remove(Key)

您可以使用下列命令格式，在 $PSDefaultParameterValues 上呼叫 Remove 方法。

        $PSDefaultParameterValues.Remove("<CmdletName>:<ParameterName>")

例如，下列命令會移除 Get-Process Cmdlet 的 Name 參數及其值。

        $PSDefaultParameterValues.Remove("Get-Process:Name")

下列範例會顯示此命令的效果。

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Get-Process:Name               PowerShell
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

        PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

如何變更 $PSDefaultParameterValues 中的值

若要變更 $PSDefaultParameterValues 中的值，請使用下列命令格式。

        $PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"

下列範例會顯示此命令的效果。

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Send-MailMessage:SmtpServer    Server01AB234x5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

        PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
   
        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Send-MailMessage:SmtpServer    Server0000cabx5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

如何停用及重新啟用 $PSDefaultParameterValues

您可以暫時停用然後再重新啟用 $PSDefaultParameterValues。如果您執行的指令碼可能會假設不同的預設參數值，這會非常有用。

若要停用 $PSDefaultParameterValues，請新增 "Disabled" 機碼和 $True 值。

例如，

        $PSDefaultParameterValues.Add("Disabled", $true)

        - or -

        $PSDefaultParameterValues[Disabled]=$true

$PSDefaultParameterValues 中的其他值會保留，但無效。

        PS C:\> $PSDefaultParameterValues

        Name                           Value
        ----                           -----
        Disabled                       True
        Send-MailMessage:SmtpServer    Server0000cabx5
        Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
        Get*:Verbose                   True

若要重新啟用 $PSDefaultParameterValues，請移除 Disabled 機碼，或將 Disabled 機碼的值變更為 $False。

        $PSDefaultParameterValues.Remove("Disabled")

- or -

        $PSDefaultParameterValues[Disabled]=$false

$PSDefaultParameterValues 先前的值就會再生效。

關鍵字

about_PSDefaultParameterValues

about_Parameters_DefaultValues

about_DefaultValues

另請參閱

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks