How to Create PowerShell Script Modules and Module Manifests

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

creating-modules1

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

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

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

View the output of Get-Verb to see a list of common verbs. There is also an “Approved Verbs for Windows PowerShell Commands” article on MSDN.

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 on page 315 of Lee Holmes’s new PowerShell Cookbook, 3rd Edition book: “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

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

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

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

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, read the help topic on TechNet for Export-ModuleMember.

For more information about modules run “help about_Modules from within PowerShell or read the help topic on TechNet.

µ

1 Comment

  1. dallyhorton

    Thanks Mike! Not including RootModule just caused me hours of grief. As you said, without this none of the commands are exported. The training course I just finished through Pluralsight made no mention of requiring this parameter either. He was certainly seeing the commands when viewing Get-Module -ListAvailable.

    Reply

Leave a Reply

%d bloggers like this: