How to Write a Module Manifest

  • Article

This topic describes how to create a module manifest that contains the standard keys by using the New-ModuleManifest cmdlet, and it describes how to manually configure the advanced keys.

When you use the New-ModuleManifest cmdlet, you can explicitly specify each parameter. Or, you can use the prompts provided by the cmdlet to set the standard keys of the manifest. A module manifest is a Windows PowerShell data file (.psd1) that contains a hash table of keys and values that describe the components of the module.

The first procedure shows how to use the cmdlet prompts to set the standard keys and to create the module manifest file. The second procedure explains how to open the module manifest file and set the advanced keys. In most cases, the module manifest can be used by setting only the standard keys.

To specify the standard keys

  1. At the Windows PowerShell command prompt, type new-modulemanifest, and then press ENTER. After you press ENTER, the cmdlet prompts you for the path.

  2. At the prompt, specify the path and file name of the new module manifest. Enter a path and a file name with a .psd1 file name extension, such as "User\Modules\MyModule\MyModule.psd1". This parameter is required.

    Typically, modules are stored under the user folder (as shown in the previous paragraph) or in the system folder. In this example, the manifest is created for a module located under the user folder. The prompt you receive resembles the following prompt.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [User]\documents\windowspowershell\modules\MyModule\MyModule.psd1

    If you specify the path to an existing file, the New-ModuleManifest cmdlet replaces that file without warning unless the file is read-only. The manifest file and the module folder should have the same name, but the module manifest file must have a .psd1 file name extension.

    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.

  3. At the NestedModules prompt, optionally specify any script modules (.psm1) and binary modules (.dll) that are imported into the module’s session state, and then press ENTER. If no nested modules are specified, as in the following example, the New-ModuleManifest cmdlet creates a NestedModules key whose value is an empty list.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:

    The members of the nested modules are imported into the caller's session state only when the root module exports the nested module members explicitly or when the root module omits the Export-ModuleMember command. This will export all commands by default, including commands from nested modules.

    Nested modules in the module’s session state are available to the root module, but they are not evident to the user. Nested modules are not returned by the Get-Module cmdlet, nor are their members returned by the Get-Command cmdlet. The files in the NestedModules key of the manifest run in the order in which they are listed.

    Scripts (.ps1) that are listed in the NestedModules key are run in the module’s session state, not in the global session state. To run a script in the global session state, list the script file name in the ScriptsToProcess key in the manifest.

  4. At the Author prompt, optionally specify the author of the module, and then press ENTER. If no author is specified, the New-ModuleManifest cmdlet creates an Author key whose value is the name of the current user.

    In this example, the author is specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson

  5. At the CompanyName prompt, optionally specify the company name or vendor of the module. If the company name or vendor is not specified, the New-ModuleManifest cmdlet creates a CompanyName key with a value of "Unknown".

    In this example, the company name is specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso

  6. At the Copyright prompt, optionally specify the copyright information for the module, and then press ENTER. If no copyright information is specified, the New-ModuleManifest cmdlet creates a Copyright key with the following value:

    (c) year user_name. All rights reserved.

    In this value, the year placeholder is replaced by the current year and the user_name placeholder is replaced by the value of the Author key (if one is specified) or the name of the current user.

    In this example, the copyright information is not specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright:

  7. At the ModuleToProcess prompt, optionally specify the root module file of the manifest, and then press ENTER. Enter the file name of one script module (. psm1) or binary module (.dll). When the module is imported, the members that are exported from the root module file are imported into the global session state. If no root module is specified, the New-ModuleManifest cmdlet creates a ModuleToProcess key with an empty string value. In this case, the manifest file becomes the root file for the module, and the module becomes a manifest module (ModuleType = Manifest).

    In this example, no file is specified as the root module file.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:

    To export members from .psm1 or .dll files in a module that has a manifest, specify the names of those files in the values of the ModuleToProcess or NestedModules keys in the module manifest. Otherwise, their members are not exported.

  8. At the Description prompt, optionally specify a short description of the module manifest, and then press ENTER. If a description is not specified, the New-ModuleManifest cmdlet creates a Description key with an empty string value.

    In this example, a short description of the module is specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:
Description: This is a test module manifest.

  9. At the TypesToProcess prompt, optionally specify any type files that need to be processed when the module is imported, and then press ENTER. If no type files are specified, the New-ModuleManifest cmdlet creates a TypesToProcess key whose value is an empty list.

    In this example, no type files are specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:
Description: This is a test module manifest.
TypesToProcess[0]:

    Type files are used by Windows PowerShell to add members to a .NET Framework type.

  10. At the FormatsToProcess prompt, optionally specify any formatting files that need to be processed when the module is imported, and then press ENTER. If no formatting files are specified, the New-ModuleManifest cmdlet creates a FormatsToProcess key whose value is an empty list.

    In this example, no formatting files are specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:
Description: This is a test module manifest.
TypesToProcess[0]:
FormatsToProcess[0]:

    Formatting files are used by Windows PowerShell to define how the members of a .NET Framework type are displayed.

  11. At the RequiredAssemblies prompt, optionally specify any assembly (.dll) files that the module requires, and then press ENTER. If no assemblies are specified, the New-ModuleManifest cmdlet creates a RequiredAssemblies key whose value is an empty list.

    In this example, no formatting files are specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:
Description: This is a test module manifest.
TypesToProcess[0]:
FormatsToProcess[0]:
RequiredAssemblies[0]:

    Windows PowerShell loads the specified assemblies before it processes type and formatting files, before it imports nested modules, or before it imports the root module file that is specified by the ModuleToProcess key.

  12. At the FileList prompt, optionally specify all the items that are included in the module, and then press ENTER. If files are specified, the New-ModuleManifest cmdlet creates a FileList key whose value is an empty list.

    In this example, no formatting files are specified.

    cmdlet New-ModuleManifest at command pipeline position 1
Supply values for the following parameters:
Path: [user]\documents\windowspowershell\modules\MyModule\MyModule.psd1
NestedModules[0]:
Author: Jeremy Nelson
CompanyName: Contoso
Copyright: 
ModuleToProcess:
Description: This is a test module manifest.
TypesToProcess[0]:
FormatsToProcess[0]:
RequiredAssemblies[0]:
FileList[0]:

When you press ENTER at the FileList prompt, the cmdlet creates a manifest in the specified path. Then, you can call the Import-Module cmdlet to load the module.

To specify the advanced keys

  1. Use a text editor such as Notepad to open the module manifest file that was created by the New-ModuleManifest cmdlet.

  2. From the following list, select the advanced keys that you need to set, and modify the manifest file as needed.

    • Version key
      Specifies the version number of the module. By default, Windows PowerShell enters '1.0' when the manifest is created.
    • ID key
      Specifies an identifier that uniquely identifies the module. By default, Windows PowerShell generates a globally unique identifier (GUID) when the manifest is created.
    • PowerShellVersion key
      Specifies the minimum version of Windows PowerShell that will work with this module. Valid versions are 1.0 or 2.0. Requirements for versions greater than 2.0 are not enforced.
    • PowerShellHostName key
      Specifies 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 .
    • PowerShellHostVersion key
      Specifies the minimum version of the Windows PowerShell host program that works with the module.
    • DotNetFrameworkVersion key
      Specifies the minimum version of the .NET Framework that is required by the module.
    • CLRVersion key
      Specifies the minimum version of the common language runtime (CLR) that is required by the module.
    • ProcessorArchitecture key
      Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, and None (unknown or unspecified).
    • ScriptsToProcess key
      Specifies script (.ps1) files that are run in the caller's session state when the module is imported. This could be the global session state or, for nested modules, the session state of another module. You can use these scripts to prepare an environment just as you might use a login script.

    • FunctionsToExport key
      Specifies the functions that the module exports (wildcard characters are permitted) to the caller’s session state. By default, all functions are exported. You can use this key to restrict the functions that are exported by the module.

      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.

      If the manifest also exports aliases for the functions, this key can remove functions whose aliases are listed in the AliasesToExport key, but this key cannot add function aliases to the list.

    • CmdletsToExport key
      Specifies the cmdlets that the module exports (wildcard characters are permitted). By default, all cmdlets are exported. You can use this key to restrict the cmdlets that are exported by the module.

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

      If the manifest also exports aliases for the cmdlets, this key can remove cmdlets whose aliases are listed in the AliasesToExport key, but this key cannot add cmdlet aliases to the list.

    • VariablesToExport key
      Specifies the variables that the module exports (wildcard characters are permitted) to the caller’s session state. By default, all variables are exported. You can use this key to restrict the variables that are exported by the module.

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

      If the manifest also exports aliases for the variables, this key can remove variables whose aliases are listed in the AliasesToExport key, but this key cannot add variable aliases to the list.

    • AliasesToExport key
      Specifies the aliases that the module exports (wildcard characters are permitted) to the caller’s session state. By default, all aliases are exported. You can use this key to restrict the aliases that are exported by the module.

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

    • ModuleList key
      Specifies all the modules that are packaged with this module. These modules can be entered by name (a comma-separated string) or as a hash table with ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key. The ModuleList key is designed to act as a module inventory. These modules are not automatically processed.
    • PrivateData key
      Specifies any private data that needs to be passed to the root module specified by the ModuleToProcess key.

  3. Save the module manifest file.

See Also

Concepts

Writing a Windows PowerShell Module