PowerShell
PowerShell copied to clipboard
PowerShell
Advance Function's Parameter's Get-Help is inconsistent if comment-based help is used (missing Alias, Default Value, Parameter Set, etc.)
Prerequisites
- [x] Write a descriptive title.
- [x] Make sure you are able to repro it on the latest released version
- [x] Search the existing issues.
- [x] Refer to the FAQ.
- [x] Refer to Differences between Windows PowerShell 5.1 and PowerShell.
Steps to reproduce
Enter in the following code
function Test-GreetingA {
[CmdletBinding()]
param (
[Parameter(
Position = 0,
Mandatory,
ValueFromPipeline
)]
[Alias(
'Subject'
)]
[string]
$Person
)
begin {
}
process {
Write-Output "Hello $Person"
}
end {
}
}
<#
.SYNOPSIS
Test a simple greeting
.DESCRIPTION
A simple greeting that requires a person's name
.PARAMETER Person
The person you want to greet
.EXAMPLE
Test-Greeting -Person 'John Smith'
#>
function Test-GreetingB {
[CmdletBinding()]
param (
[Parameter(
Position = 0,
Mandatory,
ValueFromPipeline
)]
[Alias(
'Subject'
)]
[string]
$Person
)
begin {
}
process {
Write-Output "Hello $Person"
}
end {
}
}
Now run the following Get-Help commands
Get-Help Test-GreetingA -Parameter Person
Get-Help Test-GreetingB -Parameter Person
Expected behavior
-Person <string>
Required? true
Position? 0
Default value None
Accept pipeline input? true (ByValue)
Parameter set name (All)
Aliases Subject
Dynamic? false
Accept wildcard characters? false
-Person <String>
The person you want to greet
Required? true
Position? 0
Default value None
Accept pipeline input? true (ByValue)
Parameter set name (All)
Aliases Subject
Dynamic? false
Accept wildcard characters? false
Actual behavior
-Person <string>
Required? true
Position? 0
Accept pipeline input? true (ByValue)
Parameter set name (All)
Aliases Subject
Dynamic? false
Accept wildcard characters? false
-Person <String>
The person you want to greet
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Aliases
Accept wildcard characters? false
Error details
Incorrect output includes (disparity between Get-Help's output for Test-GreetingA vs. Test-GreetingB):
- 'Default value' is missing (A)
- 'Position' is incremented (B)
- 'Parameter set name' is missing (B)
- 'Dynamic' is missing (B)
- 'Default value' right hand value is not showing (B)
- 'Aliases' right hand value is not showing (B)
Environment data
Name Value
---- -----
PSVersion 7.5.1
PSEdition Core
GitCommitId 7.5.1
OS Microsoft Windows 10.0.22631
Platform Win32NT
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1
WSManStackVersion 3.0
Visuals
The help output is identical for both functions:
-Person <string>
Required? true
Position? 0
Accept pipeline input? true (ByValue)
Parameter set name (All)
Aliases Subject
Dynamic? false
Accept wildcard characters? false
Could it be VSCode behavior?
1st thing I noticed in looking quickly at this
Your placement of help above the function definition, whilst allowed in scripts, can easily break in interactive use & is why I recommend always doing the below and have done since this blog post
Expand for help layout recommendation
My Recommended help layout within your function
function Test-GreetingB {
<#
.SYNOPSIS
Test a simple greeting
.DESCRIPTION
A simple greeting that requires a person's name
.PARAMETER Person
The person you want to greet
.EXAMPLE
Test-Greeting -Person 'John Smith'
#>
[CmdletBinding()]
param (
[Parameter(
Position = 0,
Mandatory,
ValueFromPipeline
)]
[Alias(
'Subject'
)]
[string]
$Person
)
begin {
}
process {
Write-Output "Hello $Person"
}
end {
}
}
Thank you for your help @kilasuit , I didn't know that. I did that and re-ran the Get-Help command with the same results.
@237dmitry You are correct. I thought that by having the config launch the standard powershell terminal it was the same as if I was running from a normal terminal. I thought that as both my Window's Terminal and VSCode's Terminal report the same host and version info and do have VSCode configured to launch what I thought was a normal windows terminal running powershell instead. See pictures below for more information:
Windows Terminal running PowerShell:
VSCode's terminal running PowerShell:
VSCode terminal host running PowerShell's (from the extension/integration):
Out of giggles though, I ran the test in the native windows terminal app and the result was correct without error. So, @237dmitry is correct in thinking this is a VSCode behavior. I guess my attempt to use the windows terminal from VSCode is not actually working. I'm a bit confused as to why and am wondering what other behaviors are different. Does anyone know of a list of behavior differences or how launching powershell from within VSCode changes its behavior when the host is the same?
Thank you @JosephColvin for this issue. The Interactive WG reviewed this and yes, it's a Get-Help bug. We will leave this open to fix in the future.
@theJasonHelmick I wonder if I couldn't spend a weekend tracking down the bug (not but, stinky typo) and contributing to finding in the code where the actual problem is? Did you already find the bug to be in the commandlet process/control side or in the Get-Help commandlet itself?
@JosephColvin - Thank you for the offer :). In this case we are aware of the issue so I don't want you to waste your time. I don't have any timelines but I hope to resolve this in the future.