How to Create PowerShell Script Modules and Module Manifests

My entry for the Scripting Games advanced event 4 contained four separate functions:

creating-modules1.png

I want to create a module that contains these functions. There are several different types of modules, but what I'll be creating is a "Script Module". Modules sound like something really complicated, but script modules are actually simple.

Currently, I have the functions saved as a ps1 file which I dot-source to load the functions into memory, but I want to share this tool with others so it makes more sense to create a module out of it.

I'm simply going to save the existing ps1 file as a psm1 file in a folder with the same name in my modules folder as shown in the following image:

creating-modules2d.png

It's very important to have the folder and base name for the file the same. I've given it a generic name because I may want to add more functions to a new version of this same module in the future. I called it MrAuditTool (Mr for Mike Robbins and then Audit Tool).

At this point, it's a script module. We can see what commands it contains:

creating-modules3a.png

The following image contains two important things to be aware of, first shown with the purple rectangle around it, if you've imported the module you're working with or it's been imported automatically in PowerShell version 3 and changes are made to it, you'll either have to remove and re-import it or you can simply add the Force parameter to the Import-Module command.

The second item I want you to be aware of is if you don't use standard verbs for your function names, you'll receive the warning message shown in the following image. I've placed a red rectangle around the warning and the function that doesn't use a standard verb (click on the image for a larger version which is easier to read):

creating-modules8.png

View the output of Get-Verb to see a list of approved verbs.

Based on one of the Scripting Guy, Ed Wilson's sessions that I sat through at the PowerShell Summit a few months ago, it's best practice to create a module manifest file. I also read the following in Lee Holmes's PowerShell Cookbook: "In addition to creating the .psm1 file that contains your module's commands, you should also create a module manifest to describe its contents and system requirements".

The New-ModuleManifest cmdlet is used to create a module manifest. As shown below, in PowerShell version 3, the only field that you're required to provide a value for is the path:

creating-modules4a.png

Although, if the RootModule is not set in the Module Manifest file, it won't work and no commands at all will be exported. If you run into this problem, make sure this option is set in the psd1 module manifest file:

creating-modules7.png

You could open the file with the ISE at this point and edit it manually, but I'm going to delete this manifest file and create a new one with the options I want instead:

creating-modules5a.png

What's really cool about the manifest file I just created is now it only exports the one New-UserAuditReport function since all of the others are helper functions:

creating-modules6.png

There are other ways to export only specific commands in the psm1 module file instead of using this method in the psd1 module manifest file. If you're interested, research the Export-ModuleMember cmdlet.

For more information about modules run help about_Modules from PowerShell.

µ