Where is PowerShell Updatable Help for Windows Modules?

Where is PowerShell Updatable Help for Windows Modules?

  • Comments 8
  • Likes

Summary: Get the inside scoop on what's up with Windows PowerShell 3.0 Updatable Help.

Hey, Scripting Guy! Question Hey, Scripting Guy! I love PowerShell 3.0—I really do. There is one thing that I do not understand, however, and that is what’s up with the Help? I mean one of the nice things in Windows PowerShell 1.0 and 2.0 was the MAN pages, but now they are gone. I hope this is not part of a trend to ruin the product. Say it ain’t so!

—ET

Hey, Scripting Guy! Answer Hello ET,

Microsoft Scripting Guy, Ed Wilson, is here. ET, the first thing you need to know about Windows PowerShell 3.0 is that it does not ship with Help files. These need to be installed from the Internet by using the Update-Help cmdlet. But, when it comes to questions about Help in Windows PowerShell, I always like to defer the questions to June Blender because she is the writer who works very closely with the Windows PowerShell team to produce the Help documentation. So, ET, I passed your question to June, and she agreed to write an answer. Today we have a guest blogger to start off the week—June Blender is back with us. To learn more about June, see her blog, Understanding and Using Updatable PowerShell Help.

Take it away June…

Have you been trying to use the new Update-Help or Save-Help cmdlets in Windows PowerShell 3.0? You get lots of great Help topics that you know are never stale, but you also get a screen full of error messages. I’m here to explain why.

You sit down, heart aflutter, start Windows PowerShell with the "Run as administrator" option, and type the magic words:

[ADMIN] PS C:\> Update-Help

 Image of message

Soon, the Write-Progress status bar appears, reeling off the names of modules as it downloads and installs updated Help files.

When the command completes, you run a command that determines how many system modules on the machine now have updated Help. The following command looks for HelpInfo XML files, which are downloaded and updated along with the Help files.

[ADMIN]: PS C:\ > (dir $pshome\Modules\*\*HelpInfo.xml, $pshome\*HelpInfo.xml).count

52

Note   I ran this on my virtual maching on September 12. Your results will vary with the Windows version, the roles and features that are installed on the system, and the date and time. Our elves seem to work 24/7.

But then you notice the following vile red error message.

Image of message

 And you check to see how many system modules support Updatable Help with the following command.

 [ADMIN]: PS C:\ > (Get-Module -List | where {$_.ModuleBase -like "*System32*" -and $_.HelpInfoUri}).count

82

What's going on here? Why is this failing since Windows PowerShell has already Released to Manufacturing (RTM)? Why don’t I have Help for all supported modules? I'm here to explain.

What's in the error message?

First, a quick primer on the error messages. They contain too much information for most users, but they are designed to help module authors debug errors in Updatable Help.

Here’s the most common one.

Image of message

In simplest terms, this message says that Update-Help looked for Updatable Help files where you told it to look, but there were no Help files there.

In technical terms, it went to the location specified by the URI in the value of the HelpInfoUri key in the module manifest, but it didn't find a container that might hold a HelpInfo XML file at that location.

Instead, it found a friendly, but clearly unexpected, web page: Windows Server Future Resources.

Here’s another interesting error message you might see from time to time. This is the HelpInfoXmlValidationFailure message.

Image of message

In this message, Update-Help is reporting that it looked for Updatable Help files, but instead, it found a Document Type Definition (DTD) file.

In 99.9314159% of cases, this means that Updatable Help is not yet published and the module is using a placeholder value that links to a complex website, like the Welcome to Microsoft site—not the type of thing that Update-Help expects.

On the positive side, this shows that the security features of Update-Help are working to protect your computer. Update-Help won’t install anything that doesn’t pass its strict inspection.

Why am I getting an error message?

Updatable Help is a brand new feature that required all new tools and processes inside Microsoft. Many people had to be trained to use the tools, and of course, there were a few bugs.

And those awesome 2500+ cmdlets, functions, CIM commands, and workflows? The same team had to write Help for all of them. That required training, in addition to more new tools and processes. Our teams are learning Windows PowerShell and Updatable Help just like yours are!

We're really pleased that we've been able to deliver Help for more than 50 modules and 1000 commands, and we're working as fast as we can to finish the job.

In fact, many modules, including the eleven core modules (Microsoft.PowerShell.* and PS*) are ready for a second update—coming soon!

And while you're waiting…Get-Help -Online

Some modules that don't yet have Updatable Help already have online Help. That's because we use online Help to test the Help content that we package in Updatable Help. So while you're waiting for Updatable Help, you can use the online Help.

Online Help also works for modules that cannot or do not support Updatable Help. For example, the BitsTransfer module cannot support Updatable Help. Its RTM Help files are included in the module. But updated Help files are online, and you can use the Online parameter of Get-Help to get them.

[ADMIN]: PS C:\>Get-Help Start-BitsTransfer -Online

And while you're waiting for online Help…

Well, you can get to know some of the other modules that you've downloaded, but you have not used. Like the nifty DTC Cmdlets module or the cool International Settings Cmdlets module.

"I love waiting for Updatable Help…” said no one…ever.

New Updatable Help files are being released every day. So be sure to run an Update-Help command every day, either manually or in a scheduled job or scheduled task. For more information, see Ed’s blog, Create a PowerShell Scheduled Job.

And if you follow my Twitter feed, I'll let you know when new Updatable Help topics are released: @juneb_get_help.

~June

Thank you, June, for writing a useful, informative, and helpful blog.

ET, that is all there is to using the Updatable Help feature from Windows PowerShell 3.0. Guest blogger Week will continue tomorrow when Marco Shaw will share his script and knowledge.  

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi June,

    updateable help is surely a very interesting and important feature!

    It's great to have it and your article does explain some of the gotchas!

    Running Update-Help on my company workstation ( on a german WIN7 enterprise OS with

    PS 3.0 release version installed ) I receive some other error messages:

    PS C:\Windows\system32> Update-Help

    Update-Help : Fehler beim Aktualisieren von Hilfe für die Module "ISE, Microsoft.PowerShell.Management, Microsoft.PowerShell.Utility, CimCmdlets,

    Microsoft.PowerShell.Diagnostics, Microsoft.PowerShell.Host, Microsoft.PowerShell.Security, Microsoft.WSMan.Management, PSScheduledJob,

    Microsoft.PowerShell.Core" mit den Benutzeroberflächenkulturen {de-DE}: Die XML-Datei "HelpInfo" für die Benutzeroberflächenkultur de-DE kann nicht

    abgerufen werden. Stellen Sie sicher, dass die HelpInfoUri-Eigenschaft im Modulmanifest gültig ist, oder überprüfen Sie die Netzwerkverbindung, und

    führen Sie den Befehl dann erneut aus.

    In Zeile:1 Zeichen:1

    + Update-Help

    + ~~~~~~~~~~~

       + CategoryInfo          : ResourceUnavailable: (:) [Update-Help], Exception

       + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShell.Commands.UpdateHelpCommand

    Even if it is german, you could probably tell me the error cause, ... I hope ...

    Might there be no german help topics available?

    (If not, where could I have looked that up? Is there a certain URL for localized help topics available?)

    Or maybe this is an issue just related to our company's security settings ( like GPOs, firewall and so on)

    What could we do in this case? Is there a Powershell Help Update Server available like the local WSUS servers that we are running ... :-)

    I can't tell one possible cause of failure from the other, I'm afraid ...

    Klaus.

  • I am getting the same error, but in english.

    update-help : Failed to update Help for the module(s) 'ISE, Microsoft.PowerShell.Management,

    Microsoft.PowerShell.Utility, CimCmdlets, Microsoft.PowerShell.Diagnostics, Microsoft.PowerShell.Host,

    Microsoft.PowerShell.Security, Microsoft.WSMan.Management, PSScheduledJob, PSWorkflow, PSWorkflowUtility,

    Microsoft.PowerShell.Core' 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 -Verbose -force

    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~

       + CategoryInfo          : ResourceUnavailable: (:) [Update-Help], Exception

       + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShell.Commands.UpdateHelpCommand

    When I run the command where she gets 52, I get 0.

    When I run the command where she gets 82, I get 11.

    I am behind a proxy, but it is set up in IE.

  • Hi, Klaus,

    There are no German help topics yet published for the commands in Windows modules. For Windows PowerShell 3.0, help topics are translated based on user demand. To register a request for localized help topics, please vote for one of the language-request bugs on Connect. Here is the German language request bug: connect.microsoft.com/.../please-add-documentation-in-german-language-for-powershell-3-0

    Also, Windows PowerShell 3.0 was shipped with a bug that prevents English-language help topics from being displayed on localized versions of Windows, even when the fallback language is English. A fix will be available soon from Windows Update for all supported versions of Windows. To get that fix on demand for Windows 8 and Windows Server 2012, go to support.microsoft.com/.../2758246.

    Hope this helps,

    June

  • Hi, Jon Harvey,

    Are you running Update-Help elevated? To get help for modules in $pshome, start Windows PowerShell with the "Run as administrator" option. Then, type: Update-Help.

    Thanks,

    June

  • We're running behind a corporate firewall (with password authentication) and I am unable to get updates for help.  Is there any way to update help in these circumstances?

  • hi!

    just wanted to mention that the link to Ed's blog is wrong ...

    KR

    Guennie

  • @Guenther Schmitz  thanks for pointing out the broken link, I believe I just fixed it.