New-ModuleManifest

Creates a new module manifest.

Syntax

New-ModuleManifest [-Path] <string> -Author <string> -CompanyName <string> -Copyright <string> -Description <string> -FileList <string[]> -FormatsToProcess <string[]> -ModuleToProcess <string> -NestedModules <string[]> -RequiredAssemblies <string[]> -TypesToProcess <string[]> [-AliasesToExport <string[]>] [-ClrVersion <Version>] [-CmdletsToExport <string[]>] [-DotNetFrameworkVersion <Version>] [-FunctionsToExport <string[]>] [-Guid <Guid>] [-ModuleList <Object[]>] [-ModuleVersion <Version>] [-PassThru] [-PowerShellHostName <string>] [-PowerShellHostVersion <Version>] [-PowerShellVersion <Version>] [-PrivateData <Object>] [-ProcessorArchitecture {<None> | <MSIL> | <X86> | <IA64> | <Amd64>}] [-RequiredModules <Object[]>] [-ScriptsToProcess <string[]>] [-VariablesToExport <string[]>] [-Confirm] [-WhatIf] [<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 are not required for a module.

New-ModuleManifest creates a manifest that includes all of 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 does not add, open the resulting file in a text editor.

Each parameter of this cmdlet (except for Path and PassThru) creates a module manifest key and its value. In a module manifest, only the ModuleVersion key is required. However, several other parameters of this cmdlet are mandatory. As a result, you can type a "New-ModuleManifest" command without parameters and the cmdlet will prompt you for values for other commonly used keys. To leave the value empty, press ENTER.

For a complete description of the format, effects, and requirements of a module manifest, see "How to Write a Module Manifest" in the MSDN (Microsoft Developer Network) library at https://go.microsoft.com/fwlink/?LinkId=143613.

Parameters

-AliasesToExport <string[]>

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 cannot 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 that are exported by the module are exported by the manifest.

Required?	false
Position?	named
Default Value	* (all)
Accept Pipeline Input?	false
Accept Wildcard Characters?	true

-Author <string>

Specifies the module author.

This parameter is required by the cmdlet, but the Author key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates an Author key with the name of the current user.

Required?	true
Position?	named
Default Value	Name of the current user
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ClrVersion <Version>

Specifies the version of the Common Language Runtime (CLR) of the Microsoft .NET Framework that the module requires.

If you omit this parameter, New-ModuleManifest creates a CLRVersion key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-CmdletsToExport <string[]>

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 cannot 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 that are exported by the module are exported by the manifest.

Required?	false
Position?	named
Default Value	* (all)
Accept Pipeline Input?	false
Accept Wildcard Characters?	true

-CompanyName <string>

Identifies the company or vendor who created the module.

This parameter is required by the cmdlet, but the CompanyName key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a CompanyName key with a value of "Unknown".

Required?	true
Position?	named
Default Value	"Unknown"
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Copyright <string>

Specifies a copyright statement for the module.

This parameter is required by the cmdlet, but the Copyright key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, 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 (if one is specified) or the name of the current user.

Required?	true
Position?	named
Default Value	(c) <year> <username>. All rights reserved.
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Description <string>

Describes the contents of the module.

This parameter is required by the cmdlet, but the Description key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a Description key with an empty string value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-DotNetFrameworkVersion <Version>

Specifies the version of the Microsoft .NET Framework that the module requires.

If you omit this parameter, New-ModuleManifest creates a DotNetFrameWorkVersion key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-FileList <string[]>

Specifies all items that are included in the module.

This key is designed to act as a module inventory. These files are not automatically exported with the module.

This parameter is required by the cmdlet, but the FileList key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FileList key with an empty array value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-FormatsToProcess <string[]>

Specifies the formatting files (.ps1xml) that run when the module is imported.

When you import a module, Windows PowerShell runs the Update-FormatData cmdlet with the specified files. Because formatting files are not scoped, they affect all session states in the session.

This parameter is required by the cmdlet, but the FormatsToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FormatsToProcess key with an empty array value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-FunctionsToExport <string[]>

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 cannot 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 that are exported by the module are exported by the manifest.

Required?	false
Position?	named
Default Value	* (all)
Accept Pipeline Input?	false
Accept Wildcard Characters?	true

-Guid <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 Windows PowerShell, type "[guid]::NewGuid()".

Required?	false
Position?	named
Default Value	A GUID generated for the module
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ModuleList <Object[]>

Lists all modules that are packaged with this module.

Enter each module name as a string or enter a hash table with ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key.

This key is designed to act as a module inventory. These modules are not automatically processed.

If you omit this parameter, New-ModuleManifest creates a ModuleList key in the manifest with an empty array value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ModuleToProcess <string>

Specifies the primary or "root" file of the module. When the module is imported, the members that are exported from the root module file are imported into the caller's session state. Enter the file name of one script module (.psm1) or binary module (.dll).

If a module has a manifest file and no root file has been designated in the ModuleToProcess 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 ModuleToProcess or NestedModules keys in the manifest. Otherwise, their members are not exported.

This parameter is required by the cmdlet, but the ModuleToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a ModuleToProcess key with an empty string value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ModuleVersion <Version>

Specifies the version of the module.

This parameter is not required by the cmdlet, 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".

Required?	false
Position?	named
Default Value	1.0
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-NestedModules <string[]>

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 are listed in the 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-Module command).

Nested modules in the module session state are available to the root module, but they are not 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.

This parameter is required by the cmdlet, but the NestedModules key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a NestedModules key with an empty array value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PassThru

Writes the resulting module manifest to the console, in addition to creating a .psd1 file. By default, this cmdlet does not generate any output.

Required?	false
Position?	named
Default Value	False
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Path <string>

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". This 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.

Required?	true
Position?	1
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PowerShellHostName <string>

Specifies the name of the Windows PowerShell host program that the module requires. Enter the name of the host program, such as "Windows PowerShell ISE Host" or "ConsoleHost". Wildcards are not permitted.

To find the name of a host program, in the program, type "$host.name".

If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PowerShellHostVersion <Version>

Specifies the minimum version of the Windows PowerShell host program that works with the module. Enter a version number, such as 1.1.

If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PowerShellVersion <Version>

Specifies the minimum version of Windows PowerShell that will work with this module. Enter 1.0 or 2.0. Requirements for versions greater than 2.0 are not enforced.

If you omit this parameter, New-ModuleManifest creates a PowerShellVersion key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PrivateData <Object>

Specifies data that is passed to the module when it is imported.

If you omit this parameter, New-ModuleManifest creates a PrivateData key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ProcessorArchitecture <ProcessorArchitecture>

Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, and None (unknown or unspecified).

If you omit this parameter, New-ModuleManifest creates a ProcessorArchitecture key with an empty string value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RequiredAssemblies <string[]>

Specifies the assembly (.dll) files that the module requires. Windows 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 ModuleToProcess 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.

This parameter is required by the cmdlet, but the RequiredAssemblies key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a RequiredAssemblies key with an empty array value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RequiredModules <Object[]>

Specifies modules that must be in the global session state. If the required modules are not in the global session state, attempts to import this module will fail.

Enter each module name as a string or enter a hash table with the ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key. For more information, see the examples.

Windows PowerShell does not import required modules automatically. It verifies only that the required modules are present. However, modules can include scripts (.ps1) that import the required modules into the global session state.

If you omit this parameter, New-ModuleManifest creates a RequiredModules key with an empty array value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-ScriptsToProcess <string[]>

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.

If you omit this parameter, New-ModuleManifest creates a ScriptsToProcess key with an empty array value.

Required?	false
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-TypesToProcess <string[]>

Specifies the type files (.ps1xml) that run when the module is imported.

When you import the module, Windows PowerShell runs the Update-TypeData cmdlet with the specified files. Because type files are not scoped, they affect all session states in the session.

This parameter is required by the cmdlet, but the TypesToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a TypesToProcess key with an empty array value.

Required?	true
Position?	named
Default Value	None
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-VariablesToExport <string[]>

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 cannot 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 that are exported by the module are exported by the manifest.

Required?	false
Position?	named
Default Value	* (all)
Accept Pipeline Input?	false
Accept Wildcard Characters?	true

-Confirm

Prompts you for confirmation before executing the command.

Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-WhatIf

Describes what would happen if you executed the command without actually executing the command.

Required?	false
Position?	named
Default Value	none
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Inputs

None

You cannot pipe input to this cmdlet.

Outputs

None or System.String

By default, New-ModuleManifest does not generate any output. However, if you use the PassThru parameter, it generates a System.String object representing the module manifest..

Notes

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 (%Windir%\System32\WindowsPowerShell\v1.0\Modules), start Windows PowerShell with the "Run as administrator" option.

A "session" is an instance of the Windows PowerShell execution environment. A session can have one or more session state. 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.

Example 1

C:\PS>New-ModuleManifest

Path: C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1
NestedModules[0]: BackgroundModule.psm1
Author: Jinghao Liu
CompanyName: Fabrikam, Inc.
Copyright: Copyright © 2009 Liu Jinghao. All rights reserved.
ModuleToProcess: TestModule.psm1
Description: Cmdlets to find common errors in scripts.
TypesToProcess[0]: TestTypes.ps1xml
FormatsToProcess[0]: TestFormat.ps1xml
RequiredAssemblies[0]: Test.dll
FileList[0]: Test-Module.psd1
FileList[1]: Test-Module.psm1
FileList[2]: BackgroundModule.psm1
FileList[3]: TestTypes.ps1xml
FileList[4]: TestFormat.ps1xml
FileList[5]: Test.dll
FileList[6]: TestIcon.ico


Description
-----------
This command creates a new module manifest. The cmdlet prompts you for the parameters that it requires, including the Path parameter, and creates a manifest file in the specified location.

The output of this command shows sample responses to the prompts. To use default values, press ENTER.

The actual prompt, and its handling of quoted and non-quoted phrases, depends on the host program in which Windows PowerShell is running.

Example 2

C:\PS>New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC

This command creates a new module manifest. The command includes parameters that the cmdlet does not require (or prompt for). You can include other manifest key values at the prompt.

Example 3

C:\PS>New-ModuleManifest -RequiredModules FileTransfer,@{ModuleName="BackgroundModule";GUID="486569a2-2784-48bf-af15-70ba837a64d0";ModuleVersion="3.5"}

This example shows how to use the string and hash table formats of the RequiredModules parameter value. Strings and hash tables can be used in the same command. 

This command commands creates a module manifest for a module that requires the FileTransfer module and a (fictitious) module named "BackgroundModule". 

The command uses a string format to specify the name of the FileTransfer module and the hash table format to specify the name, a GUID, and a version of the BackgroundModule.