更新 PowerShell 关于帮助

在最近的一些工作中，我意识到我的新 Windows PowerShell 5.1 安装缺少“关于”帮助主题。显然，这是一个已知问题，尽管我认为它没有引起太多关注。 Microsoft 正在致力于改进 PowerShell 7 的可更新帮助，我认为这也将为 Windows PowerShell 带来有益的变化。事实上，微软一直在更新有关主题。所有帮助文件均在 GitHub 上开源：https://github.com/MicrosoftDocs/PowerShell-Docs/tree/staging/reference。我经常使用 about 主题，因此我编写了一个 PowerShell 脚本来从 GitHub 下载并安装最新的 About 主题。

下载-PSAboutHelp.ps1

该脚本跨平台运行，尽管我尚未使用 PowerShell 6.x 对其进行测试。它需要从 Windows PowerShell 上的提升会话运行。该脚本需要 Platyps 模块，如果尚未安装，则将安装该模块。该脚本不需要 git 或 GitHub 帐户，尽管它依赖于 GitHub API。

该脚本可以从此 Github gist 保存。

Download-PSAboutHelp.ps1:

#requires -version 5.1
#requires -RunAsAdministrator

# Download-PSAboutHelp.ps1

 c:\scripts\Download-PSAboutHelp.ps1

Download the About topics for PowerShell 5.1 and save them to the default location.

.Example
PS7 C:\> c:\scripts\Download-PSAboutHelp.ps1 -alternatepath C:\PS7\About

Download the About topics for PowerShell 7.0 and save to C:\PS7\About.

.Notes

This command uses the GitHub public API. It is possible that if you run this command
repeatedly in a short period of time that you might get an error regarding API limits.

This command has NOT been tested with PowerShell 6.x.

Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/

.Link
Get-Help
.Link
Update-Help
#>
[cmdletbinding(SupportsShouldProcess)]
Param(
    [Parameter(HelpMessage = "Specify an alternate path to for the About help files. The path must already exist.")]
    [string]$AlternatePath
)

#get the PowerShell version
$version = "{0}.{1}" -f $PSVersionTable.PSVersion.Major,$PSVersionTable.PSVersion.minor
#validate final Path

if ($AlternatePath) {
    Write-Verbose "Using alternate path $AlternatePath"
    $HelpPath = $AlternatePath
}
else {
    if ($version -eq "5.1") {
        $helpPath = "$PSHome\en-US"
    }
    else {
        if ($isWindows) {
            $helpPath = "~\Documents\PowerShell\help\en-US\"
        }
        else {
            $helpPath = "~/.local/share/powershell/Help/en-US"
        }
    }
}

if (-Not (Test-Path $helpPath)) {
    Write-Warning "Failed to find the destination path $helpPath."
    #bail out
    return
}

#install Platyps if not found
if (-Not (Get-Module Platyps -ListAvailable)) {
    Write-Host "Installing the required Platyps module from the PowerShell Gallery" -ForegroundColor Yellow
    Try {
        Install-Module Platyps -force -errorAction Stop
    }
    Catch {
        #bail out if this fails
        Write-Warning "Failed to install Platyps. $($_.Exception.message)"
        return
    }
}
else {
    Import-Module Platyps
}

$base = "https://api.github.com"
$owner = "MicrosoftDocs"
$repo = "PowerShell-Docs"
$path = "reference/$version/Microsoft.PowerShell.Core/About"

Try {
    $r = Invoke-RestMethod -uri "$base/repos/$owner/$repo/contents/$path" -DisableKeepAlive -ErrorAction Stop
}
Catch {
    Write-Warning "Failed to download contents from $uri. $($_.exception.message)"
    #bail out
    return
}

#download file
$topics = $r | Where-Object name -ne "About.md"

if ($topics) {
    $count = $topics.count
    Write-Verbose "Found $count About topics"
`   $i = 0
    #Parameters for Write-Progress
    $progParam = @{
        Activity = $MyInvocation.MyCommand
        Status = "Downloading content"
        CurrentOperation = $null
        PercentComplete = 0
        ID = 1
    }

    #use the .NET framework for non-Windows systems which don't have $env:temp
    $destPath = Join-Path -path ([System.IO.Path]::GetTempPath()) -child AboutTmp
    if (-not (Test-Path $destPath)) {
        [void](New-Item $destPath -ItemType Directory)
    }

    foreach ($topic in $topics) {
        $i++
        [int]$pct = ($i/$count)*100
        $name = $topic.name.split(".")[0]
        Write-Verbose "Processing $($topic.name)"
        $dl = Join-Path -Path $destPath -ChildPath $topic.name
        Try {
            $progParam.currentOperation = $topic.download_url
            $progParam.percentcomplete = $pct
            Write-Progress @progParam

            if ($PSCmdlet.ShouldProcess($topic.name,"Download help content")) {
                Invoke-WebRequest -Uri $topic.download_url -OutFile $dl -UseBasicParsing -errorAction Stop
            }
        }
        Catch {
            Write-Warning "Failed to get $($topic.name). $($_.exception.message)"
        }

        $progParam.status = "Processing files"
        if (Test-Path $dl) {
            #strip off heading
            $progParam2 = @{
                Activity = "Reformatting content..."
                Status = $dl
                id = 2
                currentOperation = $topic.name
                ParentID = 1
            }
            Write-Progress @progParam2
            $content = Get-Content -Path $dl
            $content | Select-Object -skip 8 -first 2 | Set-Content -Path $dl -force
            #insert the about heading
            "## $name `n" | Add-Content -path $dl
            #insert the rest of the content
            $content | Select-Object -skip 10 | Add-Content -path $dl -Force
        }

    } #foreach topic

    $progParam.currentOperation = $null
    Write-Progress @progParam
    $progParam3 = @{
        Activity = "Generating external help"
        Status = $helpPath
        CurrentOperation = "...please wait"
        ID = 2
        ParentID = 1
    }

    Write-Progress @progParam3

    Write-Verbose "Generating help content to $helpPath ... please wait"
    if ($pscmdlet.ShouldProcess($destPath,"Create external help")) {
        New-ExternalHelp -Path $destPath -OutputPath $helpPath -Force
    }
    $progParam3.Completed = $True
    Write-Progress @progParam3

    #clean up
    if (Test-Path $destPath) {
        Write-Verbose "Cleaning up temporary download folder"
        Remove-Item -Path $destPath -Recurse -Force
    }
    Write-Host "You might need to start a new PowerShell session to see the new help." -ForegroundColor Green
}
else {
    Write-Warning "No about topics found"
}

这是一个脚本文件，因此您可以使用完整路径运行它。它将检测您的 PowerShell 版本和默认位置。如果您不想覆盖现有的帮助内容，则可以指定备用路径。如果您需要，该脚本具有基于注释的帮助。

运行脚本

当您运行该脚本时，它会将特定于内容的版本从 Github 下载到临时文件夹。然后重新格式化每个文件，以便 Platyps 模块中的 New-ExternalHelp 命令可以生成 about 帮助主题。

您可能需要重新启动 PowerShell 才能获取新的帮助主题。另请注意，某些源 Markdown 不能很好地格式化为文本。目前我们受到 Platyps 模块或源 Markdown 的限制。但它仍然应该作为帮助可读。

该脚本下载内容并将其保存到 EN-US 文件夹。在 Windows PowerShell 中，如果您没有看到 $pshome\en-us 下的文件，您需要尝试此脚本。

我希望你能让我知道你的想法。