Module manifest gotcha
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.
