Wednesday, March 07, 2012

PowerShell Version 3–Updatable Help (continued)

In a recent blog article I discussed the new updatable help feature of PowerShell V3. In that post I described the Update-Help cmdlet and shows how you use that cmdlet to up date your help information. The Update-Help cmdlet knows how to go online to find, download and install updated help information for both the core PowerShell modules plus any additional modules on your system. The PowerShell V3 module feature enables Get-Help to know (or be told!) where to look for updated material for each module, and does what is needed!

But what if you are offline, or you are in an air-gap network, isolated from the Internet. Well, obviously, in that situation, Update-Help can not go online and get the necessary updates. But PowerShell does provide a cmdlet, Save-Help, that can get the necessary help information and can store it. You can then copy somewhere Update-Help can then find – in the case of an airgap network, you could copy the help information to a memory stick, then use sneaker-ware to copy that material onto the airgap network.  Let’s take a look at both these aspects.

To save the help files, you use Save-Help, specifying a destination path (where you want the files saved). Optionally, you can specify the UI culture for which you want to get updated help. Specifying the –Verbose switch provides more output describing what Save-Help is doing. By default, you can run Save-Help or Update-Help just once per day (per machine). To over ride this, use the –force parameter.

Here’s what Save-Help looks like in my Windows 7 workstation:

 

SNAGHTML1f74f896

As you can see from this screenshot, PowerShell gets the files and stores them in the path folder, which then looks like this:

SNAGHTML1f79c392

Each PowerShell module has the two files that make up the extensible help for that module:

  • An XML file – this identifies the UI version of the help content (found in the XML).
  • A cab file – containing updated MAML and about_* files. Each file in the cab file represents something to be moved (later) by update help.

Each pair of files is named using a simple naming convention of : <module name>_<module guid>_<ui culture>_<helpinfotype, where <helpinfotype> is either HelpContent (in which case the file has a .CAB extension), or HelpInfo (in which case the file has a .XML extension).

You will notice that when I got the help, Save-Help could not find help for the module TFL. That’s mainly because that help information has not yet been written and saved in EN-US locale (well, not yet anyway!). I will do another blog post at some point where I explain how to add updatable help to your module.

To install this help on the air-gap network or machine, or one you want to update offline, you first have to save the files to somewhere you can later access them from the network/machine. As I suggest above, a USB memory stick can be used to transport them (or CD, etc). Once you have the files moved to their appropriate place, you use Update-Help, specifying the SourcePath parameter and providing the path to where the help files are available. The update would look something like this:

SNAGHTML1f8d8193

The Update-Help cmdlet (when verbose is specified), displays the XML files parsed and whether or not the associated HelpInfo file was processed and the help files in the CAB file that have been moved to their appropriate location.

 

Technorati Tags: ,,

6 comments:

Daniel Stover said...

O.O

Thomas said...

Thanks for the comment David - I just hope it's meant positively!!

Mark Stang said...

any idea how to get save-help to work through a proxy? seems like a pretty simple thing MS has left out

Thomas said...

@Mark - setup the proxy in IE and it +should+ work.

Mika Seitsonen said...

Great info, Thomas. How to include help for those modules which are not installed on the machine where Update-Help is run?

Thomas said...

Mika,

Re-run the Update-Help cmdlet later, when the new module(s) are added is probably the easiest and fastest way.