Updating Help for older versions of PowerShell

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:tempPowerShell-Docstoolsbuild-updatedhelp.ps1 -sourceFolder C:tempPowerShell-Docsreference5.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:tempupdatablehelp5.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:tempupdatablehelp5.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

• Update-Help
• PlatyPS
• Pandoc

The post Updating Help for older versions of PowerShell appeared first on PowerShell.