Summary: Get the inside scoop on what's up with Windows PowerShell 3.0 Updatable Help.
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
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
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.
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.
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.
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