From cab343913dd2372fe6c37afa6242f57b70340ce9 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 2 Jan 2025 08:54:30 -0600 Subject: [PATCH 1/3] Update monthly stats (#11620) --- .../docs-conceptual/community/2024-updates.md | 45 ++++++++++++++++++- .../docs-conceptual/community/hall-of-fame.md | 23 +++++----- 2 files changed, 56 insertions(+), 12 deletions(-) diff --git a/reference/docs-conceptual/community/2024-updates.md b/reference/docs-conceptual/community/2024-updates.md index 810ffe26e49a..945f8198c8db 100644 --- a/reference/docs-conceptual/community/2024-updates.md +++ b/reference/docs-conceptual/community/2024-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2024 -ms.date: 11/04/2024 +ms.date: 01/02/2025 title: What's New in PowerShell-Docs for 2024 --- # What's new in PowerShell Docs for 2024 @@ -11,6 +11,49 @@ community. Help us make the documentation better for you. Read the [Contributor's Guide][01] to learn how to get started. +## 2024-December + +- Added [about_Type_Conversion](/powershell/module/microsoft.powershell.core/about/about_type_conversion) +- Updated and improved documentation for several PSScriptAnalyzer rules + - [AvoidDefaultValueSwitchParameter](/powershell/utility-modules/psscriptanalyzer/rules/avoiddefaultvalueswitchparameter) + - [AvoidGlobalFunctions](/powershell/utility-modules/psscriptanalyzer/rules/avoidglobalfunctions) + - [AvoidOverwritingBuiltInCmdlets](/powershell/utility-modules/psscriptanalyzer/rules/avoidoverwritingbuiltincmdlets) + - [AvoidUsingCmdletAliases](/powershell/utility-modules/psscriptanalyzer/rules/avoidusingcmdletaliases) + - [AvoidUsingWriteHost](/powershell/utility-modules/psscriptanalyzer/rules/avoidusingwritehost) + - [PlaceOpenBrace](/powershell/utility-modules/psscriptanalyzer/rules/placeopenbrace) + - [PossibleIncorrectComparisonWithNull](/powershell/utility-modules/psscriptanalyzer/rules/possibleincorrectcomparisonwithnull) + - [PossibleIncorrectUsageOfAssignmentOperator](/powershell/utility-modules/psscriptanalyzer/rules/possibleincorrectusageofassignmentoperator) + - [ProvideCommentHelp](/powershell/utility-modules/psscriptanalyzer/rules/providecommenthelp) + - [UseApprovedVerbs](/powershell/utility-modules/psscriptanalyzer/rules/useapprovedverbs) + - [UseCompatibleCmdlets](/powershell/utility-modules/psscriptanalyzer/rules/usecompatiblecmdlets) + - [UseCompatibleCommands](/powershell/utility-modules/psscriptanalyzer/rules/usecompatiblecommands) + - [UseCompatibleTypes](/powershell/utility-modules/psscriptanalyzer/rules/usecompatibletypes) + - [UseShouldProcessForStateChangingFunctions](/powershell/utility-modules/psscriptanalyzer/rules/useshouldprocessforstatechangingfunctions) + - [UseSupportsShouldProcess](/powershell/utility-modules/psscriptanalyzer/rules/usesupportsshouldprocess) + +### Top Community Contributors + +GitHub stats + +- 22 PRs merged (7 from Community) +- 30 issues opened (30 from Community) +- 24 issues closed (24 Community issues closed) + +The following people contributed to PowerShell docs this month by submitting pull requests or +filing issues. Thank you! + +| GitHub Id | PRs merged | Issues opened | +| ------------------ | :--------: | :-----------: | +| sethvs | 3 | | +| ArieHein | 1 | | +| bharathalleni | 1 | | +| jhribal | 1 | | +| Saibamen | 1 | | +| skycommand | 1 | | +| surfingoldelephant | | 6 | +| ArmaanMcleod | | 2 | +| dpareit | | 2 | + ## 2024-November New and updated content diff --git a/reference/docs-conceptual/community/hall-of-fame.md b/reference/docs-conceptual/community/hall-of-fame.md index 1f2b41b7d955..95aa5c8506e6 100644 --- a/reference/docs-conceptual/community/hall-of-fame.md +++ b/reference/docs-conceptual/community/hall-of-fame.md @@ -1,6 +1,6 @@ --- description: List of the GitHub users that have the most contributions to the PowerShell-Doc project. -ms.date: 12/02/2024 +ms.date: 01/02/2025 title: Community contributor Hall of Fame --- # Community Contributor Hall of Fame @@ -17,27 +17,27 @@ Pull Requests help us fix those issues and make the documentation better for eve | PRs Merged | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | Grand Total | | --------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 194 | 446 | 467 | 321 | 161 | 100 | 121 | 108 | 74 | 1995 | +| Community | 3 | 194 | 446 | 467 | 321 | 161 | 100 | 122 | 108 | 81 | 2003 | | matt9ucci | | | 157 | 80 | 30 | 1 | 6 | | | | 274 | | nschonni | | | | 14 | 138 | 10 | | | | | 162 | | kiazhi | | 25 | 79 | 12 | | | | | | | 116 | | alexandair | | 57 | 7 | 26 | 2 | 1 | | | | | 93 | -| sethvs | | | 1 | 44 | | 20 | 1 | 10 | | 3 | 79 | +| sethvs | | | 1 | 44 | | 20 | 1 | 10 | | 6 | 82 | | doctordns | | 5 | 32 | 20 | 7 | 9 | 5 | | 1 | | 79 | | ehmiiz | | | | | | | | 22 | 14 | | 36 | | yecril71pl | | | | | | 21 | 3 | 3 | | | 27 | | Dan1el42 | | 20 | | | | | | | | | 20 | -| skycommand | | | 1 | 3 | 3 | 6 | | 1 | 4 | | 18 | +| skycommand | | | 1 | 3 | 3 | 6 | | 1 | 4 | 1 | 19 | | NReilingh | | 2 | | 13 | 3 | | | | | | 18 | | it-praktyk | | | | 16 | 1 | | | | | | 17 | | vors | | 15 | 1 | | | | | | | | 16 | -| kvprasoon | | 2 | 1 | 7 | 2 | 2 | 2 | | | | 16 | | markekraus | | | 11 | 5 | | | | | | | 16 | -| purdo17 | | | | 13 | | | | | | | 13 | +| kvprasoon | | 2 | 1 | 7 | 2 | 2 | 2 | | | | 16 | | k-takai | | | | 5 | 1 | 7 | | | | | 13 | +| purdo17 | | | | 13 | | | | | | | 13 | +| PlagueHO | | 10 | | | 1 | | | | | | 11 | | bergmeister | | | 1 | 3 | 3 | 1 | 1 | 1 | 1 | | 11 | | exchange12rocks | | | 7 | 3 | | | 1 | | | | 11 | -| PlagueHO | | 10 | | | 1 | | | | | | 11 | ## GitHub issues opened @@ -45,8 +45,8 @@ GitHub issues help us identify errors and gaps in our documentation. | Issues Opened | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | Grand Total | | --------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 54 | 95 | 212 | 561 | 558 | 364 | 225 | 270 | 200 | 2542 | -| mklement0 | | | 19 | 60 | 56 | 61 | 28 | 8 | 20 | 23 | 275 | +| Community | 3 | 54 | 95 | 211 | 561 | 557 | 364 | 225 | 270 | 224 | 2564 | +| mklement0 | | | 19 | 60 | 56 | 61 | 28 | 8 | 20 | 24 | 276 | | ehmiiz | | | | | | | | 20 | 14 | | 34 | | iSazonov | | | 1 | 4 | 10 | 8 | 4 | 3 | | 1 | 31 | | jszabo98 | | | | 2 | 15 | 6 | 1 | | 1 | 2 | 27 | @@ -66,10 +66,11 @@ GitHub issues help us identify errors and gaps in our documentation. | jsilverm | | | | | | 8 | | | 4 | | 12 | | CarloToso | | | | | | | | | 11 | | 11 | | Liturgist | | | | | 1 | 1 | 1 | 2 | 4 | 2 | 11 | -| vors | 1 | 6 | 2 | 1 | | | | | | | 10 | +| ArmaanMcleod | | | | | | | | | 4 | 6 | 10 | | UberKluger | | | | | | 1 | 7 | 2 | | | 10 | -| LaurentDardenne | | | 3 | 2 | | | | 5 | | | 10 | +| vors | 1 | 6 | 2 | 1 | | | | | | | 10 | | matt9ucci | | | 2 | 5 | | | 2 | | 1 | | 10 | +| LaurentDardenne | | | 3 | 2 | | | | 5 | | | 10 | [contrib]: contributing/overview.md From 2da27da84d31d6f83416249c616fdd5dafd805b9 Mon Sep 17 00:00:00 2001 From: Arie Heinrich Date: Thu, 2 Jan 2025 15:58:24 +0100 Subject: [PATCH 2/3] add additional words to dictionary (#11619) --- .vscode/cspell/psdocs/dictionaries/psdocs.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.vscode/cspell/psdocs/dictionaries/psdocs.txt b/.vscode/cspell/psdocs/dictionaries/psdocs.txt index 075b049c38c7..5220b96fed4d 100644 --- a/.vscode/cspell/psdocs/dictionaries/psdocs.txt +++ b/.vscode/cspell/psdocs/dictionaries/psdocs.txt @@ -87,6 +87,7 @@ documentationcenter DPAPI DWORD endianness +Entra Etag Etags eventlog @@ -130,6 +131,7 @@ JavaScript Kerberos keypress keypresses +keyvault Kubernetes LASTEXITCODE LCID @@ -164,6 +166,7 @@ parameterless PassThru PATHEXT pbpaste +platyps pltfrm POSIX PowerShell @@ -198,6 +201,7 @@ QWORD Raspbian Recurse recurses +regedit rehost rehosting rehosts @@ -227,6 +231,8 @@ Sddl SDII SDKs sdwheeler +secretmanagement +secretstore setext sewhee SIEM From 988951152a6ccd79cabeaf5e3933d27812fd6483 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 2 Jan 2025 14:29:41 -0600 Subject: [PATCH 3/3] Fixes #11604 - Clarify $PSDefaultParameterValues works with command that use CmdletBinding (#11621) * Clarify $PSDefaultParameterValues works with command that use CmdletBinding * fix typo --- .../About/about_Parameters_Default_Values.md | 394 +++++++----------- .../About/about_Parameters_Default_Values.md | 394 +++++++----------- .../About/about_Parameters_Default_Values.md | 394 +++++++----------- 3 files changed, 426 insertions(+), 756 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 80725362633e..a41fa093446e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,7 +1,7 @@ --- description: Describes how to set custom default values for cmdlet parameters and advanced functions. Locale: en-US -ms.date: 05/31/2019 +ms.date: 01/02/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parameters_default_values?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Parameters_Default_Values @@ -10,202 +10,134 @@ title: about_Parameters_Default_Values ## Short description -Describes how to set custom default values for cmdlet parameters and advanced -functions. +Describes how to set custom default values for cmdlet parameters, advanced +functions, and scripts. ## Long description The `$PSDefaultParameterValues` preference variable lets you specify custom -default values for any cmdlet or advanced function. Cmdlets and advanced -functions use the custom default value unless you specify another value in the -command. +default parameter values for any cmdlet, advanced function, or script that uses +the **CmdletBinding** attribute. The defined values are used unless you specify +other values on the command line. -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 useful in the following scenarios: -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 email server name or -project GUID. +- specifying the same parameter value every time you use the command +- specifying a particular parameter value that's difficult to remember, such as + an email 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. +The `$PSDefaultParameterValues` variable has no default value. To save the +settings for use in future sessions, add the variable assignment to your +PowerShell profile. `$PSDefaultParameterValues` was introduced in PowerShell 3.0. ## Syntax -The `$PSDefaultParameterValues` variable is a hash table that validates the -format of keys as an object type of -**System.Management.Automation.DefaultParameterDictionary**. The hash table -contains **Key/Value** pairs. A **Key** is in the format -`CmdletName:ParameterName`. A **Value** is the **DefaultValue** or -**ScriptBlock** assigned to the key. +The `$PSDefaultParameterValues` variable is an object type of +**System.Management.Automation.DefaultParameterDictionary**. The +**DefaultParameterDictionary** type is a hashtable with some extra validation +for the format of the keys. The hashtable contains key-value pairs where: -The syntax of the `$PSDefaultParameterValues` preference variable is as -follows: +- the _key_ has the format `CommandName:ParameterName` +- the _value_ is default value for the parameter or a **ScriptBlock** that + returns the default value -``` -$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"} - -$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} } - -$PSDefaultParameterValues["Disabled"]=$True | $False -``` - -Wildcard characters are permitted in the **CmdletName** and **ParameterName** -values. - -To set, change, add, or remove a specific **Key/Value** pair from -`$PSDefaultParameterValues`, use the methods to edit a standard hash table. For -example, the **Add** and **Remove** methods. These methods don't overwrite -other values in the hash table. +For the _key_, the **CommandName** must be the name of a cmdlet, advanced +function, or script file that uses the **CmdletBinding** attribute. The script +name must match the name as reported by +`(Get-Command -Name .\script.ps1).Name`. -There's another syntax that doesn't overwrite an existing -`$PSDefaultParameterValues` hash table. To add or change a specific -**Key/Value** pair, use the following syntax: +> [!NOTE] +> PowerShell doesn't prevent you from specifying an alias for the +> **CommandName**. However, there are cases where the definition is ignored or +> causes an error. You should avoid defining default values for command +> aliases. -``` -$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` - -The **CmdletName** must be the name of a cmdlet or the name of an advanced -function that uses the **CmdletBinding** attribute. You can't use -`$PSDefaultParameterValues` to specify default values for scripts or simple -functions. +The _value_ can be an object of a type that's compatible with the parameter or +a **ScriptBlock** that returns such a value. When the value is a script block, +PowerShell evaluates the script block and uses the result for the parameter +value. If the specified parameter expects a **ScriptBlock** type, you must +enclose the value in another set of braces. When PowerShell evaluates the outer +**ScriptBlock**, the result is the inner **ScriptBlock**. The inner +**ScriptBlock** becomes the new default parameter value. -The **DefaultValue** 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 accepts a script block value, -enclose the script block value in a second set of braces, such as: +For example: ```powershell -$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-Process} } +} ``` -For more information, see the following documents: - -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Preference_Variables](about_Preference_Variables.md) - ## Examples -### How to set \$PSDefaultParameterValues - -`$PSDefaultParameterValues` is a preference variable, so it exists only in the -session in which it's set. It has no default value. - -To set `$PSDefaultParameterValues`, type the variable name and one or more -**Key/Value** pairs. If you run another `$PSDefaultParameterValues` command, it -overwrites the existing hash table. +Use the `Add()` and `Remove()` methods to add or remove a specific key-value +pair from `$PSDefaultParameterValues` without overwriting other existing +key-value pairs. -For examples about how to change **Key/Value** pairs without overwriting -existing hash table values, see -[How to add values to \$PSDefaultParameterValues](#how-to-add-values-to-psdefaultparametervalues) -or -[How to change values in \$PSDefaultParameterValues](#how-to-change-values-in-psdefaultparametervalues). - -To save `$PSDefaultParameterValues` for future sessions, add a -`$PSDefaultParameterValues` command to your PowerShell profile. For more -information, see [about_Profiles](about_Profiles.md). - -#### Set a custom default value +```powershell +$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue') +$PSDefaultParameterValues.Remove('CmdletName:ParameterName') +``` -The **Key/Value** pair sets the `Send-MailMessage:SmtpServer` key to a custom -default value of **Server123**. +Use indexing or member access to change the value of an existing key-value +pair. For example: ```powershell -$PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" -} +$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2' +$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1' ``` -#### Set default values for multiple parameters +### Assign values to `$PSDefaultParameterValues` -To set default values for multiple parameters, separate each **Key/Value** pair -with a semicolon (`;`). The `Send-MailMessage:SmtpServer` and -`Get-WinEvent:LogName` keys are set to custom default values. +To define default values for cmdlet parameters, assign a hashtable containing +the appropriate key-value pairs to the `$PSDefaultParameterValues` variable. +The hashtable can contain multiple key-value pairs. This example sets default +values for the `Send-MailMessage:SmtpServer` and `Get-WinEvent:LogName` keys. ```powershell $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + 'Send-MailMessage:SmtpServer'='Server123' + 'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational' } ``` -#### Use wildcards and switch parameters - -The cmdlet and parameter names can contain wildcard characters. Use `$True` and -`$False` to set values for switch parameters, such as **Verbose**. The common -parameter's **Verbose** parameter is set to `$True` for all commands. +The cmdlet and parameter names can contain wildcard characters. Use `$true` and +`$false` to set values for switch parameters, such as **Verbose**. This example +sets the common parameter **Verbose** to `$true` for all commands. ```powershell -$PSDefaultParameterValues = @{"*:Verbose"=$True} +$PSDefaultParameterValues = @{'*:Verbose'=$true} ``` -#### Use an array for the default value - -If a parameter can accept multiple values, an array, you can set multiple -values as the default values. The default value of the -`Invoke-Command:ComputerName` key is set to an array value of **Server01** and -**Server02**. +If a parameter accepts multiple values, you can provide multiple default values +using an array. This example sets the default value of the +`Invoke-Command:ComputerName` key to an array containing the string values +`Server01` and `Server02`. ```powershell $PSDefaultParameterValues = @{ - "Invoke-Command:ComputerName"="Server01","Server02" + 'Invoke-Command:ComputerName' = 'Server01','Server02' } ``` -#### Use a script block +### View defined values -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 `Format-Table:AutoSize` key sets that switch parameter to a default value -of **True**. The `If` statement contains a condition that the `$host.Name` must -be the PowerShell console, **ConsoleHost**. +Consider the following definition of `$PSDefaultParameterValues`: ```powershell -$PSDefaultParameterValues=@{ - "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}} +$PSDefaultParameterValues = @{ + 'Send-MailMessage:SmtpServer' = 'Server123' + 'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational' + 'Get-*:Verbose' = $true } ``` -If a parameter accepts 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, and that is set as the default parameter -value. - -The `Invoke-Command:ScriptBlock` key set to a default value of the **System -event log** because the script block is enclosed in a second set of braces. The -result of the script block is passed to the `Invoke-Command` cmdlet. +You can view the defined values by entering `$PSDefaultParameterValues` at the +command prompt. ```powershell -$PSDefaultParameterValues=@{ - "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} -} -``` - -### How to get \$PSDefaultParameterValues - -The hash table values are displayed by entering `$PSDefaultParameterValues` at -the PowerShell prompt. - -A `$PSDefaultParameterValues` hash table is set with three **Key/Value** pairs. -This hash table is used in the following examples that describe how to add, -change, and remove values from `$PSDefaultParameterValues`. - -``` -PS> $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" - "Get-*:Verbose"=$True -} - PS> $PSDefaultParameterValues Name Value @@ -215,50 +147,56 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -To get the value of a specific `CmdletName:ParameterName` key, use the -following syntax: - -``` -$PSDefaultParameterValues["CmdletName:ParameterName"] -``` +You can use indexing or member access to get a specific value. -For example, to get the value for the `Send-MailMessage:SmtpServer` key. - -``` -PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation Server123 +PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation +True ``` -### How to add values to \$PSDefaultParameterValues +### Use a script block for the default value -To add a value to `$PSDefaultParameterValues`, use the **Add** method. Adding a -value doesn't affect the hash table's existing values. +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. -Use a comma (`,`) to separate the **Key** from the **Value**. The following -syntax shows how to use the **Add** method for `$PSDefaultParameterValues`. +The `Format-Table:AutoSize` key sets that switch parameter to a default value +of `$true` The `if` statement contains a condition that the `$Host.Name` must +be `ConsoleHost`. -``` -PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue") +```powershell +$PSDefaultParameterValues = @{ + 'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} } +} ``` -The hash table created in the prior example is updated with a new **Key/Value** -pair. The **Add** method sets the `Get-Process:Name` key to the value -**PowerShell**. +If a parameter accepts a **ScriptBlock** value, enclose the **ScriptBlock** in +another set of braces. When PowerShell evaluates the outer **ScriptBlock**, the +result is the inner **ScriptBlock**. The inner **ScriptBlock** becomes the new +default parameter value. ```powershell -$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} } +} ``` -The following syntax accomplishes the same result. +### Add values to an existing `$PSDefaultParameterValues` variable + +To add a value to `$PSDefaultParameterValues`, use the `Add()` method. Adding a +value doesn't affect the hashtable's existing values. Use a comma (`,`) to +separate the _key_ from the _value_. ```powershell -$PSDefaultParameterValues["Get-Process:Name"]="PowerShell" +$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell') ``` -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was added. +The hashtable created in the prior example is updated with a new key-value +pair. -``` +```powershell PS> $PSDefaultParameterValues Name Value @@ -269,31 +207,15 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to remove values from \$PSDefaultParameterValues - -To remove a value from `$PSDefaultParameterValues`, use the **Remove** method -of hash tables. Removing a value doesn't affect the hash table's existing -values. +### Remove a value from `$PSDefaultParameterValues` -The following syntax shows how to use the **Remove** method on -`$PSDefaultParameterValues`. +To remove a value from `$PSDefaultParameterValues`, use the `Remove()` method. +Removing a value doesn't affect the hashtable's existing values. -``` -PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName") -``` - -In this example, the hash table created in the prior example is updated to -remove a **Key/Value** pair. The **Remove** method removes the -`Get-Process:Name` key. +This example removes the key-value pair that was added in the previous example. ```powershell -$PSDefaultParameterValues.Remove("Get-Process:Name") -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was removed. - -``` +PS> $PSDefaultParameterValues.Remove('Get-Process:Name') PS> $PSDefaultParameterValues Name Value @@ -303,28 +225,14 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to change values in \$PSDefaultParameterValues - -Changes to a specific value don't affect existing hash table values. To change -a specific **Key/Value** pair in `$PSDefaultParameterValues`, use the following -syntax: - -``` -PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` +### Change a value in `$PSDefaultParameterValues` -In this example, the hash table created in the prior example is updated to -change a **Key/Value** pair. The following command changes the -`Send-MailMessage:SmtpServer` key to a new value of **ServerXYZ**. +Use indexing or member access to change the default value of an existing +key-value pair. In this example, the default value for the +`Send-MailMessage:SmtpServer` key is changed to a new value of **ServerXYZ**. ```powershell -$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ" -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Send-MailMessage:SmtpServer` key was changed to a new value. - -``` +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ' PS> $PSDefaultParameterValues Name Value @@ -334,30 +242,18 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -### How to disable and re-enable \$PSDefaultParameterValues +### Disable or re-enable `$PSDefaultParameterValues` You can temporarily disable and then re-enable `$PSDefaultParameterValues`. Disabling `$PSDefaultParameterValues` is useful if you're running scripts that need different default parameter values. To disable `$PSDefaultParameterValues`, add a key of `Disabled` with a value of -**True**. The values in `$PSDefaultParameterValues` are preserved, but aren't -effective. - -``` -PS> $PSDefaultParameterValues.Add("Disabled", $True) -``` +`$true`. The values in `$PSDefaultParameterValues` are preserved, but aren't +used. -The following syntax accomplishes the same result. - -``` -PS> $PSDefaultParameterValues["Disabled"]=$True -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table with -the value for the `Disabled` key. - -``` +```powershell +PS> $PSDefaultParameterValues.Add('Disabled', $true) PS> $PSDefaultParameterValues Name Value @@ -368,26 +264,11 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -To re-enable `$PSDefaultParameterValues`, remove the **Disabled** key or change -the value of the **Disabled** key to `$False`. The previous value of -`$PSDefaultParameterValues` is effective again. - -``` -PS> $PSDefaultParameterValues.Remove("Disabled") -``` - -The following syntax accomplishes the same result. +To re-enable `$PSDefaultParameterValues`, remove the `Disabled` key or change +the value of the `Disabled` key to `$false`. -``` -PS> $PSDefaultParameterValues["Disabled"]=$False -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. When -the **Remove** method is used, the `Disabled` key is removed from the output. -If the alternate syntax was used to re-enable `$PSDefaultParameterValues`, the -`Disabled` key is displayed as **False**. - -``` +```powershell +PS> $PSDefaultParameterValues.Disabled = $false PS> $PSDefaultParameterValues Name Value @@ -400,10 +281,19 @@ Send-MailMessage:SmtpServer ServerXYZ ## See also -- [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216) -- [about_Functions_Advanced](about_Functions_Advanced.md) -- [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Preference_Variables](about_Preference_Variables.md) -- [about_Profiles](about_Profiles.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_CommonParameters][01] +- [about_Functions_Advanced][02] +- [about_Functions_CmdletBindingAttribute][03] +- [about_Hash_Tables][04] +- [about_Preference_Variables][05] +- [about_Profiles][06] +- [about_Script_Blocks][07] + + +[01]: about_CommonParameters.md +[02]: about_Functions_Advanced.md +[03]: about_Functions_CmdletBindingAttribute.md +[04]: about_Hash_Tables.md +[05]: about_Preference_Variables.md +[06]: about_Profiles.md +[07]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 2abdcff201da..dd58344236d3 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,7 +1,7 @@ --- description: Describes how to set custom default values for cmdlet parameters and advanced functions. Locale: en-US -ms.date: 05/31/2019 +ms.date: 01/02/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parameters_default_values?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Parameters_Default_Values @@ -10,202 +10,134 @@ title: about_Parameters_Default_Values ## Short description -Describes how to set custom default values for cmdlet parameters and advanced -functions. +Describes how to set custom default values for cmdlet parameters, advanced +functions, and scripts. ## Long description The `$PSDefaultParameterValues` preference variable lets you specify custom -default values for any cmdlet or advanced function. Cmdlets and advanced -functions use the custom default value unless you specify another value in the -command. +default parameter values for any cmdlet, advanced function, or script that uses +the **CmdletBinding** attribute. The defined values are used unless you specify +other values on the command line. -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 useful in the following scenarios: -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 email server name or -project GUID. +- specifying the same parameter value every time you use the command +- specifying a particular parameter value that's difficult to remember, such as + an email 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. +The `$PSDefaultParameterValues` variable has no default value. To save the +settings for use in future sessions, add the variable assignment to your +PowerShell profile. `$PSDefaultParameterValues` was introduced in PowerShell 3.0. ## Syntax -The `$PSDefaultParameterValues` variable is a hash table that validates the -format of keys as an object type of -**System.Management.Automation.DefaultParameterDictionary**. The hash table -contains **Key/Value** pairs. A **Key** is in the format -`CmdletName:ParameterName`. A **Value** is the **DefaultValue** or -**ScriptBlock** assigned to the key. +The `$PSDefaultParameterValues` variable is an object type of +**System.Management.Automation.DefaultParameterDictionary**. The +**DefaultParameterDictionary** type is a hashtable with some extra validation +for the format of the keys. The hashtable contains key-value pairs where: -The syntax of the `$PSDefaultParameterValues` preference variable is as -follows: +- the _key_ has the format `CommandName:ParameterName` +- the _value_ is default value for the parameter or a **ScriptBlock** that + returns the default value -``` -$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"} - -$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} } - -$PSDefaultParameterValues["Disabled"]=$True | $False -``` - -Wildcard characters are permitted in the **CmdletName** and **ParameterName** -values. - -To set, change, add, or remove a specific **Key/Value** pair from -`$PSDefaultParameterValues`, use the methods to edit a standard hash table. For -example, the **Add** and **Remove** methods. These methods don't overwrite -other values in the hash table. +For the _key_, the **CommandName** must be the name of a cmdlet, advanced +function, or script file that uses the **CmdletBinding** attribute. The script +name must match the name as reported by +`(Get-Command -Name .\script.ps1).Name`. -There's another syntax that doesn't overwrite an existing -`$PSDefaultParameterValues` hash table. To add or change a specific -**Key/Value** pair, use the following syntax: +> [!NOTE] +> PowerShell doesn't prevent you from specifying an alias for the +> **CommandName**. However, there are cases where the definition is ignored or +> causes an error. You should avoid defining default values for command +> aliases. -``` -$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` - -The **CmdletName** must be the name of a cmdlet or the name of an advanced -function that uses the **CmdletBinding** attribute. You can't use -`$PSDefaultParameterValues` to specify default values for scripts or simple -functions. +The _value_ can be an object of a type that's compatible with the parameter or +a **ScriptBlock** that returns such a value. When the value is a script block, +PowerShell evaluates the script block and uses the result for the parameter +value. If the specified parameter expects a **ScriptBlock** type, you must +enclose the value in another set of braces. When PowerShell evaluates the outer +**ScriptBlock**, the result is the inner **ScriptBlock**. The inner +**ScriptBlock** becomes the new default parameter value. -The **DefaultValue** 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 accepts a script block value, -enclose the script block value in a second set of braces, such as: +For example: ```powershell -$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-Process} } +} ``` -For more information, see the following documents: - -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Preference_Variables](about_Preference_Variables.md) - ## Examples -### How to set \$PSDefaultParameterValues - -`$PSDefaultParameterValues` is a preference variable, so it exists only in the -session in which it's set. It has no default value. - -To set `$PSDefaultParameterValues`, type the variable name and one or more -**Key/Value** pairs. If you run another `$PSDefaultParameterValues` command, it -overwrites the existing hash table. +Use the `Add()` and `Remove()` methods to add or remove a specific key-value +pair from `$PSDefaultParameterValues` without overwriting other existing +key-value pairs. -For examples about how to change **Key/Value** pairs without overwriting -existing hash table values, see -[How to add values to \$PSDefaultParameterValues](#how-to-add-values-to-psdefaultparametervalues) -or -[How to change values in \$PSDefaultParameterValues](#how-to-change-values-in-psdefaultparametervalues). - -To save `$PSDefaultParameterValues` for future sessions, add a -`$PSDefaultParameterValues` command to your PowerShell profile. For more -information, see [about_Profiles](about_Profiles.md). - -#### Set a custom default value +```powershell +$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue') +$PSDefaultParameterValues.Remove('CmdletName:ParameterName') +``` -The **Key/Value** pair sets the `Send-MailMessage:SmtpServer` key to a custom -default value of **Server123**. +Use indexing or member access to change the value of an existing key-value +pair. For example: ```powershell -$PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" -} +$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2' +$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1' ``` -#### Set default values for multiple parameters +### Assign values to `$PSDefaultParameterValues` -To set default values for multiple parameters, separate each **Key/Value** pair -with a semicolon (`;`). The `Send-MailMessage:SmtpServer` and -`Get-WinEvent:LogName` keys are set to custom default values. +To define default values for cmdlet parameters, assign a hashtable containing +the appropriate key-value pairs to the `$PSDefaultParameterValues` variable. +The hashtable can contain multiple key-value pairs. This example sets default +values for the `Send-MailMessage:SmtpServer` and `Get-WinEvent:LogName` keys. ```powershell $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + 'Send-MailMessage:SmtpServer'='Server123' + 'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational' } ``` -#### Use wildcards and switch parameters - -The cmdlet and parameter names can contain wildcard characters. Use `$True` and -`$False` to set values for switch parameters, such as **Verbose**. The common -parameter's **Verbose** parameter is set to `$True` for all commands. +The cmdlet and parameter names can contain wildcard characters. Use `$true` and +`$false` to set values for switch parameters, such as **Verbose**. This example +sets the common parameter **Verbose** to `$true` for all commands. ```powershell -$PSDefaultParameterValues = @{"*:Verbose"=$True} +$PSDefaultParameterValues = @{'*:Verbose'=$true} ``` -#### Use an array for the default value - -If a parameter can accept multiple values, an array, you can set multiple -values as the default values. The default value of the -`Invoke-Command:ComputerName` key is set to an array value of **Server01** and -**Server02**. +If a parameter accepts multiple values, you can provide multiple default values +using an array. This example sets the default value of the +`Invoke-Command:ComputerName` key to an array containing the string values +`Server01` and `Server02`. ```powershell $PSDefaultParameterValues = @{ - "Invoke-Command:ComputerName"="Server01","Server02" + 'Invoke-Command:ComputerName' = 'Server01','Server02' } ``` -#### Use a script block +### View defined values -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 `Format-Table:AutoSize` key sets that switch parameter to a default value -of **True**. The `If` statement contains a condition that the `$host.Name` must -be the PowerShell console, **ConsoleHost**. +Consider the following definition of `$PSDefaultParameterValues`: ```powershell -$PSDefaultParameterValues=@{ - "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}} +$PSDefaultParameterValues = @{ + 'Send-MailMessage:SmtpServer' = 'Server123' + 'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational' + 'Get-*:Verbose' = $true } ``` -If a parameter accepts 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, and that is set as the default parameter -value. - -The `Invoke-Command:ScriptBlock` key set to a default value of the **System -event log** because the script block is enclosed in a second set of braces. The -result of the script block is passed to the `Invoke-Command` cmdlet. +You can view the defined values by entering `$PSDefaultParameterValues` at the +command prompt. ```powershell -$PSDefaultParameterValues=@{ - "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} -} -``` - -### How to get \$PSDefaultParameterValues - -The hash table values are displayed by entering `$PSDefaultParameterValues` at -the PowerShell prompt. - -A `$PSDefaultParameterValues` hash table is set with three **Key/Value** pairs. -This hash table is used in the following examples that describe how to add, -change, and remove values from `$PSDefaultParameterValues`. - -``` -PS> $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" - "Get-*:Verbose"=$True -} - PS> $PSDefaultParameterValues Name Value @@ -215,50 +147,56 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -To get the value of a specific `CmdletName:ParameterName` key, use the -following syntax: - -``` -$PSDefaultParameterValues["CmdletName:ParameterName"] -``` +You can use indexing or member access to get a specific value. -For example, to get the value for the `Send-MailMessage:SmtpServer` key. - -``` -PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation Server123 +PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation +True ``` -### How to add values to \$PSDefaultParameterValues +### Use a script block for the default value -To add a value to `$PSDefaultParameterValues`, use the **Add** method. Adding a -value doesn't affect the hash table's existing values. +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. -Use a comma (`,`) to separate the **Key** from the **Value**. The following -syntax shows how to use the **Add** method for `$PSDefaultParameterValues`. +The `Format-Table:AutoSize` key sets that switch parameter to a default value +of `$true` The `if` statement contains a condition that the `$Host.Name` must +be `ConsoleHost`. -``` -PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue") +```powershell +$PSDefaultParameterValues = @{ + 'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} } +} ``` -The hash table created in the prior example is updated with a new **Key/Value** -pair. The **Add** method sets the `Get-Process:Name` key to the value -**PowerShell**. +If a parameter accepts a **ScriptBlock** value, enclose the **ScriptBlock** in +another set of braces. When PowerShell evaluates the outer **ScriptBlock**, the +result is the inner **ScriptBlock**. The inner **ScriptBlock** becomes the new +default parameter value. ```powershell -$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} } +} ``` -The following syntax accomplishes the same result. +### Add values to an existing `$PSDefaultParameterValues` variable + +To add a value to `$PSDefaultParameterValues`, use the `Add()` method. Adding a +value doesn't affect the hashtable's existing values. Use a comma (`,`) to +separate the _key_ from the _value_. ```powershell -$PSDefaultParameterValues["Get-Process:Name"]="PowerShell" +$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell') ``` -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was added. +The hashtable created in the prior example is updated with a new key-value +pair. -``` +```powershell PS> $PSDefaultParameterValues Name Value @@ -269,31 +207,15 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to remove values from \$PSDefaultParameterValues - -To remove a value from `$PSDefaultParameterValues`, use the **Remove** method -of hash tables. Removing a value doesn't affect the hash table's existing -values. +### Remove a value from `$PSDefaultParameterValues` -The following syntax shows how to use the **Remove** method on -`$PSDefaultParameterValues`. +To remove a value from `$PSDefaultParameterValues`, use the `Remove()` method. +Removing a value doesn't affect the hashtable's existing values. -``` -PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName") -``` - -In this example, the hash table created in the prior example is updated to -remove a **Key/Value** pair. The **Remove** method removes the -`Get-Process:Name` key. +This example removes the key-value pair that was added in the previous example. ```powershell -$PSDefaultParameterValues.Remove("Get-Process:Name") -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was removed. - -``` +PS> $PSDefaultParameterValues.Remove('Get-Process:Name') PS> $PSDefaultParameterValues Name Value @@ -303,28 +225,14 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to change values in \$PSDefaultParameterValues - -Changes to a specific value don't affect existing hash table values. To change -a specific **Key/Value** pair in `$PSDefaultParameterValues`, use the following -syntax: - -``` -PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` +### Change a value in `$PSDefaultParameterValues` -In this example, the hash table created in the prior example is updated to -change a **Key/Value** pair. The following command changes the -`Send-MailMessage:SmtpServer` key to a new value of **ServerXYZ**. +Use indexing or member access to change the default value of an existing +key-value pair. In this example, the default value for the +`Send-MailMessage:SmtpServer` key is changed to a new value of **ServerXYZ**. ```powershell -$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ" -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Send-MailMessage:SmtpServer` key was changed to a new value. - -``` +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ' PS> $PSDefaultParameterValues Name Value @@ -334,30 +242,18 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -### How to disable and re-enable \$PSDefaultParameterValues +### Disable or re-enable `$PSDefaultParameterValues` You can temporarily disable and then re-enable `$PSDefaultParameterValues`. Disabling `$PSDefaultParameterValues` is useful if you're running scripts that need different default parameter values. To disable `$PSDefaultParameterValues`, add a key of `Disabled` with a value of -**True**. The values in `$PSDefaultParameterValues` are preserved, but aren't -effective. - -``` -PS> $PSDefaultParameterValues.Add("Disabled", $True) -``` +`$true`. The values in `$PSDefaultParameterValues` are preserved, but aren't +used. -The following syntax accomplishes the same result. - -``` -PS> $PSDefaultParameterValues["Disabled"]=$True -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table with -the value for the `Disabled` key. - -``` +```powershell +PS> $PSDefaultParameterValues.Add('Disabled', $true) PS> $PSDefaultParameterValues Name Value @@ -368,26 +264,11 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -To re-enable `$PSDefaultParameterValues`, remove the **Disabled** key or change -the value of the **Disabled** key to `$False`. The previous value of -`$PSDefaultParameterValues` is effective again. - -``` -PS> $PSDefaultParameterValues.Remove("Disabled") -``` - -The following syntax accomplishes the same result. +To re-enable `$PSDefaultParameterValues`, remove the `Disabled` key or change +the value of the `Disabled` key to `$false`. -``` -PS> $PSDefaultParameterValues["Disabled"]=$False -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. When -the **Remove** method is used, the `Disabled` key is removed from the output. -If the alternate syntax was used to re-enable `$PSDefaultParameterValues`, the -`Disabled` key is displayed as **False**. - -``` +```powershell +PS> $PSDefaultParameterValues.Disabled = $false PS> $PSDefaultParameterValues Name Value @@ -400,10 +281,19 @@ Send-MailMessage:SmtpServer ServerXYZ ## See also -- [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216) -- [about_Functions_Advanced](about_Functions_Advanced.md) -- [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Preference_Variables](about_Preference_Variables.md) -- [about_Profiles](about_Profiles.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_CommonParameters][01] +- [about_Functions_Advanced][02] +- [about_Functions_CmdletBindingAttribute][03] +- [about_Hash_Tables][04] +- [about_Preference_Variables][05] +- [about_Profiles][06] +- [about_Script_Blocks][07] + + +[01]: about_CommonParameters.md +[02]: about_Functions_Advanced.md +[03]: about_Functions_CmdletBindingAttribute.md +[04]: about_Hash_Tables.md +[05]: about_Preference_Variables.md +[06]: about_Profiles.md +[07]: about_Script_Blocks.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 3f8d1933b66b..30eca6439b23 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -1,7 +1,7 @@ --- description: Describes how to set custom default values for cmdlet parameters and advanced functions. Locale: en-US -ms.date: 05/31/2019 +ms.date: 01/02/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parameters_default_values?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Parameters_Default_Values @@ -10,202 +10,134 @@ title: about_Parameters_Default_Values ## Short description -Describes how to set custom default values for cmdlet parameters and advanced -functions. +Describes how to set custom default values for cmdlet parameters, advanced +functions, and scripts. ## Long description The `$PSDefaultParameterValues` preference variable lets you specify custom -default values for any cmdlet or advanced function. Cmdlets and advanced -functions use the custom default value unless you specify another value in the -command. +default parameter values for any cmdlet, advanced function, or script that uses +the **CmdletBinding** attribute. The defined values are used unless you specify +other values on the command line. -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 useful in the following scenarios: -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 email server name or -project GUID. +- specifying the same parameter value every time you use the command +- specifying a particular parameter value that's difficult to remember, such as + an email 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. +The `$PSDefaultParameterValues` variable has no default value. To save the +settings for use in future sessions, add the variable assignment to your +PowerShell profile. `$PSDefaultParameterValues` was introduced in PowerShell 3.0. ## Syntax -The `$PSDefaultParameterValues` variable is a hash table that validates the -format of keys as an object type of -**System.Management.Automation.DefaultParameterDictionary**. The hash table -contains **Key/Value** pairs. A **Key** is in the format -`CmdletName:ParameterName`. A **Value** is the **DefaultValue** or -**ScriptBlock** assigned to the key. +The `$PSDefaultParameterValues` variable is an object type of +**System.Management.Automation.DefaultParameterDictionary**. The +**DefaultParameterDictionary** type is a hashtable with some extra validation +for the format of the keys. The hashtable contains key-value pairs where: -The syntax of the `$PSDefaultParameterValues` preference variable is as -follows: +- the _key_ has the format `CommandName:ParameterName` +- the _value_ is default value for the parameter or a **ScriptBlock** that + returns the default value -``` -$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"} - -$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} } - -$PSDefaultParameterValues["Disabled"]=$True | $False -``` - -Wildcard characters are permitted in the **CmdletName** and **ParameterName** -values. - -To set, change, add, or remove a specific **Key/Value** pair from -`$PSDefaultParameterValues`, use the methods to edit a standard hash table. For -example, the **Add** and **Remove** methods. These methods don't overwrite -other values in the hash table. +For the _key_, the **CommandName** must be the name of a cmdlet, advanced +function, or script file that uses the **CmdletBinding** attribute. The script +name must match the name as reported by +`(Get-Command -Name .\script.ps1).Name`. -There's another syntax that doesn't overwrite an existing -`$PSDefaultParameterValues` hash table. To add or change a specific -**Key/Value** pair, use the following syntax: +> [!NOTE] +> PowerShell doesn't prevent you from specifying an alias for the +> **CommandName**. However, there are cases where the definition is ignored or +> causes an error. You should avoid defining default values for command +> aliases. -``` -$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` - -The **CmdletName** must be the name of a cmdlet or the name of an advanced -function that uses the **CmdletBinding** attribute. You can't use -`$PSDefaultParameterValues` to specify default values for scripts or simple -functions. +The _value_ can be an object of a type that's compatible with the parameter or +a **ScriptBlock** that returns such a value. When the value is a script block, +PowerShell evaluates the script block and uses the result for the parameter +value. If the specified parameter expects a **ScriptBlock** type, you must +enclose the value in another set of braces. When PowerShell evaluates the outer +**ScriptBlock**, the result is the inner **ScriptBlock**. The inner +**ScriptBlock** becomes the new default parameter value. -The **DefaultValue** 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 accepts a script block value, -enclose the script block value in a second set of braces, such as: +For example: ```powershell -$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} } +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-Process} } +} ``` -For more information, see the following documents: - -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Script_Blocks](about_Script_Blocks.md) -- [about_Preference_Variables](about_Preference_Variables.md) - ## Examples -### How to set \$PSDefaultParameterValues - -`$PSDefaultParameterValues` is a preference variable, so it exists only in the -session in which it's set. It has no default value. - -To set `$PSDefaultParameterValues`, type the variable name and one or more -**Key/Value** pairs. If you run another `$PSDefaultParameterValues` command, it -overwrites the existing hash table. +Use the `Add()` and `Remove()` methods to add or remove a specific key-value +pair from `$PSDefaultParameterValues` without overwriting other existing +key-value pairs. -For examples about how to change **Key/Value** pairs without overwriting -existing hash table values, see -[How to add values to \$PSDefaultParameterValues](#how-to-add-values-to-psdefaultparametervalues) -or -[How to change values in \$PSDefaultParameterValues](#how-to-change-values-in-psdefaultparametervalues). - -To save `$PSDefaultParameterValues` for future sessions, add a -`$PSDefaultParameterValues` command to your PowerShell profile. For more -information, see [about_Profiles](about_Profiles.md). - -#### Set a custom default value +```powershell +$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue') +$PSDefaultParameterValues.Remove('CmdletName:ParameterName') +``` -The **Key/Value** pair sets the `Send-MailMessage:SmtpServer` key to a custom -default value of **Server123**. +Use indexing or member access to change the value of an existing key-value +pair. For example: ```powershell -$PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" -} +$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2' +$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1' ``` -#### Set default values for multiple parameters +### Assign values to `$PSDefaultParameterValues` -To set default values for multiple parameters, separate each **Key/Value** pair -with a semicolon (`;`). The `Send-MailMessage:SmtpServer` and -`Get-WinEvent:LogName` keys are set to custom default values. +To define default values for cmdlet parameters, assign a hashtable containing +the appropriate key-value pairs to the `$PSDefaultParameterValues` variable. +The hashtable can contain multiple key-value pairs. This example sets default +values for the `Send-MailMessage:SmtpServer` and `Get-WinEvent:LogName` keys. ```powershell $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123"; - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" + 'Send-MailMessage:SmtpServer'='Server123' + 'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational' } ``` -#### Use wildcards and switch parameters - -The cmdlet and parameter names can contain wildcard characters. Use `$True` and -`$False` to set values for switch parameters, such as **Verbose**. The common -parameter's **Verbose** parameter is set to `$True` for all commands. +The cmdlet and parameter names can contain wildcard characters. Use `$true` and +`$false` to set values for switch parameters, such as **Verbose**. This example +sets the common parameter **Verbose** to `$true` for all commands. ```powershell -$PSDefaultParameterValues = @{"*:Verbose"=$True} +$PSDefaultParameterValues = @{'*:Verbose'=$true} ``` -#### Use an array for the default value - -If a parameter can accept multiple values, an array, you can set multiple -values as the default values. The default value of the -`Invoke-Command:ComputerName` key is set to an array value of **Server01** and -**Server02**. +If a parameter accepts multiple values, you can provide multiple default values +using an array. This example sets the default value of the +`Invoke-Command:ComputerName` key to an array containing the string values +`Server01` and `Server02`. ```powershell $PSDefaultParameterValues = @{ - "Invoke-Command:ComputerName"="Server01","Server02" + 'Invoke-Command:ComputerName' = 'Server01','Server02' } ``` -#### Use a script block +### View defined values -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 `Format-Table:AutoSize` key sets that switch parameter to a default value -of **True**. The `If` statement contains a condition that the `$host.Name` must -be the PowerShell console, **ConsoleHost**. +Consider the following definition of `$PSDefaultParameterValues`: ```powershell -$PSDefaultParameterValues=@{ - "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}} +$PSDefaultParameterValues = @{ + 'Send-MailMessage:SmtpServer' = 'Server123' + 'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational' + 'Get-*:Verbose' = $true } ``` -If a parameter accepts 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, and that is set as the default parameter -value. - -The `Invoke-Command:ScriptBlock` key set to a default value of the **System -event log** because the script block is enclosed in a second set of braces. The -result of the script block is passed to the `Invoke-Command` cmdlet. +You can view the defined values by entering `$PSDefaultParameterValues` at the +command prompt. ```powershell -$PSDefaultParameterValues=@{ - "Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}} -} -``` - -### How to get \$PSDefaultParameterValues - -The hash table values are displayed by entering `$PSDefaultParameterValues` at -the PowerShell prompt. - -A `$PSDefaultParameterValues` hash table is set with three **Key/Value** pairs. -This hash table is used in the following examples that describe how to add, -change, and remove values from `$PSDefaultParameterValues`. - -``` -PS> $PSDefaultParameterValues = @{ - "Send-MailMessage:SmtpServer"="Server123" - "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational" - "Get-*:Verbose"=$True -} - PS> $PSDefaultParameterValues Name Value @@ -215,50 +147,56 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -To get the value of a specific `CmdletName:ParameterName` key, use the -following syntax: - -``` -$PSDefaultParameterValues["CmdletName:ParameterName"] -``` +You can use indexing or member access to get a specific value. -For example, to get the value for the `Send-MailMessage:SmtpServer` key. - -``` -PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"] +```powershell +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation Server123 +PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation +True ``` -### How to add values to \$PSDefaultParameterValues +### Use a script block for the default value -To add a value to `$PSDefaultParameterValues`, use the **Add** method. Adding a -value doesn't affect the hash table's existing values. +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. -Use a comma (`,`) to separate the **Key** from the **Value**. The following -syntax shows how to use the **Add** method for `$PSDefaultParameterValues`. +The `Format-Table:AutoSize` key sets that switch parameter to a default value +of `$true` The `if` statement contains a condition that the `$Host.Name` must +be `ConsoleHost`. -``` -PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue") +```powershell +$PSDefaultParameterValues = @{ + 'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} } +} ``` -The hash table created in the prior example is updated with a new **Key/Value** -pair. The **Add** method sets the `Get-Process:Name` key to the value -**PowerShell**. +If a parameter accepts a **ScriptBlock** value, enclose the **ScriptBlock** in +another set of braces. When PowerShell evaluates the outer **ScriptBlock**, the +result is the inner **ScriptBlock**. The inner **ScriptBlock** becomes the new +default parameter value. ```powershell -$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell") +$PSDefaultParameterValues = @{ + 'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} } +} ``` -The following syntax accomplishes the same result. +### Add values to an existing `$PSDefaultParameterValues` variable + +To add a value to `$PSDefaultParameterValues`, use the `Add()` method. Adding a +value doesn't affect the hashtable's existing values. Use a comma (`,`) to +separate the _key_ from the _value_. ```powershell -$PSDefaultParameterValues["Get-Process:Name"]="PowerShell" +$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell') ``` -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was added. +The hashtable created in the prior example is updated with a new key-value +pair. -``` +```powershell PS> $PSDefaultParameterValues Name Value @@ -269,31 +207,15 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to remove values from \$PSDefaultParameterValues - -To remove a value from `$PSDefaultParameterValues`, use the **Remove** method -of hash tables. Removing a value doesn't affect the hash table's existing -values. +### Remove a value from `$PSDefaultParameterValues` -The following syntax shows how to use the **Remove** method on -`$PSDefaultParameterValues`. +To remove a value from `$PSDefaultParameterValues`, use the `Remove()` method. +Removing a value doesn't affect the hashtable's existing values. -``` -PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName") -``` - -In this example, the hash table created in the prior example is updated to -remove a **Key/Value** pair. The **Remove** method removes the -`Get-Process:Name` key. +This example removes the key-value pair that was added in the previous example. ```powershell -$PSDefaultParameterValues.Remove("Get-Process:Name") -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Get-Process:Name` key was removed. - -``` +PS> $PSDefaultParameterValues.Remove('Get-Process:Name') PS> $PSDefaultParameterValues Name Value @@ -303,28 +225,14 @@ Get-*:Verbose True Send-MailMessage:SmtpServer Server123 ``` -### How to change values in \$PSDefaultParameterValues - -Changes to a specific value don't affect existing hash table values. To change -a specific **Key/Value** pair in `$PSDefaultParameterValues`, use the following -syntax: - -``` -PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue" -``` +### Change a value in `$PSDefaultParameterValues` -In this example, the hash table created in the prior example is updated to -change a **Key/Value** pair. The following command changes the -`Send-MailMessage:SmtpServer` key to a new value of **ServerXYZ**. +Use indexing or member access to change the default value of an existing +key-value pair. In this example, the default value for the +`Send-MailMessage:SmtpServer` key is changed to a new value of **ServerXYZ**. ```powershell -$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ" -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. The -`Send-MailMessage:SmtpServer` key was changed to a new value. - -``` +PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ' PS> $PSDefaultParameterValues Name Value @@ -334,30 +242,18 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -### How to disable and re-enable \$PSDefaultParameterValues +### Disable or re-enable `$PSDefaultParameterValues` You can temporarily disable and then re-enable `$PSDefaultParameterValues`. Disabling `$PSDefaultParameterValues` is useful if you're running scripts that need different default parameter values. To disable `$PSDefaultParameterValues`, add a key of `Disabled` with a value of -**True**. The values in `$PSDefaultParameterValues` are preserved, but aren't -effective. - -``` -PS> $PSDefaultParameterValues.Add("Disabled", $True) -``` +`$true`. The values in `$PSDefaultParameterValues` are preserved, but aren't +used. -The following syntax accomplishes the same result. - -``` -PS> $PSDefaultParameterValues["Disabled"]=$True -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table with -the value for the `Disabled` key. - -``` +```powershell +PS> $PSDefaultParameterValues.Add('Disabled', $true) PS> $PSDefaultParameterValues Name Value @@ -368,26 +264,11 @@ Get-*:Verbose True Send-MailMessage:SmtpServer ServerXYZ ``` -To re-enable `$PSDefaultParameterValues`, remove the **Disabled** key or change -the value of the **Disabled** key to `$False`. The previous value of -`$PSDefaultParameterValues` is effective again. - -``` -PS> $PSDefaultParameterValues.Remove("Disabled") -``` - -The following syntax accomplishes the same result. +To re-enable `$PSDefaultParameterValues`, remove the `Disabled` key or change +the value of the `Disabled` key to `$false`. -``` -PS> $PSDefaultParameterValues["Disabled"]=$False -``` - -The `$PSDefaultParameterValues` variable displays the updated hash table. When -the **Remove** method is used, the `Disabled` key is removed from the output. -If the alternate syntax was used to re-enable `$PSDefaultParameterValues`, the -`Disabled` key is displayed as **False**. - -``` +```powershell +PS> $PSDefaultParameterValues.Disabled = $false PS> $PSDefaultParameterValues Name Value @@ -400,10 +281,19 @@ Send-MailMessage:SmtpServer ServerXYZ ## See also -- [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216) -- [about_Functions_Advanced](about_Functions_Advanced.md) -- [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) -- [about_Hash_Tables](about_Hash_Tables.md) -- [about_Preference_Variables](about_Preference_Variables.md) -- [about_Profiles](about_Profiles.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_CommonParameters][01] +- [about_Functions_Advanced][02] +- [about_Functions_CmdletBindingAttribute][03] +- [about_Hash_Tables][04] +- [about_Preference_Variables][05] +- [about_Profiles][06] +- [about_Script_Blocks][07] + + +[01]: about_CommonParameters.md +[02]: about_Functions_Advanced.md +[03]: about_Functions_CmdletBindingAttribute.md +[04]: about_Hash_Tables.md +[05]: about_Preference_Variables.md +[06]: about_Profiles.md +[07]: about_Script_Blocks.md