About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers
 

about_Parameters_Default_Values

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