Powershell: Get-Help cannot open if there are duplicates

[watkins656]

Steps to reproduce

1. Clone any help file - example: about_Scheduled_Jobs
2. Type command: Get-Help about_Scheduled_Jobs
3. There is no way to open the help, even attempting with -ShowWindow

Expected behavior

There should be a way to open the help file, even with duplicates.

Actual behavior

Nothing can be opened

Environment data

Name Value
---- -----
PSVersion 5.1.17134.858
PSEdition Desktop
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...}
BuildVersion 10.0.17134.858
CLRVersion 4.0.30319.42000
WSManStackVersion 3.0
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1

[vexx32]

@watkins656 can you reproduce this issue in the latest stable or preview versions of PowerShell? 5.1 is a legacy version and is not being actively maintained. 🙂

[alexandair]

Yes, it could be reproduced in the latest preview:

PowerShell 7.0.0-preview.6
Copyright (c) Microsoft Corporation. All rights reserved.

PS C:\Users\aleksandar> help about_psreadline

Name                              Category  Module                    Synopsis
----                              --------  ------                    --------
about_PSReadLine                  HelpFile
about_psreadline                  HelpFile

PS C:\Users\aleksandar>

[rkeithhill]

This bug just won't go away. WTH? You can workaround the bug like so:

get-help about_psreadline | select -f 1 | % ToString | more

But seriously, this bug needs to be fixed.

[vexx32]

/cc @SteveL-MSFT

The behaviour arises because Get-Help acts as a search when it finds two help files by the same name. I would think that the behaviour should be:

1. If the name provided matches multiple entries, and the names of the returned entries are identical, then
2. The most up to date (by version I suppose) entry should be automatically selected. Otherwise,
3. Return to current behaviour (allow multiple entries to be displayed when there is more than one match).

Additionally, we should probably expose the version of the module that this help is coming from so as to provide a way to distinguish the files, _and_ provide a way for Get-Help to target a specific version should it be required.

[iSazonov]

It seems we already have such issue.

[mklement0]

Good points, @vexx32; with side-by-side module installations, a way to target a specific version is definitely called for.

@iSazonov: Yes, the issue at hand was originally reported in #9215, but since there's more information here now, can you please close #9215 as a duplicate?
There's also a bit more background in this Stack Overflow answer.

Worth noting that the problem only affects _conceptual_ help topics (about_*, more generally, presumably all HelpFile category files, *.help.txtfiles).

With _cmdlet_ help topics, the same module version that the module auto-loading mechanism targets is apparently targeted (first module by that name in the folders listed in $env:PSModulePath examined in sequence, highest version wins among multiple versions installed in the same folder), and no duplicates occur.

There are additional oddities:

• WinPS apparently always lists the about topics from its $PSHOME folders first.

• PS Core now seems to ignore a $PSHOME version if one is installed with a module that comes first in $env:PSModulePath; however, with the very specific combination of installing PSReadLine 1.2 alongside 2.0.0-beta6 (Install-Module PSReadLine -Force -SkipPublisherCheck), I can still reproduce the symptom in PowerShell Core 7.0.0-preview.6

• Generally, it seems that *.help.txt files are even picked up in irregularly named folders (not named for module versions) that the module auto-loader ignores.

Here's a quick helper function that finds all help files by file-name substring (e.g., Get-HelpFile psReadline).

function Get-HelpFile($fileNamePart) { 
  # Note the use of Split-Path -Parent, because help files can be in sibling
  # folders of $env:PSModulePath folders.
  Split-Path -Parent ($env:PSModulePath -split [IO.Path]::PathSeparator) | 
      Get-ChildItem -File -Recurse -Filter *$fileNamePart* |
        Where-Object Name -match '(?:\.help\.txt|-help.xml)$'
}

[SteveL-MSFT]

I took a look at this and unfortunately it's not so straightforward to fix. The problem is that as help is discovered, it is emitted. Since we don't know the order before hand if there are dupes, we don't know which of the duplicates is the right one to show until we have the full results. If we change this to a synchronous model where we filter first before displaying, then this breaks the current user experience where they see found results as they are found. This means that if there is a large set of results, you wouldn't see anything until the very end (we'd add a progress bar I suppose).

Assuming we agree to break the user experience, there isn't any version information related to the module in updateable help. The help content is stored in a Help folder. In the case of PSReadLine, you have one under your personal powershell\help folder and the other in <modulepath>\help. I think it makes sense to prefer the updateable help version in the case of a dupe, but we still have the problem #1 above.

In the case where you have multiple versions of the same module in different places that have local help that gets found by the helpsystem, it would probably make sense to show the one from the path where the module is imported.

All of this is not a small change. Moving out of 7.1 as I don't see such changes making it in time.

[iSazonov]

I think it makes sense to prefer the updateable help version in the case of a dupe, but we still have the problem #1 above.

So if user loaded new module version from another path it will get old help. I think we should do that we do to get a cmdlet version - go through a module manifest.
In about_ we could add a comment header in these files with version and others that we could use for right file selection.

[SteveL-MSFT]

@PowerShell/powershell-committee discussed this, we propose:

• Add Path member to HelpInfoShort type, this allows the user to differentiate between dupes
• Enable Get-Help to accept a HelpInfoShort and perform the ToString() on it

This allows the use case:

get-help psreadline | select -first 1 | get-help

[vexx32]

That's a partial fix, but IMO unless a wildcard is present, Get-Help should do some basic filtering to ensure it doesn't output duplicate results.