about_Parameters_Default_Values

简短说明

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

长说明

使用 $PSDefaultParameterValues 首选项变量可为任何 cmdlet 或高级函数指定自定义默认值。 cmdlet 和高级函数使用自定义默认值，除非在命令中指定另一个值。

cmdlet 和高级函数的作者为其参数设置标准默认值。 通常，标准默认值很有用，但它们可能不适合所有环境。

如果你几乎每次使用命令时都必须指定相同的备用参数值，或者当某个特定参数值（例如，电子邮件服务器名称或项目 GUID）很难记住时，此功能尤其有用。

如果所需的默认值可预测地变化，则可以指定一个脚本块，该脚本块在不同条件下为参数提供不同的默认值。

PowerShell 3.0 中引入了 $PSDefaultParameterValues。

语法

$PSDefaultParameterValues 变量是一个哈希表，以对象类型 System.Management.Automation.DefaultParameterDictionary 形式验证键的格式。 哈希表包含键/值对。 键的格式为 CmdletName:ParameterName。 值是分配给键的 DefaultValue 或 ScriptBlock。

$PSDefaultParameterValues 首选项变量的语法如下所示：

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

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

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

CmdletName 和 ParameterName 值中允许使用通配符。

若要从 $PSDefaultParameterValues 设置、更改、添加或删除特定键/值对，请使用方法编辑标准哈希表。 例如，Add 和 Remove 方法。 这些方法不会覆盖哈希表中的其他值。

还有一种语法不会覆盖现有 $PSDefaultParameterValues 哈希表。 若要添加或更改特定键/值对，请使用以下语法：

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

CmdletName 必须是 cmdlet 的名称，或者是使用 CmdletBinding 属性的高级函数的名称。 不能使用 $PSDefaultParameterValues 为脚本或简单函数指定默认值。

DefaultValue 可以是对象或脚本块。 如果值为脚本块，PowerShell 将对脚本块进行求值，并将结果用作参数值。 当指定的参数接受脚本块值时，请将脚本块值括在第二组大括号中，例如：

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

有关详细信息，请参阅以下文档：

• about_Hash_Tables
• about_Script_Blocks
• about_Preference_Variables

示例

如何设置 $PSDefaultParameterValues

$PSDefaultParameterValues 是首选项变量，因此它仅在设置它的会话中存在。 它没有默认值。

若要设置 $PSDefaultParameterValues，请键入变量名和一个或多个键/值对。 如果运行另一个 $PSDefaultParameterValues 命令，它将覆盖现有的哈希表。

有关如何在不覆盖现有哈希表值的情况下更改键/值对的示例，请参阅如何向 $PSDefaultParameterValues 添加值或如何更改 $PSDefaultParameterValues 中的值。

若要为将来的会话保存 $PSDefaultParameterValues，请将 $PSDefaultParameterValues 命令添加到 PowerShell 配置文件。 有关详细信息，请参阅 about_Profiles。

设置自定义默认值

键/值对将 Send-MailMessage:SmtpServer 键设置为 Server123 的自定义默认值。

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

设置多个参数的默认值

若要设置多个参数的默认值，请使用分号 (;) 分隔每个键/值对。 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"
}

使用脚本块

可以使用脚本块在不同条件下为参数指定不同默认值。 PowerShell 将对脚本块进行求值，并将结果用作默认参数值。

Format-Table:AutoSize 键将该开关参数设置为默认值 True。 If 语句包含一个条件，即 $host.Name 必须是 PowerShell 控制台 ConsoleHost。

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

如果参数接受脚本块值，请将脚本块括在一组额外的大括号中。 当 PowerShell 评估外部脚本块时，结果为内部脚本块，并将其设置为默认参数值。

Invoke-Command:ScriptBlock 键设置为系统事件日志的默认值，因为脚本块包含在第二组大括号中。 脚本块的结果将传递给 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 方法。 添加值不会影响哈希表的现有值。

使用逗号 (,) 将键与值分开。 以下语法演示如何使用 Add 方法进行 $PSDefaultParameterValues。

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 方法。 删除值不会影响哈希表的现有值。

以下语法演示如何在 $PSDefaultParameterValues 上使用 Remove 方法。

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

另请参阅

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