Windows PowerShell Modules
A module is a set of related Windows PowerShell functionalities that can be dynamic or that can persist on disk. Modules that persist on disk are referenced, loaded, and persisted as script modules, binary modules, or manifest modules. Unlike snap-ins, the members of these modules can include cmdlets, providers, functions, variables, aliases, and much more.
The following types of modules can be used to package and deploy Windows PowerShell functionalities.
A script module is a file (.psm1) that contains any valid Windows PowerShell code. Script developers and administrators can use this type of module to create modules whose members include functions, variables, and more.
A binary module is a .NET Framework assembly (.dll) that contains compiled code. Cmdlet developers can use this type of module to create modules that contain cmdlets, providers, and more. (Existing snap-ins can also be used as binary modules.)
A manifest module is a module that includes a manifest (described later in this section) to describe its components, but it does not specify a root module in the manifest. A module manifest does not specify a root module when the
ModuleToProcess key of the manifest is blank. In most cases, a manifest module also includes one or more nested modules using script modules or binary modules. A manifest module that does not include any nested modules can be used when you want a convenient way to load assemblies, types, or formats.
A dynamic module is a module that does not persist to disk. This type of module enables a script to create a module on demand that does not need to be loaded or saved to persistent storage. By default, dynamic modules created with the New-Module cmdlet (described in the following sections) are intended to be short-lived and therefore are not visible using the Get-Module cmdlet.
A module manifest is a .psd1 file that contains a hash table. The keys and values in the hash table:
Describe the contents and attributes of the module.
Define the prerequisites.
Determine how the components are processed.
Manifests are not required for a module. Modules can reference script files (.ps1), script module files (.psm1), manifest files (.psd1), formatting and type files (.ps1xml), cmdlet and provider assemblies (.dll), resource files, Help files, localization files, or any other type of file or resource that is bundled as part of the module. For an internationalized script, the module folder also contains a set of message catalog files. By adding a manifest file to the module folder, the multiple files can still be referenced as a single unit by referencing the manifest.
The manifest itself describes the following categories of information:
Metadata about the module, such as the module version number, the author, and the description.
Prerequisites needed to import the module, such as the Windows PowerShell version, the common language runtime (CLR) version, and the required modules.
Processing directives such as the scripts, formats, and types to process.
Restrictions on the members of the module to export, such as the aliases, functions, variables, and cmdlets to export.
For more information about manifests, see Module Manifests.
Storing Modules on Disk
When writing script, binary, and manifest modules, there are several places that the module files can be stored. For example, they can be stored in the system folder where Windows PowerShell is installed, or they can be stored under a user folder. In either case, the path to the folder is referred to as the base of the module (ModuleBase), and the name of the script, binary, or manifest module file should be the same as the module folder name, with the following exceptions:
Dynamic modules that are created using the New-Module cmdlet can be named using the Name parameter of the cmdlet.
Modules imported from assembly objects using the Import-Module -Assembly command are named using the following syntax:
"dynamic_code_module_" + assembly.GetName().
When storing files under a user folder, you have to create the following path. Notice that each module is in its own folder. (It is possible to nest modules, but for the most part there will be a root module that has the same name as the module folder.)
When storing files under the system folder, you have to create the following path. Notice that when you work within the system folder, Windows prompts you each time that you create, copy over, or remove a file. Also, when you run cmdlets that access these locations, the Windows PowerShell session that you use to run these commands needs to be opened with administrator privileges.
Module Cmdlets and Variables
The following cmdlets and variables are provided by Windows PowerShell for the creation and management of modules.
- New-Module cmdlet
- This cmdlet creates a new dynamic module that exists only in memory. The module is created from a script block, and its exported members, such as its functions and variables, are immediately available in the session and remain available until the session is closed.
- New-ModuleManifest cmdlet
- This cmdlet creates a new module manifest (.psd1) file, populates its values, and saves the manifest file in the specified path. This cmdlet can also be used to create a module manifest template that can be filled in manually.
- Import-Module cmdlet
- This cmdlet adds one or more modules to the current session.
- Get-Module cmdlet
- This cmdlet retrieves information about the modules that have been or that can be imported into the current session.
- Export-ModuleMember cmdlet
- This cmdlet specifies the module members (such as cmdlets, functions, variables, and aliases) that are exported from a script module (.psm1) file or from a dynamic module created by using the New-Module cmdlet.
- Remove-Module cmdlet
- This cmdlet removes modules from the current session.
- Test-ModuleManifest cmdlet
- This cmdlet verifies that a module manifest accurately describes the components of a module by verifying that the files that are listed in the module manifest file (.psd1) actually exist in the specified paths.
- This variable contains the directory from which the script module is being executed. This variable allows scripts to use the module path to access other resources.
- This environment variable contains a list of the directories in which Windows PowerShell module are stored. Windows PowerShell uses the value of this variable when importing modules automatically and updating help topics for modules.
ConceptsWriting a Windows PowerShell Module