Summary: Learn how to use the updatable Help feature in Windows PowerShell.
Microsoft Scripting Guy, Ed Wilson, is here. Our guest blogger today is June Blender.
June Blender is a senior programming writer on the Windows PowerShell team at Microsoft, an avid Windows PowerShell user, and a passionate user advocate. She writes the Help topics that you see when you type Get-Help. She lives in magnificent Escalante, Utah, where she works remotely when she's not out hiking, kayaking, or convincing lost tourists to try Windows PowerShell. She believes that outstanding documentation is a collaborative effort, and she welcomes your comments and contributions for Windows PowerShell Help.
Twitter: @juneb_get_help
Windows PowerShell Team Blog
And now … here is June!
How I learned to love Updatable Help
There are many approaches for writing a Help system, and you've probably seen them all. There's the traditional authoritative "Father Knows Best" approach that churns out topics that the developers like. The poor writer sits in isolation tossing topics over the fence and hoping they're really helpful without really knowing. There's the modern wiki approach where you trust your customers to write your Help system. It's cheap (almost free), but rarely comprehensive and with quality that varies from terrific, to "What were they thinking?," and everything in between.
To be honest, we designed the Windows PowerShell Help system in the traditional way, but I'm not the type to sit in isolation. In fact, if you know me, you'll know that I don't sit much at all. So, I tossed myself over the fence with the topics and listened carefully to the feedback.
I realized that the best Help is collaborative. It combines the knowledge of the design team to explain the intent of a feature, the development team to explain how the feature works, the test team to point out "gotchas," beginning users to identify missing instructions that we assumed everyone knew, intermediate users to explain how the feature works in the real world and to satisfy multiple learning styles, and advanced users to show us ways of using a feature that we never even anticipated. In this collaboration, the writer provides a point of contact, technical expertise, a logical framework, and clear simple language.
Beginning in Windows PowerShell 2.0, we tried this approach, and users really appreciated it. I added dozens of examples, corrected errors, simplified and explicated, rewrote sections, and added new About topics—some of them written by users. (Did you know that Kirk Munro of Posholic.com fame wrote about_Operator_Precedence?) We added a Documentation Bug section to the Windows PowerShell page on Microsoft Connect, I started the Windows PowerShell Community Documentation Review, and I encouraged users to write directly to me (juneb@microsoft.com) and to tweet bugs and suggestions (@juneb_get_help). And you did! Thank you!
But our publishing system didn't support our collaborative model. Our writing deadlines precede code deadlines by 6-8 weeks, almost guaranteeing that the Help is outdated before it's shipped, and we couldn't correct the Help files that we shipped, because they're part of Windows. So, we updated the online version of the Help topics in the TechNet Library and told you to use the online Help whenever possible. But that strategy didn't fit the shell model, where Help is at the command prompt.
The solution, Updatable Help, is the brain-child of Dan Harman, a Windows PowerShell senior program manager. If you love Updatable Help, you need to thank Dan. Updatable Help downloads and installs the latest Help files on your computer. When you have the Help files, you simply type Get-Help. You don't even need to restart Windows PowerShell.
You can download the Help files from the Internet, but if you're not connected to the Internet, you can download them from a local file share. Administrators can use a Group Policy setting to specify a file share and prevent users from downloading Help from the Internet. And you can set it up to work automatically so you never have to think about it. Best of all, anyone who authors a module can support Updatable Help.
The Update-Help cmdlet
The foundation of Updatable Help is the Update-Help cmdlet. This is one of the most powerful and comprehensive cmdlets in Windows PowerShell.
Here's what Update-Help does by default:
- Finds all of the modules that are installed on your computer (in the value of the PSModulePath environment variable) plus those in the current session.
- Finds the online location of Help files for each module.
- Checks to see if you have the latest Help files for the module on your computer.
- Downloads the newest Help files if you don't have them.
- Unpacks the Help files (they're in CAB files).
- Verifies the XML and file types for security.
- Installs them in the language-specific subdirectory of the module directory.
You just sit and smile, thinking about what it would have been like if you had to do this manually. When it's done, you type Get-Help. You don't even need to restart Windows PowerShell. Every time I run Update-Help, I feel like I applauding.
As you might expect, Update-Help has lots of parameters that you can use to customize the process, including specifying the modules and the locales, and using Verbose to watch each step of the process.
And you don't even need to remember to type Update-Help. You can set it as a scheduled task or scheduled job, or put an Update-Help command in your Windows PowerShell profile. There's a built-in throttle that prevents Update-Help from running more than once each day.
If you don’t have the Help files, Update-Help prompts you to install them (once for each user on each computer). If you say yes, it runs Update-Help. If you say no, and Get-Help detects that you don't have the Help files, it auto-generates a rudimentary Help file for each command from the code, much like Get-Command.
Using Windows PowerShell 2.0? Sorry, but Updatable Help isn't supported. If you're using Windows 8 or Windows Server 2012, which have both Windows PowerShell 2.0 and 3.0, switch to Windows PowerShell 3.0 (type PowerShell or PowerShell.exe) before running Update-Help.
No Internet? Use the Save-Help cmdlet
If you have computers that aren't connected to the Internet or you don't want thousands of client machines accessing Internet downloads, there's the companion Save-Help cmdlet.
Save-Help works a lot like Update-Help, but it doesn't unpack and install the Help files on your computer. Instead, it saves the Help file package for each module in a file system directory that you specify. When users need to update Help, they use the SourcePath parameter of the Update-Help cmdlet to tell Update-Help to get the Help files from the file share instead of from the Internet.
Administrators can prevent users from downloading Help from the Internet. The "Set the default source path for Update-Help" Group Policy setting specifies a file system location for value of the SourcePath parameter. When users type Update-Help, they get the Help from the file system directory automatically. Users can override the default source path with an alternate file system location, but they can't eliminate the SourcePath parameter and then use Update-Help to download Help files from the Internet.
Enhanced online Help
There are a few gotchas, as always. To update Help for modules that are installed in the Windows PowerShell installation directory, $pshome, you need to start Windows PowerShell with the "Run as administrator" option. Otherwise, you get an "access denied" error. To run as administrator, you need to be a member of the Adminstrators group on the computer, and not everyone is.
To provide extra help to users who cannot download Help files, we've improved the online Help experience in Windows PowerShell. In Windows PowerShell 2.0, Get-Help -Online works only when the Help files are on the computer. That's because the URL (the Internet address) of the online version of the Help topic is in the Help file in the first related link.
In Windows PowerShell 3.0, the Internet address of the Help topic for a cmdlet is part of the cmdlet (it's the HelpUri property value). So if you have the cmdlet, you have the link. This works for all types of commands, including simple and advanced functions, CIM commands, and workflows.
Read all about it!
You can read all about Updatable Help in about_Updatable_Help and in the Help topics for the Update-Help and Save-Help cmdlets.
If you want to add Updatable Help and online Help to modules that you author, you can learn how in Supporting Updatable Help and Supporting Online Help.
If you're interested in the nitty-gritty internals (I always am), I snuck a really detailed How Updatable Help Works into the SDK topics.
Troubleshooting Updatable Help
Here's the "call to action" part. I'd like to work with you to produce an outstanding guide for troubleshooting problems with Updatable Help. I'm adding a moderated (by me) troubleshooting page to the TechNet Wiki, but I'll also accept questions, suggestions, and solutions by e-mail (juneb@microsoft.com), the Windows PowerShell page on Microsoft Connect, and Twitter (@juneb_get_help)—and in person, of course.
Here are some of the obvious issues:
- Some modules do not support Updatable Help, so you're not going to be able to update your Help files. Update-Help skips these by default. To find modules that support Updatable Help, use:
Get-Module –ListAvailable | where HelpInfoUri
(Get-Module <ModuleName>).HelpInfoUri
- Some modules support Updatable Help, but they don’t yet have any Updatable Help files in their Internet location. The error message says, "The HelpInfoUri does not resolve to a container." Nothing you can do but wait. (This error also appears when the HelpInfoUri or module GUID in the HelpInfo XML file is wrong.)
- Network connection issues. The error message says, "Unable to retrieve the HelpInfo XML file." There might be a problem with the XML file, but often this is a network issue. Retry.
-
I can't see the Updatable Help files for Windows modules in their download location. I went to the URL that's in the value of the HelpInfoUri property, but didn't see anything.
-
The Help files for Windows modules are stored in an Internet location that doesn't have any web pages. It only contains the files, so there's nothing to see.
-
For which system modules have I downloaded Updatable Help?
(Hint: Look for a HelpInfo XML file.)
Split-Path (dir $pshome\Modules\*HelpInfo.xml -Recurse).Directory -Leaf
- How do I tell which version of a module's Help files I have installed?
#Get-UpdateHelpVersion.ps1
Param
(
[parameter(Mandatory=$False)]
[String[]]
$Module
)
$HelpInfoNamespace = @{helpInfo="http://schemas.microsoft.com/powershell/help/2010/05"}
if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} }
else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} }
foreach ($mModule in $Modules)
{
$mDir = $mModule.ModuleBase
if (Test-Path $mdir\*helpinfo.xml)
{
$mName=$mModule.Name
$mNodes = dir $mdir\*helpinfo.xml -ErrorAction SilentlyContinue | Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture"
foreach ($mNode in $mNodes)
{
$mCulture=$mNode.Node.UICultureName
$mVer=$mNode.Node.UICultureVersion
[PSCustomObject]@{"ModuleName"=$mName; "Culture"=$mCulture; "Version"=$mVer}
}
}
}
~June Blender
Updatable Help: Because stale Help is so v2.
Thanks for sharing, June. Join me tomorrow when we will have another exciting day using Windows PowerShell.
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