Share via


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

Example 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 @moduleSettings

This 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 @moduleSettings

For 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

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.