Updating Help for older versions of PowerShell

[Server Man]

PowerShell’s Updatable Help system was introduced in PowerShell 3.0. It was designed to assure that you always have the newest help topics on your local computer so that you can read them at the command line. Help was updated with every new release and periodically between releases. For you, the end user, the Update-Help cmdlet makes it easy to download and install the latest version. However, you may have noticed that the updated help hasn’t changed for a long time and does not match the documentation available on docs.microsoft.com.

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 MicrosoftDocs/PowerShell-Docs --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.

Continue reading...