共用方式為


about_Parameters_Default_Values

簡短描述

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

詳細描述

$PSDefaultParameterValues喜好設定變數可讓您指定任何 Cmdlet 或進階函式的自定義預設值。 除非您在命令中指定另一個值,否則 Cmdlet 和進階函式會使用自定義預設值。

Cmdlet 和進階函式的作者會為其參數設定標準預設值。 一般而言,標準預設值很有用,但可能不適用於所有環境。

當您幾乎每次使用 命令或特定參數值難以記住時,此功能特別有用,例如電子郵件伺服器名稱或專案 GUID。

如果所需的預設值可以預測,您可以指定腳本區塊,為不同條件下的參數提供不同的預設值。

$PSDefaultParameterValues 已在 PowerShell 3.0 中引進。

語法

$PSDefaultParameterValues變數是哈希表,會將索引鍵的格式驗證為 System.Management.Automation.DefaultParameterDictionary 的物件類型。 哈希表包含 索引鍵/值 組。 索引 格式 CmdletName:ParameterName為 。 Value 是指派給密鑰的 DefaultValueScriptBlock

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

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

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

$PSDefaultParameterValues["Disabled"]=$True | $False

CmdletName 和 ParameterName 值允許通配符。

若要從 $PSDefaultParameterValues設定、變更、新增或移除特定的索引鍵/值組,請使用 方法來編輯標準哈希表。 例如, AddRemove 方法。 這些方法不會覆寫哈希表中的其他值。

有另一個語法不會覆寫現有的 $PSDefaultParameterValues 哈希表。 若要新增或變更特定的 索引鍵/值 組,請使用下列語法:

$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

CmdletName 必須是 Cmdlet 的名稱,或是使用 CmdletBinding 屬性的進階函式名稱。 您無法使用 $PSDefaultParameterValues 指定文稿或簡單函式的預設值。

DefaultValue 可以是物件或腳本區塊。 如果值是腳本區塊,PowerShell 會評估腳本區塊,並使用結果做為參數值。 當指定的參數接受文稿區塊值時,請將腳本區塊值放在第二組大括弧中,例如:

$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

如需詳細資訊,請參閱下列文件:

範例

如何設定$PSDefaultParameterValues

$PSDefaultParameterValues 是喜好設定變數,因此它只存在於設定所在的會話中。 它沒有預設值。

若要設定 $PSDefaultParameterValues,請輸入變數名稱和一或多個 索引鍵/值 組。 如果您執行另一個 $PSDefaultParameterValues 命令,它會覆寫現有的哈希表。

如需如何變更 索引鍵/值 組而不覆寫現有哈希表值的範例,請參閱 如何將值新增至$PSDefaultParameterValues如何變更$PSDefaultParameterValues中的值。

若要儲存 $PSDefaultParameterValues 未來會話,請將命令新增 $PSDefaultParameterValues 至 PowerShell 配置檔。 如需詳細資訊,請參閱 about_Profiles

設定自訂預設值

機碼/值組會將Send-MailMessage:SmtpServer索引鍵設定為 Server123自定義預設值。

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

設定多個參數的預設值

若要設定多個參數的預設值,請以分號分隔每個索引鍵/值組。; Send-MailMessage:SmtpServerGet-WinEvent:LogName 索引鍵會設定為自定義預設值。

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

使用通配符和參數

Cmdlet 和參數名稱可以包含通配符。 使用 $True$False 來設定參數的值,例如 Verbose。 通用參數的 Verbose 參數會針對所有命令設定為 $True

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

使用陣列作為預設值

如果參數可以接受多個值陣列,您可以將多個值設定為預設值。 機碼的Invoke-Command:ComputerName預設值會設定為 Server01Server02陣列值。

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

使用腳本區塊

您可以使用文稿區塊,在不同的條件下為參數指定不同的預設值。 PowerShell 會評估腳本區塊,並使用結果作為預設參數值。

索引Format-Table:AutoSize鍵會將參數切換為 True 的預設值If語句包含的條件必須是 $host.Name PowerShell主控台 ConsoleHost

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

如果參數接受腳本區塊值,請將腳本區塊括在一組額外的大括弧中。 當 PowerShell 評估外部腳本區塊時,結果會是內部腳本區塊,且設定為預設參數值。

索引Invoke-Command:ScriptBlock鍵會設定為 System 事件記錄的預設值,因為腳本區塊會以第二組大括弧括住。 腳本區塊的結果會傳遞至 Invoke-Command Cmdlet。

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

如何取得$PSDefaultParameterValues

哈希表值會藉由在PowerShell提示字元中輸入 $PSDefaultParameterValues 來顯示。

哈希表會設定三$PSDefaultParameterValues索引鍵/值組。 下列範例會使用此哈希表,說明如何從 $PSDefaultParameterValues新增、變更和移除值。

PS> $PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123"
  "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
  "Get-*:Verbose"=$True
}

PS> $PSDefaultParameterValues

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

若要取得特定 CmdletName:ParameterName 索引鍵的值,請使用下列語法:

$PSDefaultParameterValues["CmdletName:ParameterName"]

例如,若要取得索引鍵的值 Send-MailMessage:SmtpServer

PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server123

如何將值新增至$PSDefaultParameterValues

若要將值新增至 $PSDefaultParameterValues,請使用 Add 方法。 加入值不會影響哈希表的現有值。

使用逗號 (,) 來分隔 索引鍵Value。 下列語法示範如何使用$PSDefaultParameterValuesAdd 方法。

PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue")

在先前範例中建立的哈希表會以新的 索引鍵/值 組進行更新。 Add 方法會將Get-Process:Name索引鍵設定為 PowerShell

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

下列語法會完成相同的結果。

$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"

變數 $PSDefaultParameterValues 會顯示更新的哈希表。 已 Get-Process:Name 新增金鑰。

PS> $PSDefaultParameterValues

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

如何從$PSDefaultParameterValues移除值

若要從 $PSDefaultParameterValues中移除值,請使用 哈希表的 Remove 方法。 拿掉值不會影響哈希表的現有值。

下列語法示範如何在 上使用 $PSDefaultParameterValuesRemove 方法。

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

在此範例中,先前範例中建立的哈希表會更新為移除 索引鍵/值 組。 Remove 方法會Get-Process:Name移除索引鍵。

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

變數 $PSDefaultParameterValues 會顯示更新的哈希表。 金鑰 Get-Process:Name 已移除。

PS> $PSDefaultParameterValues

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

如何變更$PSDefaultParameterValues中的值

對特定值的變更不會影響現有的哈希表值。 若要在 中$PSDefaultParameterValues變更特定的索引鍵/值組,請使用下列語法:

PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

在此範例中,先前範例中建立的哈希表會更新為變更 索引鍵/值 組。 下列命令會將Send-MailMessage:SmtpServer索引鍵變更為 ServerXYZ 的新值

$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ"

變數 $PSDefaultParameterValues 會顯示更新的哈希表。 索引 Send-MailMessage:SmtpServer 鍵已變更為新的值。

PS> $PSDefaultParameterValues

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

如何停用和重新啟用$PSDefaultParameterValues

您可以暫時停用,然後重新啟用 $PSDefaultParameterValues。 如果您要執行需要不同預設參數值的腳本,停用 $PSDefaultParameterValues 會很有用。

若要停用 $PSDefaultParameterValues,請新增 值為 True索引鍵Disabled。 中的 $PSDefaultParameterValues 值會保留,但無效。

PS> $PSDefaultParameterValues.Add("Disabled", $True)

下列語法會完成相同的結果。

PS> $PSDefaultParameterValues["Disabled"]=$True

變數 $PSDefaultParameterValues 會以索引鍵的值顯示更新的 Disabled 哈希表。

PS> $PSDefaultParameterValues

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

若要重新啟用 $PSDefaultParameterValues,請移除 Disabled 索引鍵,或將 Disabled 索引鍵的值變更為 $False。 的先前值 $PSDefaultParameterValues 再次生效。

PS> $PSDefaultParameterValues.Remove("Disabled")

下列語法會完成相同的結果。

PS> $PSDefaultParameterValues["Disabled"]=$False

變數 $PSDefaultParameterValues 會顯示更新的哈希表。 使用 Remove 方法時,會Disabled從輸出中移除索引鍵。 如果使用替代語法重新啟用 $PSDefaultParameterValues,索引 Disabled 鍵會顯示為 False

PS> $PSDefaultParameterValues

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

另請參閱