Updating Help for older versions of PowerShell

Sean Wheeler

September 17th, 20193 0

It turns out, maintaining Updateable Help is difficult. The steps required to build and host the updated files are mostly manual. We made improvements to our build automation in the release of PowerShell 6 and now host the help files in Azure blob storage. However, for various internal reasons, we haven’t been able to change the way we distribute the help files for previous versions. Because of that, the downloadable help files for version 5.1 and older have not been updated since PowerShell 6.0 released.

Manually update local help from source

The good news is we have been updating the content. You can see that on the Docs site. And, since the documentation is open source, you can build the updated help content locally and install it on any machine you want. To make it easier to build a specific version, I have created a script that creates the files you need. The process is simple:

  1. Clone or download the PowerShell-Docs repository
  2. Run build-updatedhelp.ps1 to build version of the documentation you want to update
  3. Run Update-Help to install the newly built help

Prerequisites

Almost all the documentation on the Microsoft Docs platform is written in Markdown. This is the case for PowerShell documentation. However, the help files used by PowerShell are plain text files for About_ topics and Microsoft Assistance Markup Language (MAML) files for cmdlet reference. MAML is XML conforming to a well defined schema. The MAML schema describes the structure of the help content. There is no layout or style information within the MAML files. Rendering this help content in PowerShell is managed by the Get-Help cmdlet. To build the content for Get-Help, we must convert the Markdown source files to plain text and MAML. This is done using the following tools:

  • PlatyPS – an open source tool that creates PowerShell help content – Converts Markdown to MAML.
  • Pandoc – an open source tool that converts documents to or from many different formats – Converts markdown to plain text for About topics.
  • build-updatedhelp.ps1 – This script downloads PlatyPS and Pandoc, then builds CAB files that can be installed using Update-Help.

Step by step instructions

  1. Clone or download the PowerShell-Docs repository

    cd C:\temp
git clone https://github.com/MicrosoftDocs/PowerShell-Docs.git --depth 1
     Output
    Cloning into 'PowerShell-Docs'...
remote: Enumerating objects: 3588, done.
remote: Counting objects: 100% (3588/3588), done.
remote: Compressing objects: 100% (2169/2169), done.
remote: Total 3588 (delta 2270), reused 1754 (delta 1403), pack-reused 0
Receiving objects: 100% (3588/3588), 8.63 MiB | 14.70 MiB/s, done.
Resolving deltas: 100% (2270/2270), done.
Updating files: 100% (3905/3905), done.

    NOTE: Cloning the repository using --depth 1 minimizes the history that is downloaded. This reduces the download size. This is the quickest way to get the latest content. If you intend to contribute changes to the documentation, you should first create a fork then clone your fork.

  2. Run build-updatedhelp.ps1 to build version of the documentation you want to update. This script is in the tools folder of the PowerShell-Docs repository. This is script is based on thebuild.ps1 script that is used to build the the documentation today. This script downloads PlatyPS and Pandoc then builds the documentation in the target folder. For example, run the following command to build the help content for PowerShell v5.1:

    C:\temp\PowerShell-Docs\tools\build-updatedhelp.ps1 -sourceFolder C:\temp\PowerShell-Docs\reference\5.1 -Verbose

    The script builds the updateable help content for all Markdown source files in each module subfolder.

  3. Run Update-Help to install the newly built help

    This command must be run within the version of PowerShell that is being updated. Update-Help overwrites the local help content with whatever content you target.

    Installing help in PowerShell 5.1 (and older) requires administrative rights. You must run the following command from an elevated session:

    Update-Help -SourcePath c:\temp\updatablehelp\5.1 -Recurse -Force

    When the Update-Help command completes, you may receive an error message similar to this:

    Update-Help : Failed to update Help for the module(s) 'ActiveDirectory, AppBackgroundTask,
AppLocker, AppvClient, Appx, AssignedAccess, BestPractices, BitLocker, BitsTransfer, BranchCache,
ConfigCI, Defender, DirectAccessClientComponents, Dism, DnsClient, EventTracingManagement,
HgsClient, HgsDiagnostics, HostNetworkingService, Hyper-V, IISAdministration, International,
iSCSI, IscsiTarget, Kds, MMAgent, MsDtc, NetAdapter, NetConnection, NetEventPacketCapture,
NetLbfo, NetLldpAgent, NetNat, NetQos, NetSecurity, NetSwitchTeam, NetTCPIP,
NetworkConnectivityStatus, NetworkControllerDiagnostics, NetworkSwitchManager, NetworkTransition,
NFS, PcsvDevice, PKI, PnpDevice, PrintManagement, ProcessMitigations, Provisioning,
RemoteDesktop, ScheduledTasks, SecureBoot, ServerManager, ServerManagerTasks, SmbShare,
SmbWitness, StartLayout, Storage, TLS, TroubleshootingPack, TrustedPlatformModule, UEV,
VpnClient, Wdac, WebAdministration, Whea, WindowsDeveloperLicense, WindowsErrorReporting,
WindowsSearch, WindowsUpdate, WindowsUpdateProvider' with UI culture(s) {en-US} : Unable to
retrieve the HelpInfo XML file for UI culture en-US. Make sure the HelpInfoUri property in the
module manifest is valid or check your network connection and then try the command again.

At line:1 char:1
+Update-Help -SourcePath c:\temp\updatablehelp\5.1 -Recurse -Force
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 + CategoryInfo          : ResourceUnavailable: (:) [Update-Help], Exception
 + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShell.Commands.UpdateHel

    This message is warning you that the update did not include help for the modules listed. The content for those modules is also kept up-to-date on Microsoft Docs, but the script we’ve provided doesn’t yet support the windows-powershell-docs repo where that content is hosted. However, it could potentially be extended to support that repo (and others) too, so stay tuned for updates.

NOTE: The build script downloads the supported versions Pandoc and PlatyPS to a temp folder on your computer. It does not overwrite version you may have installed already. The files are left behind in the temp folder.

Further reading

 

Sean Wheeler Principal Content Developer for PowerShell, Cloud + AI | C+E Skilling - Azure Deployments Team

Read next

PowerShell 7 Preview 4
We continue to make progress towards our PowerShell 7 release which currently is targeting December 2019 for a Release Candidate and January 2020 for General ...
Steve Lee
September 19, 2019
4 comments

3 comments

Discussion is closed. Login to edit/delete existing comments.

  • Mystery Man 0

    Hello! I managed to build the PowerShell-Docs repo with this script but I wasn’t so lucky building the Windows-Powershell-Docs repo. I receive funny error messages like:

    Write-Error : Cannot bind parameter ‘Exception’. Cannot convert the “Cannot validate argument on parameter ‘LandingPagePath’. Path ‘C:\Users\Frank.Abagnale.XI\Desktop\windows-powershell-docs-master\docset\windows\addsadministration\addsadministration.md’ is not a file.” value of type “System.Management.Automation.ErrorRecord” to type “System.Exception”.

    Write-Error : Cannot bind parameter ‘Exception’. Cannot convert the “The running command stopped because the preference variable “WarningPreference” or common parameter is set to Stop: [New-ExternalHelp] Cannot find ‘external help file’ in metadata for file C:\Users\Frank.Abagnale.XI\Desktop\windows-powershell-docs-master\docset\windows\hyper-v\hyper-v.md” value of type “System.Management.Automation.ErrorRecord” to type “System.Exception”.

    Write-Error : Cannot bind parameter ‘Exception’. Cannot convert the “Cannot bind argument to parameter ‘URI’ because it is an empty string.” value of type “System.Management.Automation.ErrorRecord” to type “System.Exception”.

    • Sean WheelerMicrosoft employee 0

      Yes, we said that it does not work for that content right now. We are working to fix that but I can’t say when that might happen.

      • Mystery Man 0

        Oh, really? The way the blog reads to me is “It works with the Windows-Powershell-Docs repo too, only we don’t guarantee or support it.”

        Anyway, I seem to have made it work since then. It still throws some other error messages, but the contents seem to be fine.

        Also, I was very uncomfortable with the fact that the script downloaded 55 MB Pandoc in each run to compile 16 MB worth of docs, so I re-wrote it to download it only once. So, question: How is the chance of this change being accepted if put it into a PR? I seem to remember Microsoft had a policy of not accepting PRs for tooling changes.

Feedback usabilla icon