Module Manifests

A module manifest file defines a hash table that contains information about the module. This includes information about the root module for the manifest, metadata such as the author and description of the module, restrictions to limit which members of the module are exported, and more.

The following sample module manifest shows the keys and some of the possible values that can be used to describe a module. This example was created using the New-ModuleManifest cmdlet. When creating multiple modules, you can use this cmdlet to create a manifest template that can then be modified for different modules.

Following this example is a list of the keys and an explanation about how the values of these keys are used by Windows PowerShell.

#
# Module manifest for module 'MyModule'
#
# Generated by: Jeremy Nelson
#
# Generated on: 2/15/2009
#

@{

# Script module or binary module file associated with this manifest
ModuleToProcess = 'MyModule.dll'

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = '0093ae2d-89e4-494c-81a6-35881fafb6f2'

# Author of this module
Author = 'Jeremy Nelson'

# Company or vendor of this module
CompanyName = 'Unknown'

# Copyright statement for this module
Copyright = '(c) 2009 Jeremy Nelson. All rights reserved.'

# Description of the functionality provided by this module
Description = 'This is a template that can be used to create other module manifests.'

# 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, IA64) 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 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 files packaged with this module
FileList = @()

# Private data to pass to the module specified in ModuleToProcess
PrivateData = ''

}

ModuleToProcess

The script or binary module file that the user will associate with this manifest. It is also referred to as the root module for the manifest when nested modules are used. The name of the root module does not have to be the same as the manifest. However, the manifest and the module folder should have the same name.

If no module is specified, the manifest file becomes the root module. In this case, the module is referred to as a manifest module.

Version

The version number of the module.

In the previous example, the version number was not specified, and the New-ModuleManifest cmdlet added the default version number.

GUID

The identifier of the module.

In the previous example, the identifier was not specified, and the New-ModuleManifest cmdlet generated its own identifier.

Author

The author of the module.

In the previous example, the author was specified by the user when the New-ModuleManifest cmdlet was run. Notice that when the author is specified, it is also used in the metadata at the top of the manifest file and possibly in the copyright information.

CompanyName

The name of the company or vendor of the module.

In the previous example, the company name was not specified, so the New-ModuleManifest cmdlet added 'Unknown' .

Copyright

The copyright information for the module.

In the previous example, the copyright information was not specified, so the New-ModuleManifest cmdlet added '(c) 2009 Jeremy Nelson. All rights reserved.' .

Description

A description of the module.

In the previous example, the description was specified when the New-ModuleManifest cmdlet was run.

PowerShellVersion

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.

In the previous example, no minimum version was specified when the New-ModuleManifest cmdlet was run.

PowerShellHostName

The name of the Windows PowerShell host that is required by the module, such as "Windows PowerShell ISE Host" or "ConsoleHost". This name is provided by Windows PowerShell . To find the name of a host program, in the program, type: $host.name .

In the previous example, no host was specified when the New-ModuleManifest cmdlet was run.

PowerShellHostVersion

The minimum version number of the Windows PowerShell host that is required by the module.

In the previous example, no version was specified when the New-ModuleManifest cmdlet was run.

DotNetFrameworkVersion

The minimum version of the .NET Framework that is required by the module.

In the previous example, no version was specified when the New-ModuleManifest cmdlet was run.

CLRVersion

The version of the common language runtime (CLR) of the .NET Framework that is required by the module.

In the previous example, no CLR version was specified when the New-ModuleManifest cmdlet was run.

ProcessorArchitecture

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

In the previous example, no architecture was specified when the New-ModuleManifest cmdlet was run.

RequiredModules

Additional modules that this module requires to run. If the required modules are not in the global scope, attempts to import this module will fail.

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. Windows PowerShell does not import the required modules automatically. It only verifies that the required modules are present. However, modules can include scripts (.ps1) that import the required modules into the global scope. In the previous example, no required modules were specified when the New-ModuleManifest cmdlet was run.

RequiredAssemblies

The assembly (.dll) files that the module requires, such as assemblies required by type and formatting files. Windows PowerShell loads the specified assemblies before it updates types or formats, before it imports nested modules, or before it imports the root module.

In addition, you should specify the assemblies that are required to be loaded to update formatting or type files listed in the FormatsToProcess or TypesToProcess keys, even if those assemblies are already listed as binary modules in the NestedModules key.

In the previous example, no assemblies were specified when the New-ModuleManifest cmdlet was run.

ScriptsToProcess

The script (.ps1) files that are 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.

In the previous example, no script files were specified when the New-ModuleManifest cmdlet was run.

TypesToProcess

The type files (.ps1xml) that are associated with the module. These files contain definitions of the .NET Framework types that are used by the components of the module, such as a type returned by a cmdlet. When you import the module, Windows PowerShell runs the Update-TypeData cmdlet with the specified type files.

In the previous example, no type files were specified when the New-ModuleManifest cmdlet was run.

FormatsToProcess

The formatting files (.ps1xml) that are associated with the module. These files contain display information for .NET Framework types that are used by the components of the module. For example, these files specify whether a type returned by a cmdlet is displayed as a table or as a list. When you import the module, Windows PowerShell runs the Update-FormatData cmdlet with the specified files.

In the previous example, no formatting files were specified when the New-ModuleManifest cmdlet was run.

NestedModules

The script modules (.psm1) and binary modules (.dll) that are imported into the session state of the module but are not imported into the global session state. This means that nested modules are not visible to the user. The exported members of nested modules are imported into the root module session state, but they are not exported to the global session state unless the user uses the Global parameter of the Import-Module cmdlet or unless the root module exports the nested module members explicitly.

The files in the NestedModules key run in the order in which they are listed. This is important in cases where there are dependencies between nested modules. Also, script files (.ps1) that are listed in the NestedModules key are run in the session state of the module, not in the session state of the caller. To run a script in the caller session state, list the script file name in the ScriptsToProcess key.

In the previous example, no nested modules were specified when the New-ModuleManifest cmdlet was run.

FunctionsToExport

Restricts the functions that the module exports to the session state of the caller. The caller’s session state can be the global session state or, for nested modules, the session state of another module. When chaining nested modules, all functions that are exported by a nested module will be exported to the global session state unless a module in the chain restricts the function by using the FunctionsToExport key.

In the previous example, no functions were specified when the New-ModuleManifest cmdlet was run. In this case, the value '*' was added to the key, which means that all functions defined by the module, including any functions exported by a nested module, are exported to the caller’s session state.

CmdletsToExport

Restricts the cmdlets that the module exports to the session state of the caller. The caller’s session state can be the global session state or, for nested modules, the session state of another module. When chaining nested modules, all cmdlets that are exported by a nested module will be exported to the global session state unless a module in the chain restricts the cmdlet by using the CmdletsToExport key.

In the previous example, no cmdlets were specified when the New-ModuleManifest cmdlet was run. In this case, the value '*' was added to the key, which means that all cmdlets defined by the module, including any cmdlets exported by a nested module, are exported to the caller’s session state.

VariablesToExport

Restricts the variables that the module exports to the session state of the caller. The caller’s session state can be the global session state or, for nested modules, the session state of another module. When chaining nested modules, all variables that are exported by a nested module will be exported to the global session state unless some module in the chain restricts the variable by using the VariablesToExport key.

In the previous example, no variables were specified when the New-ModuleManifest cmdlet was run. In this case, the value '*' was added to the key, which means that all variables defined by the module, including any variables exported by a nested module, are exported to the caller’s session state.

AliasesToExport

Restricts the aliases that the module exports to the session state of the caller. The caller’s session state can be the global session state or, for nested modules, the session state of another module. When chaining nested modules, all aliases that are exported by a nested module will be exported to the global session state unless a module in the chain restricts the alias by using the AliasesToExport key.

In the previous example, no aliases were specified when the New-ModuleManifest cmdlet was run. In this case, the value '*' was added to the key, which means that all aliases defined by the module, including any aliases exported by a nested module, are exported to the caller’s session state.

FileList

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

In the previous example, no files were specified when the New-ModuleManifest cmdlet was run.

PrivateData

Data that is passed to the module when it is imported. This data is available using the $args automatic variable from within the script modules.

In the previous example, no private data was specified when the New-ModuleManifest cmdlet was run.

Concepts