通过

about_Parameters_Default_Values

  • 项目

应用到: Windows PowerShell 3.0, Windows PowerShell 4.0

主题

about_Parameters_Default_Values

简短说明

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

详细说明

借助 $PSDefaultParameterValues 首选项变量，你可以为任何 cmdlet 或高级函数指定自定义默认值。除非在命令中指定其他值，否则 cmdlet 和函数使用自定义默认值。

Cmdlet 和高级函数的编写者为其参数设置标准默认值。通常情况下，标准默认值很有用，但它们可能不适用于所有环境。

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

如果所需的默认值按可预见方式而有所不同，可指定一个脚本块，用于在不同的条件下为参数提供不同的默认值。

Windows PowerShell 3.0 中引入了 $PSDefaultParameterValues。

语法

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

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

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

       $PSDefaultParameterValues["Disabled"]=$true | $false

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

$PSDefaultParameterValues 的值是 System.Management.Automation.DefaultParameterDictionary，它是一种可验证密钥格式的哈希表。输入哈希表，其中密钥由 cmdlet 名称和参数名称组成（以冒号 (:) 分隔），并且该值是自定义默认值。

若要设置、更改、添加或删除 $PSDefaultParameterValues 中的条目，请使用用于编辑标准哈希表的方法。

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

默认值可以是对象或脚本块。如果该值为脚本块，则 Windows PowerShell 将计算脚本块并将其结果用作参数值。当指定的参数采用脚本块值时，请将脚本块值用第二组大括号括起来，例如：$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

有关哈希表的信息，请参阅 about_Hash_Tables。有关脚本块的信息，请参阅 about_Script_Blocks。有关首选项变量的信息，请参阅 about_Preference_Variables。

示例

以下命令将设置 Send-MailMessage cmdlet 的 SmtpServer 参数的自定义默认值。

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

若要为多个参数设置默认值，请使用分号 (;) 分隔每个名称/值对。以下命令将添加 Get-WinEvent cmdlet 的 LogName 参数的自定义默认值。

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

可以在 cmdlet 和参数的名称中使用通配符。以下命令在所有命令中将 Verbose 通用参数设置为 $true。使用 $true 和 $false 为开关参数设置值，例如 Verbose。

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

如果参数采用多个值（数组），可以将多个值设置为默认值。以下命令将 Invoke-Command cmdlet 的 ComputerName 参数的默认值设置为“Server01”和“Server02”。

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

可以使用脚本块在不同的条件下为参数指定不同的默认值。Windows PowerShell 将计算该脚本块并将结果用作默认参数值。

当主机程序为 Windows PowerShell 控制台时 以下命令将 Format-Table cmdlet 的 Autosize 参数的默认值设置为 $true。

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

如果参数采用脚本块值，请额外使用一组大括号将该脚本块括起来。当 Windows PowerShell 计算外部脚本块时，将产生设置为默认参数值的内部脚本块。

以下命令将设置 Invoke-Command 的 ScriptBlock 参数的默认值。因为脚本块括在第二组大括号中，因此括起来的脚本块将传递给 Invoke-Command cmdlet。

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

如何设置 $PSDefaultParameterValues

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

若要设置 $PSDefaultParameterValues，请在命令行中键入变量名称以及一个或多个键/值对。

如果键入其他 $PSDefaultParameterValues 命令，其值将替换初始值。不保留初始值。

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

如何获取 $PSDefaultParameterValues

若要获取 $PSDefaultParameterValues 的值，请在命令提示符下，键入：$PSDefaultParameterValues

例如，第一个命令将设置 $PSDefaultParameterValues 的值。第二个命令将获取 $PSDefaultParameterValues 的值。

        PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
                "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
                "Get-*:Verbose"=$true}

        PS C:\> $PSDefaultParameterValues

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

若要获取 <CmdletName:ParameterName> 键的值，请使用以下命令语法：

       $PSDefaultParameterValues["<CmdletName:ParameterName>"]

例如：

       PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
       Server01AB234x5

如何将值添加到 $PSDefaultParameterValues

若要在 $PSDefaultParameterValues 中添加或删除值，请使用用于标准哈希表的方法。

例如，若要向 $PSDefaultParameterValues 添加一个值而不影响现有值，请使用哈希表的 Add 方法。

Add 方法的语法如下所示：

        <HashTable>.Add(Key, Value)

其中键是“<CmdletName>:<ParameterName>”，该值为参数值。

使用以下命令格式在 $PSDefaultParameterValues 上调用 Add 方法。请务必使用逗号 (,) 分隔值中的键，而不是使用等号 (=)。

        $PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")

例如，以下命令会将“PowerShell”添加为 Get-Process cmdlet 的 Name 参数的默认值。

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

以下示例演示了此命令的效果。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

        PS C:\> $PSDefaultParameterValues

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

如何从 $PSDefaultParameterValues 中删除值

若要从 $PSDefaultParameterValues 中删除值，请使用哈希表的 Remove 方法。

Remove 方法的语法如下所示：

        <HashTable>.Remove(Key)

使用以下命令格式在 $PSDefaultParameterValues 上调用 Remove 方法。

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

例如，以下命令将删除 Get-Process cmdlet 的 Name 参数及其值。

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

以下示例演示了此命令的效果。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")

        PS C:\> $PSDefaultParameterValues

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

如何更改 $PSDefaultParameterValues 中的值

若要更改 $PSDefaultParameterValues 中的值，请使用以下命令格式。

        $PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"

以下示例演示了此命令的效果。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
   
        PS C:\> $PSDefaultParameterValues

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

如何禁用和重新启用 $PSDefaultParameterValues

可以暂时禁用 $PSDefaultParameterValues，然后再重新启用。如果你运行的脚本可能采用不同的默认参数值，这将非常有用。

若要禁用 $PSDefaultParameterValues，请添加值为 $True 的“Disabled”键。

例如，

        $PSDefaultParameterValues.Add("Disabled", $true)

        - or -

        $PSDefaultParameterValues[Disabled]=$true

$PSDefaultParameterValues 中的其他值保持不变，但不起作用。

        PS C:\> $PSDefaultParameterValues

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

若要重新启用 $PSDefaultParameterValues，请删除 Disabled 键或将 Disabled 键的值更改为 $False。

        $PSDefaultParameterValues.Remove("Disabled")

- or -

        $PSDefaultParameterValues[Disabled]=$false

$PSDefaultParameterValues 的以前值再次起作用。

关键字

about_PSDefaultParameterValues

about_Parameters_DefaultValues

about_DefaultValues

另请参阅

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks