Corporate Powershell Module Repository – Part 2 – Developer Guide
August 12, 2010
Posted by on
This article continues the last one about architecting a corporate module repository.
I put a formal submission process in place to ensure that all modules meet certain standards. Developers are given a complete set of documentation that outlines best practices that are enforced via a review process. When a developer submits a module for distribution in the repository their module is checked to ensure that it meets the following guidelines:
- All in-house modules must “make sense” and must have the company-specific prefix. Let’s say that prefix is Toe. Something like ToeISE or ToeClipboard would be ok.
- When a namespace already exists that is suitable for a developer’s module they should first try and contact the creator of the namespace to ensure there are no duplicate efforts. Collaboration on modules is encouraged.
- The noun of a cmdlet must use the modulename as a prefix or the noun can be the prefix itself, i.e., if the module is named ToeISE a proper cmdlet name might be Open-ToeISE, or if the module is called ToeHTML a proper cmdlet name could be ConvertTo-ToeHTMLTable
- Cmdlets must use a valid verb returned from Get-Verb, and that verb should follow suit with what Microsoft currently uses the verb for. For example, Out-ToeExcel would be more appropriate than Write-ToeExcel because the intention of “Write” is to write information to the user through the console.
- When using add-type in your module you should ensure that the -namespace parameter uses your module name. A great example of this is a module that wraps pinvoke code. The following might be a part of a module called ToeClipboard:
$sig = @"
public static extern IntPtr GetClipboardData(uint uFormat);
public static extern uint EnumClipboardFormats(uint format);
public static extern bool OpenClipboard(IntPtr hWndNewOwner);
public static extern bool CloseClipboard();
public static extern bool EmptyClipboard();
Add-Type -MemberDefinition $sig -Namespace ToeClipboard -Name User32
- Developers should create modules using .psm1 files where possible
- Strict guidelines are given around .psd1 files. There must be a .psd1 file with every distribution. I have provided our developers with a company-specific script that runs New-ModuleManifest to ensure that fields are filled out appropriately.
- Parameters must be defined with param(), and they must contain the appropriate Parameter attributes outlined in Get-Help about_Functions_Advanced_Parameters
- All cmdlets must include inline help. The following template was supplied to developers:
One line blurb that discusses cmdlet
Multi-line description of cmdlet
Description of ParameterName1
Description of ParameterName2
Information about the types of input objects accepted
Information about the objects returned as output from the cmdlet
Detailed example. Ideally there should be an example for each set of Parameters and a pipeline example.
Related cmdlets or relevant URL
- Aliases for cmdlets/functions should not be exported. This is required to ensure that there is no contention and clobbering of aliases. Aliases may be suggested in your notes, but they must not be forced.
- Aliases for parameters are OK because they are contained within the cmdlet. They may also be necessary to ensure that pipeline input by name is accepted from multiple sources.
Are you surprised that I would end this article calling for a Powershell module repository on the Internet? While the infrastructure and design of the in-house module repository I put together for my company will not work on the Internet, I think the standards I outlined for the developer’s guide is something that is enforceable for the module repository we will build on the Internet. In order to be successful we will need a governing body that ensures namespaces and standards are met with new code. I feel that this is the easy part. Just look at all of the Judges for the 2010 Scripting Games; Reading 100 scripts a day that are all nearly identical is hardly anyone’s idea of fun yet there were plenty of community leaders who were happy to take up the task when asked. I think the hard part is the design and maintenance of the infrastructure on the Internet. So get to work people – I guarantee you we can assemble the board to oversee it justly, fairly, and with proper standards in place.
Part three of this series will include my techniques for migrating snapins to modules for both in-house and 3rd party snapins.