Summary: Ed Wilson, Microsoft Scripting Guy, talks about Windows PowerShell modules.
Hey, Scripting Guy! I keep hearing about Windows PowerShell modules, but I do not know what they really mean. Is it something that comes with Windows PowerShell, or is it something I have to buy or download? I don’t get it. Can you shed some light?
—ST
Hello ST,
Microsoft Scripting Guy, Ed Wilson, is here. Things are really exciting around the Scripting Household. I have been talking to Microsoft evangelist ,Blain Barton, about doing a PowerShell Saturday in Florida. Without giving any details away, it is something we are exploring. It will be way cool!
Windows PowerShell modules are a great way to share functions, and to be able to bring a group of functions into a script, or to a Windows PowerShell session, or even from computer to computer. The functions do not need to be advanced functions, but it sort of makes sense. I mean, if I am going to be writing something that I want to reuse, something I want to share from machine to machine, or something I want to with other users, it makes sense to use all of the Windows PowerShell technology that is available, including:
- Comment-based Help
- Parameter constraints
- Error handling
- Output streams (error, warning, and verbose)
- WhatIf (if the function will change system state)
- Confirm (if you want to ensure the user is aware of the potential action to take place, such as deleting a bunch of users)
All of these are features that can easily be implemented in advanced functions. Modules simply provide an easy way to ship related functions. Modules can include the following:
- Functions
- Variables
- Aliases
The cool thing is that when I import a module, I can select if I want to import one or more functions, or one or more variables or alias. This provides a lot of flexibility. In addition, I can add versions to my module, so I can specify if I want to import a specific version of the module.
A module is simply a Windows PowerShell file with a .psm1 file extension. I can create it in the Windows PowerShell ISE, and when I save it, I specify that I want to save the .psm1 extension. After I have my module, I should create a module manifest for it.
A module manifest is a simple text file with a .psd1 file extension. I can create it manually, but the best way to create it is by using the New-ModuleManifest cmdlet. I must specify the path to the module, but there are also lots of other parameters that I can specify. Here is the syntax for New-ModuleManifest:
New-ModuleManifest [-Path] <String> [-AliasesToExport <String[]>] [-Author
<String>] [-ClrVersion <Version>] [-CmdletsToExport <String[]>]
[-CompanyName <String>] [-Copyright <String>] [-DefaultCommandPrefix
<String>] [-Description <String>] [-DotNetFrameworkVersion <Version>]
[-FileList <String[]>] [-FormatsToProcess <String[]>] [-FunctionsToExport
<String[]>] [-Guid <Guid>] [-HelpInfoUri <String>] [-ModuleList
<Object[]>] [-ModuleVersion <Version>] [-NestedModules <Object[]>]
[-PassThru] [-PowerShellHostName <String>] [-PowerShellHostVersion
<Version>] [-PowerShellVersion <Version>] [-PrivateData <Object>]
[-ProcessorArchitecture <ProcessorArchitecture>] [-RequiredAssemblies
<String[]>] [-RequiredModules <Object[]>] [-RootModule <String>]
[-ScriptsToProcess <String[]>] [-TypesToProcess <String[]>]
[-VariablesToExport <String[]>] [-Confirm] [-WhatIf] [<CommonParameters>]
When I am creating a module manifest for a new module, I can specify the aliases I want the module to export, the functions to export, and even the variables I want it to export. I can use the asterisk wildcard character ( * ), or I can enumerate exactly which items I want the module to export.
This is useful when a module may contain what I call "helper functions" that are used only by other functions within my module. If a function does not make sense to export, I can effectively hide it via my manifest.
When I use the Get-Module cmdlet, it returns information from the module manifest (which resides in the same folder as the module itself). This is shown here:
PS C:\> Get-Module ConversionModule
ModuleType Version Name ExportedCommands
---------- ------- ---- ----------------
Script 6.0 ConversionModule {ConvertTo-celsius, ConvertT...
As shown here, I can pipe the output of the command to the Format-List cmdlet and see more information:
PS C:\> Get-Module ConversionModule | fl
Name : ConversionModule
Path : C:\Users\ed\Documents\WindowsPowerShell\Modules\ConversionModule\ConversionModule.psm1
Description : a module that performs various unit conversions
ModuleType : Script
Version : 6.0
NestedModules : {}
ExportedFunctions : {ConvertTo-celsius, ConvertTo-Fahrenheit, ConvertTo-Feet, ConvertTo-Kilometers...}
ExportedCmdlets :
ExportedVariables :
ExportedAliases : {CTCS, CTFH, CTFT, CTKM...}
ST, that is all there is to using Windows PowerShell modules. To Script or Not to Script Week will continue tomorrow when I will talk about more cool stuff.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy