关于参数默认值

简短说明

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

长说明

首选项 $PSDefaultParameterValues 变量允许指定任何 cmdlet 或高级函数的自定义默认值。 除非在命令中指定其他值,否则 Cmdlet 和高级函数使用自定义默认值。

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

如果几乎每次使用命令时都必须指定相同的备用参数值,或者当特定参数值难以记住(如电子邮件服务器名称或项目 GUID)时,此功能特别有用。

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

$PSDefaultParameterValues 已在 PowerShell 3.0 中引入。

语法

变量 $PSDefaultParameterValues 是一个哈希表,用于验证作为 System.Management.Automation.DefaultParameterDictionary 对象类型的键的格式。 哈希表包含 键/值 对。 的格式CmdletName:ParameterName为 。 是分配给键的 DefaultValueScriptBlock

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

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

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

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

CmdletNameParameterName 值中允许使用通配符。

若要在 $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 设置为 系统事件日志 的默认值,因为脚本块包含在第二组大括号中。 脚本块的结果将 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 方法。 删除值不会影响哈希表的现有值。

以下语法演示如何在 上使用 $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

另请参阅

about_CommonParameters

about_Functions_Advanced

about_Functions_CmdletBindingAttribute

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks