Module manifest gotcha

January 14, 2010

2 comments

Module authors can use a manifest file for their modules (although this is not required). A manifest file is a .psd1 file that contains a hash table. The keys and values in the hash table describe the contents and attributes of the module, define the prerequisites, and determine how the components are processed. How do you know all the hash table keys? You don’t have to. PowerShell can create the file for you with the New-ModuleManifest cmdlet.

New-ModuleManifest creates a new module manifest (.psd1) file, populates its values, and saves the manifest file in a specified path. You can further edit the file and change the values simply by opening it in your favorite text editor. To verify that your manifest file is valid use the Test-ModuleManifest cmdlet.

OK, now to the gotcha. Here’s a snippet from PSRemoteRegistry manifest file:

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '2.0'

# Minimum version of the Windows PowerShell host required by this module
PowerShellHostVersion = '2.0'
 

Modules were introduced in PowerShell 2.0 so it was natural to set the value of ‘PowerShellVersion’ to 2.0. I assumed the same for ‘PowerShellHostVersion’ which proved to be wrong. Why?

When you load the PSRemoteRegistry module in PowerShell everything is working great. PowerShell’s version and Host version are set to 2.0:

PS > $host.Version

Major  Minor  Build  Revision
-----  -----  -----  --------
2      0      -1     -1


PS > $PSVersionTable

Name                           Value
----                           -----
CLRVersion                     2.0.50727.4927
BuildVersion                   6.1.7600.16385
PSVersion                      2.0
WSManStackVersion              2.0
PSCompatibleVersions           {1.0, 2.0}
SerializationVersion           1.1.0.1
PSRemotingProtocolVersion      2.1


BUT,
this is not the case with many PowerShell IDE’s. For example, both of the most popular PowerShell editors, PowerGUI and PowerShell Plus, host versions are not 2.0. These editors use a custom host and the developers can define whatever value they want for the version. If you try to load PSRemoteRegistry in one of these editors you’ll get a similar error to this:

The current PowerShell host is: 'PowerShellPlus Host' (version 1.0.0.0). 
The module '...\PSRemoteRegistry.psd1' requires a minimum PowerShell host version of '2.0' to execute.

I would like to thank @jkavanagh58 for reporting the issue!

There are many PowerShell editors out there and you can’t know for sure what host version each one uses, you do though, want your module to load in whatever editor the user uses. To be on the safe side, do not set a value for ‘PowerShellHostVersion’.

UPDATE (01/25/2010), Make sure you read the follow-up post from the PowerShell Team blog.

Add comment
facebook linkedin twitter email

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

2 comments

  1. Joel "Jaykul" BennettJanuary 14, 2010 ב 21:54

    There’s one exception: if your module is dependent on a specific host.

    If you’ve written a module for “PoshConsole”:http://poshconsole.codeplex.com which exploits the WpfHost display features or the BgHost hotkeys feature…

    Or if you’ve written “ISEPack”:http://code.msdn.microsoft.com/PowerShellPack based on the menu and script-editor features of PowerShell ISE…

    Then it makes sense to specify the PowerShellHostName and the PowerShellHostVersion together, or PowerShellHostName by itself, but never PowerShellHostVersion by itself.

    Reply
  2. blogs.microsoft.co.ilMarch 27, 2011 ב 13:11

    Module manifest gotcha.. He-he-he :)

    Reply