Incorrect information on supported ```$PSDefaultParameterValues``` command types

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parameters_default_values#long-description
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parameters_default_values#syntax

Summary

about_Parameters_Default_Values states the following:

• Only cmdlets or advanced functions are supported. Specifically, (advanced) script files are unsupported.
• A function must use the CmdletBindingAttribute to be advanced.

The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function.

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 [...]

However, neither point is accurate.

• Regarding supported command types:
  • A .ps1 script file (ExternalScript command type) is supported, providing it's advanced and is referred to by name (as reported by (Get-Command -Name .\script.ps1).Name).
  • An alias (Alias command type) is supported, providing its target (as reported by AliasInfo.Definition) is a cmdlet, advanced function/filter or advanced script file by name.
• A function/filter/script file does not require CmdletBindingAttribute to be advanced providing at least one parameter is decorated with ParameterAttribute. This is correctly documented in about_Functions_Advanced_Parameters.

Details

Example commands:

'param ([Parameter()] $Foo) $Foo' | 
    Set-Content -LiteralPath Temp:\ScriptFile.ps1

function AdvancedFunction { param ([Parameter()] $Foo) $Foo }

Set-Alias -Name ScriptFileNameAlias -Value ScriptFile.ps1
$Env:PATH += "{0}{1}" -f [IO.Path]::PathSeparator, (Get-Item -LiteralPath Temp:).Fullname

Set-Alias -Name AdvancedFunctionAlias -Value AdvancedFunction

A default value is supplied in the following examples as of v7.5.0:

# Cmdlet without module-qualification.
$PSDefaultParameterValues = @{ 'Write-Output:InputObject' = 'Bar' }
Write-Output # Bar

# Advanced function/filter without module-qualification.
$PSDefaultParameterValues = @{ 'AdvancedFunction:Foo' = 'Bar' }
AdvancedFunction # Bar

# Advanced script by name only.
$PSDefaultParameterValues = @{ 'ScriptFile.ps1:Foo' = 'Bar' }
Temp:\ScriptFile.ps1 # Bar

# Alias whose target is a cmdlet or advanced function/filter.
$PSDefaultParameterValues = @{ 'AdvancedFunctionAlias:Foo' = 'Bar' }
AdvancedFunctionAlias # Bar

# Alias whose target is an advanced script file by name.
# Note that the target script must be $Env:PATH-discoverable.
$PSDefaultParameterValues = @{ 'ScriptFileNameAlias:Foo' = 'Bar' }
ScriptFileNameAlias # Bar

# Function call directly after adding alias.
# This is potentially unexpected behavior given the command is called 
# directly and $PSDefaultParameterValues only contains an alias.
$PSDefaultParameterValues = @{ 'AdvancedFunctionAlias:Foo' = 'Bar' }
AdvancedFunction # Bar

Note:

• See Improve supported $PSDefaultParameterValues command types PowerShell/PowerShell#24708 for general limitations/inconsistencies that are not currently documented. E.g., module-qualified commands are unsupported.

Suggested Fix

In about_Parameters_Default_Values:

• State $PSDefaultParameterValues supports advanced .ps1 script files.
  • Note that the file must be referred to by name with .ps1 extension, as reported by (Get-Command -Name .\script.ps1).Name.
  • A full or relative path cannot be specified.
• State $PSDefaultParameterValues supports aliases whose target is a cmdlet, advanced function or script file by name.
  • Note that calling the cmdlet/advanced command directly still supplies the default value despite $PSDefaultParameterValues only containing an alias.
• Clarify what makes a function or script file advanced.
  • If either is applicable (or both):
    • The param () block is decorated with CmdletBindingAttribute.
    • At least one parameter is decorated with ParameterAttribute.
  • Note that param () is not required to make a function advanced.
    • E.g., function Test([Parameter()] $Foo) {} is advanced.
    • It is required for a script file/block, given the alternative function parameter syntax is unavailable.
  • Link to the relevant documentation.
• Potentially note that filters are included in the term "function".

[sdwheeler]

While defining parameter values for alias is allowed, it's problematic and shouldn't be used. You can't have defaults defined for both a cmdlet or advanced function and its alias.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
AdvancedFunctionAlias:Foo      Foo
AdvancedFunction:Foo           Bar
ScriptFileNameAlias:Foo        Foo
ScriptFile.ps1:Foo             Bar

PS> AdvancedFunction
WARNING: Multiple different default values are defined in $PSDefaultParameterValues for the parameter matching the following name or alias: Foo. These defaults have been ignored.
PS> AdvancedFunctionAlias
WARNING: Multiple different default values are defined in $PSDefaultParameterValues for the parameter matching the following name or alias: Foo. These defaults have been ignored.

If you have definitions for a script file and its alias, the definition for the alias is ignored. If you don't have a definition for the script, the definition for the alias isn't used.

PS> Get-Alias ScriptFileNameAlias

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Alias           ScriptFileNameAlias -> ScriptFile.ps1

PS> temp:\ScriptFile.ps1
Bar
PS> ScriptFileNameAlias
Bar
PS> $PSDefaultParameterValues.remove('ScriptFile.ps1:Foo')
PS> ScriptFileNameAlias
PS> ScriptFileNameAlias Buzz
Buzz