共用方式為

about_Parameters_Default_Values

簡短描述

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

完整描述

$PSDefaultParameterValues 喜好設定變數可讓您為任何使用 cmdletBinding 屬性的 Cmdlet、進階函式或腳本指定自定義預設參數值。 除非您在命令行上指定其他值，否則會使用定義的值。

這項功能在下列案例中很有用：

  • 每次使用 命令時，都會指定相同的參數值
  • 指定難以記住的特定參數值，例如電子郵件伺服器名稱或專案 GUID

$PSDefaultParameterValues 變數沒有預設值。 若要儲存在未來會話中使用的設定，請將變數指派新增至PowerShell配置檔。

$PSDefaultParameterValues 已在 PowerShell 3.0 中引進。

語法

$PSDefaultParameterValues 變數是 System.Management.Automation.DefaultParameterDictionary物件類型。 DefaultParameterDictionary 類型是雜湊表，對索引鍵格式進行了一些額外的驗證。 哈希表包含鍵值對，其中：

  • 按鍵 具有格式 CommandName:ParameterName
  • 值 是參數的預設值，或是能傳回預設值的 ScriptBlock。

針對 索引鍵，CommandName 必須是使用 cmdletBinding 属性的 Cmdlet、進階函式或腳本檔案的名稱。 腳本名稱必須符合 (Get-Command -Name .\script.ps1).Name所報告的名稱。

注意

PowerShell 不會阻止您為 CommandName指定別名。 不過，在某些情況下會忽略定義或造成錯誤。 您應該避免定義命令別名的預設值。

值 可以是與 參數兼容的類型物件，或是傳回這類值的 ScriptBlock。 當值為腳本區塊時，PowerShell 會評估腳本區塊，並使用參數值的結果。 如果指定的參數需要 ScriptBlock 類型，您必須將值放在另一組大括弧中。 當 PowerShell 評估外部 ScriptBlock時，結果是內部 ScriptBlock。 內部 ScriptBlock 會成為新的預設參數值。

例如：

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

範例

使用 Add() 和 Remove() 方法，從 $PSDefaultParameterValues 新增或移除特定索引鍵/值組，而不覆寫其他現有的索引鍵/值組。

$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue')
$PSDefaultParameterValues.Remove('CmdletName:ParameterName')

使用索引編製或成員存取來變更現有索引鍵/值組的值。 例如：

$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2'
$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1'

為 $PSDefaultParameterValues 指派值

若要定義 Cmdlet 參數的預設值，請將包含適當索引鍵/值組的哈希表指派給 $PSDefaultParameterValues 變數。 哈希表可以包含多個索引鍵/值組。 本範例會設定 Send-MailMessage:SmtpServer 和 Get-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 索引鍵的預設值設定為包含字串值的陣列，Server01 和 Server02。

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

檢視定義的值

讓我們考慮 $PSDefaultParameterValues的以下定義：

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer' = 'Server123'
  'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational'
  'Get-*:Verbose' = $true
}

您可以在命令提示字元中輸入 $PSDefaultParameterValues，以檢視定義的值。

PS> $PSDefaultParameterValues

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

您可以使用索引編製或成員存取來取得特定值。

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation
Server123
PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation
True

使用腳本區塊作為預設值

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

Format-Table:AutoSize 鍵會將該參數設為預設值 $true。if 語句包含一個條件，即 $Host.Name 必須是 ConsoleHost。

$PSDefaultParameterValues = @{
  'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}

如果參數接受 ScriptBlock 值，請將 ScriptBlock 放在另一組大括弧中。 當 PowerShell 評估外部 ScriptBlock時，結果是內部 ScriptBlock。 內部 ScriptBlock 會成為新的預設參數值。

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

將值新增至現有的 $PSDefaultParameterValues 變數

若要將值新增至 $PSDefaultParameterValues，請使用 Add() 方法。 加入值不會影響哈希表的現有值。 使用逗號（,）將 索引鍵 從 值中分隔開。

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

在先前範例中建立的哈希表會以新的機碼/值組進行更新。

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() 方法。 拿掉值不會影響哈希表的現有值。

此範例會移除上一個範例中新增的鍵值對。

PS> $PSDefaultParameterValues.Remove('Get-Process:Name')
PS> $PSDefaultParameterValues

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

變更 $PSDefaultParameterValues 中的值

使用索引編製或成員存取來變更現有索引鍵/值組的預設值。 在這個範例中，Send-MailMessage:SmtpServer 索引鍵的預設值被變更為新的值 ServerXYZ。

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ'
PS> $PSDefaultParameterValues

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

停用或重新啟用 $PSDefaultParameterValues

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

若要停用 $PSDefaultParameterValues，請新增一個 Disabled 索引鍵並將其值設為 $true。 $PSDefaultParameterValues 中的值會保留，但不會使用。

PS> $PSDefaultParameterValues.Add('Disabled', $true)
PS> $PSDefaultParameterValues

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

若要重新啟用 $PSDefaultParameterValues，請移除 Disabled 索引鍵，或將 Disabled 索引鍵的值變更為 $false。

PS> $PSDefaultParameterValues.Disabled = $false
PS> $PSDefaultParameterValues

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

另請參閱

  • Last updated on