Friday, August 17, 2012

PowerShell Version 3 – Help Soon Coming

As I blogged in March, PowerShell V3 comes with Updatable help. This is a fantastic new feature that allows for Microsoft, and any PowerShell module maker, to create updated help for the code in their modules. Thus errors can get fixed in the in-box help. The implementation Microsoft chose is not perfect – there is only minimal help ‘in the box’. You have to use Update-Help in order to get the help contents. I regard this as a bug, but Microsoft describe it as a feature. Irrespective, I do like this feature!

Now that Windows 8 is released, so is PowerShell V3. Sadly, not all the help text has been released. Given the thousands of new cmdlets that ship with V3 and Server 2012, this is not surprising. While it would have been nice to think that help text is a sufficiently important part of the product to complete before RTM – that wasn’t the way it was done. So in order to get help in PowerShell V3, you will need to continue to use Update-Help. Once all the help text is available, I’ll try to post again!

One artifact of this situation is that Update-Help generates a couple of errors. Today, if you try to update help, you may see the following error:

Update-Help : Failed to update Help for the module(s) 'CimCmdlets' with UI culture(s) {en-US} : For security reasons DTD is prohibited in this XML document. To enable DTD processing set the DtdProcessing property on XmlReaderSettings to Parse and pass the settings into XmlReader.Create method.
At line:1 char:1
+ Update-Help -force -verbose
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Update-Help], Exception
    + FullyQualifiedErrorId : HelpInfoXmlValidationFailure,Microsoft.PowerShell.Commands.UpdateHelpCommand

The problem here is that the CimCmdlets (and possibly other modules) point off to Microsoft’s web site where Update-Help is meant to be able to find the updated help for this module (or modules). Sadly, the pointer from the module points to a nonexistent page, which Microsoft helpfully points off to Bing. That’s great for most things, but Update-Help gets the Bing page, which it tries to read as XML which is not quite right.

This is sad, but PowerShell updated help is still a work in progress – and given the magnitude of the task, I suppose the PowerShell Team can be forgiven. I must say, a LOT of modules have been updated over the past few days, and I would expect all the help text to be complete well before General Availability of Windows 8 and Server 2012.

Bottom line: Updatable help rocks, but we need just a bit of patience till it’s all here!

 

3 comments:

MNEsther said...

so, what is THIS all about?
+++++++++++++++++++++++++++
PS C:\MyScripts> Update-Help -Force
Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Management,
Microsoft.PowerShell.Utility, CimCmdlets, ISE, 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 connect to Help content. Make sure the server is available and then try the
command again.
At line:1 char:1
+ Update-Help -Force
+ ~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [Update-Help], Exception
+ FullyQualifiedErrorId : UnableToConnect,Microsoft.PowerShell.Commands.UpdateHelpCommand

PS C:\MyScripts>
++++++++++++++++++++++++++

MNEsther said...

So, what is THIS all about?
===========================
PS C:\MyScripts> Update-Help -Force
Update-Help : Failed to update Help for the module(s) 'Microsoft.PowerShell.Management,
Microsoft.PowerShell.Utility, CimCmdlets, ISE, 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 connect to Help content. Make sure the server is available and then try the
command again.
At line:1 char:1
+ Update-Help -Force
+ ~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [Update-Help], Exception
+ FullyQualifiedErrorId : UnableToConnect,Microsoft.PowerShell.Commands.UpdateHelpCommand

PS C:\MyScripts>
==============================

Thomas said...

You don't give any details of your network, so it's hard to know for sure, but... The error message ' Unable to connect to Help content. Make sure the server is available and then try the
command again' should give a clue that the host is not able to get to the help content.