Windows PowerShell Modules

A module is a set of related Windows PowerShell functionalities that can be dynamic or 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.

Module Types

The following types of modules can be used to package and deploy Windows PowerShell functionalities.

Script Modules

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.

Binary Modules

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.)

Manifest Modules

A manifest module is a module that includes a manifest (described later in this section) to describe its components, but that 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.

Dynamic Modules

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 cannot be accessed by the Get-Module cmdlet.

Module Manifests

A module manifest is a .psd1 file that contains a hash table. The keys and values in the hash table do the following things:

  • 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. If you add a manifest file to the module folder, you can reference the multiple files 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 in a user folder. In either case, the path of 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 by the New-Module cmdlet can be named using the Name parameter of the cmdlet.

  • Modules imported from assembly objects by the Import-Module -Assembly command are named according to the following syntax: "dynamic_code_module_" + assembly.GetName().

When you store files in 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 is a root module that has the same name as the module folder.)

user\documents\windowspowershell\modules\mymodule

When you store files in the system folder, you have to create the following path. 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.

windows\system32\windowspowershell\V1.0\modules\mymodule

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 to 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.

$PSScriptRoot
This variable contains the directory from which the script module is being executed. It enables scripts to use the module path to access other resources.

$env:PSModulePath
This environment variable contains a list of the directories in which Windows PowerShell modules are stored. Windows PowerShell uses the value of this variable when importing modules automatically and updating Help topics for modules.

See Also



Show:
© 2014 Microsoft