New-ModuleManifest
Creates a new module manifest.
Syntax
New-ModuleManifest
[-Path] <string>
[-NestedModules <Object[]>]
[-Guid <guid>]
[-Author <string>]
[-CompanyName <string>]
[-Copyright <string>]
[-RootModule <string>]
[-ModuleVersion <version>]
[-Description <string>]
[-ProcessorArchitecture <ProcessorArchitecture>]
[-PowerShellVersion <version>]
[-ClrVersion <version>]
[-DotNetFrameworkVersion <version>]
[-PowerShellHostName <string>]
[-PowerShellHostVersion <version>]
[-RequiredModules <Object[]>]
[-TypesToProcess <string[]>]
[-FormatsToProcess <string[]>]
[-ScriptsToProcess <string[]>]
[-RequiredAssemblies <string[]>]
[-FileList <string[]>]
[-ModuleList <Object[]>]
[-FunctionsToExport <string[]>]
[-AliasesToExport <string[]>]
[-VariablesToExport <string[]>]
[-CmdletsToExport <string[]>]
[-PrivateData <Object>]
[-HelpInfoUri <string>]
[-PassThru]
[-DefaultCommandPrefix <string>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Description
The New-ModuleManifest cmdlet creates a new module manifest (.psd1) file, populates its values,
and saves the manifest file in the specified path.
Module authors can use this cmdlet to create a manifest for their module. 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, and determine how the components are
processed. Manifests aren't required for a module.
New-ModuleManifest creates a manifest that includes all the commonly used manifest keys, so you
can use the default output as a manifest template. To add or change values, or to add module keys
that this cmdlet doesn't add, open the resulting file in a text editor.
Each parameter, except for Path and PassThru, creates a module manifest key and its value.
In a module manifest, only the ModuleVersion key is required. Unless specified in the parameter
description, if you omit a parameter from the command, New-ModuleManifest creates a comment string
for the associated value that has no effect.
In PowerShell 2.0, New-ModuleManifest prompts you for the values of commonly used parameters that
aren't specified in the command, in addition to required parameter values. Beginning in PowerShell
3.0, New-ModuleManifest prompts only when required parameter values aren't specified.
Examples
Example 1 - Create a new module manifest
This example creates a new module manifest in the file that is specified by the Path parameter. The PassThru parameter sends the output to the pipeline and to the file.
The output shows the default values of all keys in the manifest.
New-ModuleManifest -Path C:\ps-test\Test-Module\Test-Module.psd1 -PassThru
#
# Module manifest for module 'Test-Module'
#
# Generated by: ContosoAdmin
#
# Generated on: 1/22/2019
#
@{
# Script module or binary module file associated with this manifest.
# RootModule = ''
# Version number of this module.
ModuleVersion = '1.0'
# ID used to uniquely identify this module
GUID = '47179120-0bcb-4f14-8d80-f4560107f85c'
# Author of this module
Author = 'ContosoAdmin'
# Company or vendor of this module
CompanyName = 'Unknown'
# Copyright statement for this module
Copyright = '(c) 2019 ContosoAdmin. All rights reserved.'
# Description of the functionality provided by this module
# Description = ''
# Minimum version of the Windows PowerShell engine required by this module
# PowerShellVersion = ''
# Name of the Windows PowerShell host required by this module
# PowerShellHostName = ''
# Minimum version of the Windows PowerShell host required by this module
# PowerShellHostVersion = ''
# Minimum version of the .NET Framework required by this module
# DotNetFrameworkVersion = ''
# Minimum version of the common language runtime (CLR) required by this module
# CLRVersion = ''
# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''
# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()
# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()
# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()
# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()
# Functions to export from this module
FunctionsToExport = '*'
# Cmdlets to export from this module
CmdletsToExport = '*'
# Variables to export from this module
VariablesToExport = '*'
# Aliases to export from this module
AliasesToExport = '*'
# List of all modules packaged with this module.
# ModuleList = @()
# List of all files packaged with this module
# FileList = @()
# Private data to pass to the module specified in RootModule/ModuleToProcess
# PrivateData = ''
# HelpInfo URI of this module
# HelpInfoURI = ''
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''
}Example 2 - Create a new manifest with some prepopulated settings
This example creates a new module manifest. It uses the PowerShellVersion and AliasesToExport parameters to add values to the corresponding manifest keys.
New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC -Path C:\ps-test\ManifestTest.psd1Example 3 - Create a manifest that requires other modules
This example uses a string format to specify the name of the BitsTransfer module and the hash table format to specify the name, a GUID, and a version of the PSScheduledJob module.
$moduleSettings = @{
RequiredModules = ("BitsTransfer", @{
ModuleName="PSScheduledJob"
ModuleVersion="1.0.0.0";
GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"
})
Path = 'C:\ps-test\ManifestTest.psd1'
}
New-ModuleManifest @moduleSettingsThis example shows how to use the string and hash table formats of the ModuleList, RequiredModules, and NestedModules parameter. You can combine strings and hash tables in the same parameter value.
Example 4 - Create a manifest that supports updateable help
This example uses the HelpInfoUri parameter to create a HelpInfoUri key in the module manifest. The value of the parameter and the key must begin with http or https. This value tells the Updatable Help system where to find the HelpInfo XML updatable help information file for the module.
$moduleSettings = @{
HelpInfoUri = 'https://go.microsoft.com/fwlink/?LinkID=603'
Path = 'C:\ps-test\ManifestTest.psd1'
}
New-ModuleManifest @moduleSettingsFor information about Updatable Help, see about_Updatable_Help. For information about the HelpInfo XML file, see Supporting Updatable Help.
Example 5 - Getting module information
This example shows how to get the configuration values of a module. The values in the module manifest are reflected in the values of properties of the module object.
The Get-Module cmdlet is used to get the Microsoft.PowerShell.Diagnostics module using the
List parameter. The command sends the module to the Format-List cmdlet to display all
properties and values of the module object.
Get-Module Microsoft.PowerShell.Diagnostics -List | Format-List -Property *
LogPipelineExecutionDetails : False
Name : Microsoft.PowerShell.Diagnostics
Path : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Microsoft.PowerShell.Diagnostics\Micro
soft.PowerShell.Diagnostics.psd1
Definition :
Description :
Guid : ca046f10-ca64-4740-8ff9-2565dba61a4f
HelpInfoUri : https://go.microsoft.com/fwlink/?LinkID=210596
ModuleBase : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Microsoft.PowerShell.Diagnostics
PrivateData :
Version : 3.0.0.0
ModuleType : Manifest
Author : Microsoft Corporation
AccessMode : ReadWrite
ClrVersion : 4.0
CompanyName : Microsoft Corporation
Copyright : Microsoft Corporation. All rights reserved.
DotNetFrameworkVersion :
ExportedFunctions : {}
ExportedCmdlets : {[Get-WinEvent, Get-WinEvent], [Get-Counter, Get-Counter], [Import-Counter,
Import-Counter], [Export-Counter, Export-Counter]...}
ExportedCommands : {[Get-WinEvent, Get-WinEvent], [Get-Counter, Get-Counter], [Import-Counter,
Import-Counter], [Export-Counter, Export-Counter]...}
FileList : {}
ModuleList : {}
NestedModules : {}
PowerShellHostName :
PowerShellHostVersion :
PowerShellVersion : 3.0
ProcessorArchitecture : None
Scripts : {}
RequiredAssemblies : {}
RequiredModules : {}
RootModule :
ExportedVariables : {}
ExportedAliases : {}
ExportedWorkflows : {}
SessionState :
OnRemove :
ExportedFormatFiles : {C:\Windows\system32\WindowsPowerShell\v1.0\Event.format.ps1xml,
C:\Windows\system32\WindowsPowerShell\v1.0\Diagnostics.format.ps1xml}
ExportedTypeFiles : {C:\Windows\system32\WindowsPowerShell\v1.0\GetEvent.types.ps1xml}Parameters
-AliasesToExport
Specifies the aliases that the module exports. Wildcards are permitted.
You can use this parameter to restrict the aliases that are exported by the module. It can remove aliases from the list of exported aliases, but it can't add aliases to the list.
If you omit this parameter, New-ModuleManifest creates an AliasesToExport key with a value of
* (all), meaning that all aliases defined in the module are exported by the manifest.
| Type: | String[] |
| Position: | Named |
| Default value: | * (all) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-Author
Specifies the module author.
If you omit this parameter, New-ModuleManifest creates an Author key with the name of the
current user.
| Type: | String |
| Position: | Named |
| Default value: | Name of the current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ClrVersion
Specifies the minimum version of the Common Language Runtime (CLR) of the Microsoft .NET Framework that the module requires.
| Type: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CmdletsToExport
Specifies the cmdlets that the module exports. Wildcards are permitted.
You can use this parameter to restrict the cmdlets that are exported by the module. It can remove cmdlets from the list of exported cmdlets, but it can't add cmdlets to the list.
If you omit this parameter, New-ModuleManifest creates a CmdletsToExport key with a value of
* (all), meaning that all cmdlets defined in the module are exported by the manifest.
| Type: | String[] |
| Position: | Named |
| Default value: | * (all) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-CompanyName
Identifies the company or vendor who created the module.
If you omit this parameter, New-ModuleManifest creates a CompanyName key with a value of
"Unknown".
| Type: | String |
| Position: | Named |
| Default value: | "Unknown" |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Copyright
Specifies a copyright statement for the module.
If you omit this parameter, New-ModuleManifest creates a Copyright key with a value of
(c) <year> <username>. All rights reserved. where <year> is the current year and <username> is
the value of the Author key.
| Type: | String |
| Position: | Named |
| Default value: | (c) <year> <username>. All rights reserved. |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DefaultCommandPrefix
Specifies a prefix that is prepended to the nouns of all commands in the module when they're imported into a session. Enter a prefix string. Prefixes prevent command name conflicts in a user's session.
Module users can override this prefix by specifying the Prefix parameter of the Import-Module
cmdlet.
This parameter was introduced in PowerShell 3.0.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
Describes the contents of the module.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DotNetFrameworkVersion
Specifies the minimum version of the Microsoft .NET Framework that the module requires.
| Type: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FileList
Specifies all items that are included in the module.
This key is designed to act as a module inventory. The files listed in the key are included when the module is published, but any functions aren't automatically exported.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FormatsToProcess
Specifies the formatting files (.ps1xml) that run when the module is imported.
When you import a module, PowerShell runs the Update-FormatData cmdlet with the specified files.
Because formatting files aren't scoped, they affect all session states in the session.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FunctionsToExport
Specifies the functions that the module exports. Wildcards are permitted.
You can use this parameter to restrict the functions that are exported by the module. It can remove functions from the list of exported aliases, but it can't add functions to the list.
If you omit this parameter, New-ModuleManifest creates an FunctionsToExport key with a value
of * (all), meaning that all functions defined in the module are exported by the manifest.
| Type: | String[] |
| Position: | Named |
| Default value: | * (all) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-Guid
Specifies a unique identifier for the module. The GUID can be used to distinguish among modules with the same name.
If you omit this parameter, New-ModuleManifest creates a GUID key in the manifest and
generates a GUID for the value.
To create a new GUID in PowerShell, type [guid]::NewGuid().
| Type: | Guid |
| Position: | Named |
| Default value: | A GUID generated for the module |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-HelpInfoUri
Specifies the internet address of the HelpInfo XML file for the module. Enter a Uniform Resource Identifier (URI) that begins with http or https.
The HelpInfo XML file supports the Updatable Help feature that was introduced in PowerShell 3.0. It contains information about the location of downloadable help files for the module and the version numbers of the newest help files for each supported locale.
For information about Updatable Help, see about_Updatable_Help. For information about the HelpInfo XML file, see Supporting Updatable Help.
This parameter was introduced in PowerShell 3.0.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ModuleList
Lists all modules that are included in this module.
Enter each module name as a string or as a hash table with ModuleName and ModuleVersion keys. The hash table can also have an optional GUID key. You can combine strings and hash tables in the parameter value.
This key is designed to act as a module inventory. The modules that are listed in the value of this key aren't automatically processed.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ModuleVersion
Specifies the module's version.
This parameter isn't required, but a ModuleVersion key is required in the manifest. If you omit
this parameter, New-ModuleManifest creates a ModuleVersion key with a value of 1.0.
| Type: | Version |
| Position: | Named |
| Default value: | 1.0 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NestedModules
Specifies script modules (.psm1) and binary modules (.dll) that are imported into the module's
session state. The files in the NestedModules key run in the order in which they're listed in
the value.
Enter each module name as a string or as a hash table with ModuleName and ModuleVersion keys. The hash table can also have an optional GUID key. You can combine strings and hash tables in the parameter value.
Typically, nested modules contain commands that the root module needs for its internal processing.
By default, the commands in nested modules are exported from the module's session state into the
caller's session state, but the root module can restrict the commands that it exports. For example,
by using an Export-ModuleMember command.
Nested modules in the module session state are available to the root module, but they aren't
returned by a Get-Module command in the caller's session state.
Scripts (.ps1) that are listed in the NestedModules key are run in the module's session state,
not in the caller's session state. To run a script in the caller's session state, list the script
file name in the value of the ScriptsToProcess key in the manifest.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PassThru
Writes the resulting module manifest to the console and creates a .psd1 file. By default, this
cmdlet doesn't generate any output.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Path
Specifies the path and file name of the new module manifest. Enter a path and file name with a
.psd1 file name extension, such as $pshome\Modules\MyModule\MyModule.psd1. The Path
parameter is required.
If you specify the path to an existing file, New-ModuleManifest replaces the file without warning
unless the file has the read-only attribute.
The manifest should be located in the module's directory, and the manifest file name should be the
same as the module directory name, but with a .psd1 file name extension.
Note
You cannot use variables, such as $PSHOME or $HOME, in response to a prompt for a Path
parameter value. To use a variable, include the Path parameter in the command.
| Type: | String |
| Position: | 1 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PowerShellHostName
Specifies the name of the PowerShell host program that the module requires. Enter the name of the host program, such as Windows PowerShell ISE Host or ConsoleHost. Wildcards aren't permitted.
To find the name of a host program, in the program, type $Host.Name.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PowerShellHostVersion
Specifies the minimum version of the PowerShell host program that works with the module. Enter a version number, such as 1.1.
| Type: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PowerShellVersion
Specifies the minimum version of PowerShell that works with this module. For example, you can enter 1.0, 2.0, or 3.0 as the parameter's value.
| Type: | Version |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PrivateData
Specifies data that is passed to the module when it's imported.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProcessorArchitecture
Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, MSIL, and None (unknown or unspecified).
| Type: | ProcessorArchitecture |
| Accepted values: | None, MSIL, X86, IA64, Amd64, Arm |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RequiredAssemblies
Specifies the assembly (.dll) files that the module requires. Enter the assembly file names.
PowerShell loads the specified assemblies before updating types or formats, importing nested
modules, or importing the module file that is specified in the value of the RootModule key.
Use this parameter to list all the assemblies that the module requires, including assemblies that must be loaded to update any formatting or type files that are listed in the FormatsToProcess or TypesToProcess keys, even if those assemblies are also listed as binary modules in the NestedModules key.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RequiredModules
Specifies modules that must be in the global session state. If the required modules aren't in the
global session state, PowerShell imports them. If the required modules aren't available, the
Import-Module command fails.
Enter each module name as a string or as a hash table with ModuleName and ModuleVersion keys. The hash table can also have an optional GUID key. You can combine strings and hash tables in the parameter value.
In PowerShell 2.0, Import-Module doesn't import required modules automatically. It just verifies
that the required modules are in the global session state.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RootModule
Specifies the primary or root file of the module. Enter the file name of a script (.ps1), a script
module (.psm1), a module manifest(.psd1), an assembly (.dll), a cmdlet definition XML file
(.cdxml), or a workflow (.xaml). When the module is imported, the members that are exported from
the root module file are imported into the caller's session state.
If a module has a manifest file and no root file was designated in the RootModule key, the manifest becomes the primary file for the module, and the module becomes a manifest module (ModuleType = Manifest).
To export members from .psm1 or .dll files in a module that has a manifest, the names of those
files must be specified in the values of the RootModule or NestedModules keys in the
manifest. Otherwise, their members aren't exported.
Note
In PowerShell 2.0, this key was called ModuleToProcess. You can use the RootModule parameter name or its ModuleToProcess alias.
| Type: | String |
| Aliases: | ModuleToProcess |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ScriptsToProcess
Specifies script (.ps1) files that run in the caller's session state when the module is imported.
You can use these scripts to prepare an environment, just as you might use a login script.
To specify scripts that run in the module's session state, use the NestedModules key.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TypesToProcess
Specifies the type files (.ps1xml) that run when the module is imported.
When you import the module, PowerShell runs the Update-TypeData cmdlet with the specified files.
Because type files aren't scoped, they affect all session states in the session.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VariablesToExport
Specifies the variables that the module exports. Wildcards are permitted.
You can use this parameter to restrict the variables that are exported by the module. It can remove variables from the list of exported variables, but it can't add variables to the list.
If you omit this parameter, New-ModuleManifest creates a VariablesToExport key with a value of
* (all), meaning that all variables defined in the module are exported by the manifest.
| Type: | String[] |
| Position: | Named |
| Default value: | * (all) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-WhatIf
Shows what would happen if New-ModuleManifest runs. The cmdlet isn't run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
None
You can't pipe input to this cmdlet.
Outputs
None or System.String
By default, New-ModuleManifest doesn't generate any output. However, if you use the PassThru
parameter, it generates a System.String object representing the module manifest.
Notes
New-ModuleManifest creates module manifest (.psd1) files encoded as UTF16.
Module manifests are usually optional. However, a module manifest is required to export an assembly that is installed in the global assembly cache.
To add or change files in the $pshome\Modules directory, start PowerShell with the Run as
administrator option.
In PowerShell 2.0, many parameters of New-ModuleManifest were mandatory, even though they weren't
required in a module manifest. Beginning in PowerShell 3.0, only the Path parameter is
mandatory.
A session is an instance of the PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the global session state.
The caller's session state is the session state into which a module is imported. Typically, it refers to the global session state, but when a module imports nested modules, the caller is the module and the caller's session state is the module's session state.