

ABOUT PARAMETERS DEFAULT VALUES


SHORT DESCRIPTION

Describes how to set custom default values for the parameters of cmdlets
and advanced functions.


LONG DESCRIPTION

The $PSDefaultParameterValues preference variable lets you specify custom
default values for any cmdlet or advanced function. Cmdlets and functions
use the custom default value unless you specify another value in the
command.

The authors of cmdlets and advanced functions set standard default values
for their parameters. Typically, the standard default values are useful,
but they might not be appropriate for all environments.

This feature is especially useful when you must specify the same alternate
parameter value nearly every time you use the command or when a particular
parameter value is difficult to remember, such as an e-mail server name or
project GUID.

If the desired default value varies predictably, you can specify a script
block that provides different default values for a parameter under
different conditions.

$PSDefaultParameterValues was introduced in PowerShell 3.0.


SYNTAX

The syntax of the $PSDefaultParameterValues preference variable is as
follows:

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

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

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

Wildcard characters are permitted in the CmdletName and ParameterName
values.

The value of $PSDefaultParameterValues is a
System.Management.Automation.DefaultParameterDictionary, a type of hash
table that validates the format of keys. Enter a hash table where the key
consists of the cmdlet name and parameter name separated by a colon (:) and
the value is the custom default value.

To set, change, add, or remove entries from $PSDefaultParameterValues, use
the methods that you would use to edit a standard hash table.

The <CmdletName> must be the name of a cmdlet or the name of an advanced
function that uses the CmdletBinding attribute. You cannot use
$PSDefaultParameterValues to specify default values for scripts or simple
functions.

The default value can be an object or a script block. If the value is a
script block, PowerShell evaluates the script block and uses the result as
the parameter value. When the specified parameter takes a script block
value, enclose the script block value in a second set of braces, such as:

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

For information about hash tables, see about_Hash_Tables. For information
about script blocks, see about_Script_Blocks. For information about
preference variables, see about_Preference_Variables.


EXAMPLES

The following command sets a custom default value for the SmtpServer
parameter of the Send-MailMessage cmdlet.

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

To set default values for multiple parameters, use a semi-colon (;) to
separate each Name=Value pair. The following command adds a custom default
value for the LogName parameter of the Get-WinEvent cmdlet.

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

You can use wildcard characters in the name of the cmdlet and parameter.
The following command sets the Verbose common parameter to $true in all
commands. Use $true and $false to set values for switch parameters, such as
VERBOSE.

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

If a parameter takes multiple values (an array), you can set multiple
values as the default value. The following command sets the default value
of the COMPUTERNAME parameter of the Invoke-Command cmdlet to “Server01”
and “Server02”.

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

You can use a script block to specify different default values for a
parameter under different conditions. PowerShell evaluates the script block
and uses the result as the default parameter value.

The following command sets the default value of the Autosize parameter of
the Format-Table cmdlet to $true when the host program is the PowerShell
console.

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

If a parameter takes a script block value, enclose the script block in an
extra set of braces. When PowerShell evaluates the outer script block, the
result is the inner script block, which is set as the default parameter
value.

The following command sets the default value of the ScriptBlock parameter
of Invoke-Command. Because the script block is enclosed in a second set of
braces, the enclosed script block is passed to the Invoke-Command cmdlet.

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

HOW TO SET $PSDefaultParameterValues

$PSDefaultParameterValues is a preference variable, so it exists only in
the session in which it is set. It has no default value.

To set $PSDefaultParameterValues, type the variable name and one or more
key-value pairs at the command line.

If you type another $PSDefaultParameterValues command, its value replaces
the original value. The original is not retained.

To save $PSDefaultParameterValues for future sessions, add a
$PSDefaultParameterValues command to your PowerShell profile. For more
information, see about_Profiles.

HOW TO GET $PSDefaultParameterValues

To get the value of $PSDefaultParameterValues, at the command prompt, type:

    $PSDefaultParameterValues

For example, the first command sets the value of $PSDefaultParameterValues.
The second command gets the value of $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

To get the value of a <CmdletName:ParameterName> key, use the following
command syntax:

    $PSDefaultParameterValues["<CmdletName:ParameterName>"]

For example:

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

HOW TO ADD VALUES TO PSDefaultParameterValues

To add or remove values from $PSDefaultParameterValues, use the methods
that you would use for a standard hash table.

For example, to add a value to $PSDefaultParameterValues without affecting
the existing values, use the Add method of hash tables.

The syntax of the Add method is as follows:

    <HashTable>.Add(Key, Value)

where the Key is “:” and the value is the parameter value.

Use the following command format to call the Add method on
$PSDefaultParameterValues. Be sure to use a comma (,) to separate the key
from the value, instead of the equal sign (=).

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

For example, the following command adds “PowerShell” as the default value
of the Name parameter of the Get-Process cmdlet.

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

The following example shows the effect of this command.

    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

HOW TO REMOVE VALUES FROM $PSDefaultParameterValues

To remove a value from $PSDefaultParameterValues, use the Remove method of
hash tables.

The syntax of the Remove method is as follows:

    <HashTable>.Remove(Key)

Use the following command format to call the Remove method on
$PSDefaultParameterValues.

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

For example, the following command removes the Name parameter of the
Get-Process cmdlet and its values.

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

The following example shows the effect of this command.

    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

HOW TO CHANGE VALUES IN $PSDefaultParameterValues

To change a value in $PSDefaultParameterValues, use the following command
format.

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

The following example shows the effect of this command.

    $PSDefaultParameterValues

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

    $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"

    $PSDefaultParameterValues

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

HOW TO DISABLE AND RE-ENABLE $PSDefaultParameterValues

You can temporarily disable and then re-enable $PSDefaultParameterValues.
This is very useful if you’re running scripts that might assume different
default parameter values.

To disable $PSDefaultParameterValues, add a key of “Disabled” with a value
of $True.

For example,

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

-   or -

    $PSDefaultParameterValues[Disabled]=$true

The other values in $PSDefaultParameterValues are preserved, but not
effective.

    PS C:\> $PSDefaultParameterValues

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

To re-enable $PSDefaultParameterValues, remove the Disabled key or change
the value of the Disabled key to $False.

    $PSDefaultParameterValues.Remove("Disabled")

-   or -

    $PSDefaultParameterValues[Disabled]=$false

The previous value of $PSDefaultParameterValues is effective again.


KEYWORDS

about_PSDefaultParameterValues

about_Parameters_DefaultValues

about_DefaultValues


SEE ALSO

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks
