about_Parameters_Default_Values

简短说明

介绍如何为 cmdlet 参数、高级函数和脚本设置自定义默认值。

详细说明

$PSDefaultParameterValues 首选项变量允许为使用 CmdletBinding 属性的任何 cmdlet、高级函数或脚本指定自定义默认参数值。 除非在命令行上指定其他值，否则将使用定义的值。

此功能在以下方案中非常有用：

• 每次使用命令时都指定相同的参数值
• 指定难以记住的特定参数值，例如电子邮件服务器名称或项目 GUID

$PSDefaultParameterValues 变量没有默认值。 若要保存用于将来会话的设置，请将变量分配添加到 PowerShell 配置文件。

PowerShell 3.0 中引入了 $PSDefaultParameterValues。

Syntax

$PSDefaultParameterValues 变量是 System.Management.Automation.DefaultParameterDictionary的对象类型。 DefaultParameterDictionary 类型是一个哈希表，对键格式进行了一些额外验证。 哈希表包含的键值对如下：

• 键 格式为 CommandName:ParameterName
• 值 是参数的默认值或是一个返回默认值的 ScriptBlock

对于键，CommandName 必须是使用 CmdletBinding 属性的 cmdlet、高级函数或脚本文件的名称。 脚本名称必须与 (Get-Command -Name .\script.ps1).Name报告的名称匹配。

值可以是与参数兼容的类型的对象，也可以是返回此类值的 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。 此示例将所有命令详细参数设置为 $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

另请参阅

• about_CommonParameters
• about_Functions_Advanced
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Profiles
• about_Script_Blocks