PoshCode Module Manifest Format:

GUID

The globally unique identifier for this module. Helps us tell modules apart

Name

The name of this module. Helps us find modules, and helps you guess what they’re for.

ModuleVersion

The version of this module. Together with the GUID, this is the unique key for the module. It should be incremented whenever you release it.

Description

A short description of the module. What it is, what it does, what it’s for.

ModuleType

Tells whether the module is a Script module or a Binary module (if they are both, then they are Binary).

Author

The person(s) who created this module. No organizations here, just people.

Company

A company (if there is one) that created this module or provides support for it.

Copyright

The copyright statement. You should always fill this out and assign copyright to the correct author, group or corporation.

License

The software license(s) that this module can be licensed under. It’s enough to use an acronym like “GPL v2” or “MIT” or “Ms-PL” ... but if you have a custom license you can specify a description of it or the full text of it. Multiple entries are allowed.

LicenseUri

The url(s) for a full copy of the license. If you’re using an open source license you can link to it’s page on opensource.org

Category

We’ll publish our official category list later, but the category is intended to be an assignment to a single category in a hierarchical tree.

Tags

A collection of user-assigned free-text keywords that help to categorize the module and serve as additional search terms.

Homepage

If the module has a home page on the internet, this is the URL. You can use the link to the PoshCode Docs page (which our cmdlets will generate for you) if you don’t have your own page.

Download

This is the link to download the module. If you’re hosting it on PoshCode, we will fill this in. If you’re hosting it elsewhere, this must be a download link. If it’s a commercial module that requires payment, you should leave this link empty unless you have a free trial download. Note: I’m still working on the commercial angle. Would it be helpful to include the price here? If we offered a way to sell your modules through PoshCode, would you use it?

RequiredAssemblies

Assembly names (or relative paths, if the assemblies are included in the module folder) for assemblies that must be loaded before the module will work. These should be the Assembly FullName, not a partial name.

RequiredModules

The names and versions (and GUIDs) of any modules that this module depends on.

PowerShellVersion

The version of Powershell required (2.0, for now).

FrameworkVersion

The version of the .Net Framework required. The framework version implies the CLR version, so we’ll just stick to this. I’m still toying with the idea of saying the list is 2.0, 3.0, 3.5, 3.5.1, and 4.0 … rather than allowing the normal version with the full four digits.

VersionChanges

This is either the list of changes in this version, or a complete list of the changes in previous versions.

Exported Cmdlets

The list of (binary) cmdlets exported by this module.

Exported Functions

The list of script functions exported by this module.

Exported Aliases

The list of aliases exported by this module.

Exported Variables

The list of variables exported by this module.

Deprecated things …

I’m leaning against having these items in the PoshCode manifest — they don’t seem to be helpful for finding or sorting or understanding a module.

• ModuleFile
• ModuleToProcess
• FormatsToProcess

• TypesToProcess

Comments Requested

I’m hoping for feedback about this list, what I might be missing, or if there’s anything in here I should leave out … let me hear it!

Scripts are still there, but they’re still basically done the way they are now: you just upload a single file.

Modules, however, will be treated specially. You’ll have to have an account to upload, but you’ll be able to just upload a .zip file of your module folder using your login and not fill in any other forms. Our system will take care of parsing the metadata out of the manifest in your module folder.

The problem is that I need a little data that isn’t a part of the standard module manifest format… and I can’t add it because PowerShell won’t load a module with extra fields in the manifest metadata hashtable: https://connect.microsoft.com/PowerShell/feedback/ViewFeedback.aspx?FeedbackID=421837 — My request was closed “by design” early in the beta cycle and I wasn’t able to convince them to rethink that.

At a minimum, PoshCode requires a LICENSE field, and a CATEGORY field (think of the categories on CPAN or TechNet Script Center).

So I’m having an informal poll. (you’ll have to “vote” by commenting or tweeting to me, because I want more than just “I choose A”).

Which option do you prefer, or can you think of a better way:

Require the License and Category to be part of the PRIVATEDATA field in the standard manifest

This might require authors to rewrite parts of their modules, because we’d be forcing PrivateData to be a Hashtable, and to contain keys that they don’t need in the module.

Some existing modules use an array in PrivateData, or even a simple string, rather than a Hashtable. However, it’s not a huge difference, and might be the cleanest method: it wouldn’t require you to manage a second file of data, and the additional data will be easily available to users and scripts via the standard Get-Module output.

Add a “doc comment” system for Module manifest files.

The upside of this is that PoshCode wants to create module-level documentation anyway. If we use documentation comments like those used on functions we would be able to just create our own standard for them, and add any extra fields we need. It would be guaranteed not to conflict with anything you’re already doing, and in addition to missing metadata, you could have some module-level documentation beyond just the Description field of the metadata.

The problem with this is that there’s no built-in way to parse that, and doing so isn’t trivial, so you would need to just read it on our website, or read the source of the file, or have our PoshCode cmdlets in order to make any sense of it once you had a module on your system. It doesn’t integrate with PowerShell in any meaningful way.

Embed the extra data right in the manifest hashtable, using a special comment to hide it from Get-Module

@{
author=“Joel Bennett”
description=“My latest crazy module”
<#!PoshCode
License=“Ms-PL”
Category=“WPF”,“GUI”,“Toolkit” #>
CompanyName=“Huddled Masses”
...
}


I like this because it’s fairly trivial for us to strip out the comment and just turn that into a plain-old DATA section. It also lends itself to reminding the PowerShell team that these fields are missing, and maintains the existing simple syntax of the manifest.

The problem here is, again, that the data doesn’t appear using any of the standard PowerShell tools — but getting it out is significantly easier than getting out document comments…

Require a separate “ReadMe.psd1” (or “PoshCode.pds1” or “Metadata.psd1”) metadata file

You could start with a copy of your module manifest, and then add the extra stuff that PoshCode needs. This would be nice because we would be able to add any extra fields we wanted as mandatory members, and we could include the “documentation” stuff I mentioned earlier…

But the downside is that it would be a third file (second manifest) that authors would have to maintain and keep current.

Any thoughts? Suggestions?

I’ve put some further thoughts about CPAN and the data problem on the wiki.