Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

about_Parameters_Default_Values

Updated: October 17, 2013

Applies To: Windows PowerShell 3.0, Windows PowerShell 4.0

TOPIC
    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 Windows 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, Windows 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. Windows 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 Windows 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 Windows 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 Windows 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 "<CmdletName>:<ParameterName>" 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.

        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


 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



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.