如何编写 PowerShell 模块清单

---

编写 PowerShell 模块后，您可以添加包含有关该模块的信息的可选模块清单。例如，您可以描述作者、指定模块中的文件（例如嵌套模块）、运行脚本来自定义用户环境、加载类型和格式化文件、定义系统要求以及限制模块导出的成员。

创建模块清单

模块清单是一个 PowerShell 数据文件 (.psd1)，它描述模块的内容并确定模块的处理方式。清单文件是一个文本文件，其中包含键和值的哈希表。您可以通过将清单文件命名为与模块相同的名称并将清单文件存储在模块的根目录中，将清单文件链接到模块。

对于仅包含单个 .psm1 或二进制程序集的简单模块，模块清单是可选的。但是，建议尽可能使用模块清单，因为它们有助于帮助您组织代码和维护版本控制信息。并且，需要模块清单才能导出安装在全局程序集缓存中的程序集。支持可更新帮助功能的模块还需要模块清单。可更新帮助使用模块清单中的 HelpInfoUri 键来查找包含模块更新帮助文件位置的帮助信息 (HelpInfo XML) 文件。有关可更新帮助的详细信息，请参阅支持可更新帮助。

创建和使用模块清单

1. 创建模块清单的最佳实践是使用 New-ModuleManifest cmdlet。您可以使用参数来指定清单的一个或多个默认键和值。唯一的要求是命名该文件。 New-ModuleManifest 使用您指定的值创建模块清单，并包含其余键及其默认值。如果您需要创建多个模块，请使用 New-ModuleManifest 创建一个可以针对不同模块进行修改的模块清单模板。有关默认模块清单的示例，请参阅示例模块清单。

   New-ModuleManifest -Path C:\myModuleName.psd1 -ModuleVersion "2.0" -Author "YourNameHere"

   另一种方法是使用所需的最少信息（ModuleVersion）手动创建模块清单的哈希表。您可以使用与模块相同的名称保存文件，并使用 .psd1 文件扩展名。然后，您可以编辑该文件并添加适当的键和值。

2. 在清单文件中添加所需的任何其他元素。

   要编辑清单文件，请使用您喜欢的任何文本编辑器。但是，清单文件是一个包含代码的脚本文件，因此您可能希望在脚本或开发环境（例如 Visual Studio Code）中编辑它。清单文件的所有元素都是可选的，除了 ModuleVersion 数字。

   有关可以包含在模块清单中的键和值的说明，请参阅模块清单元素表。有关详细信息，请参阅 New-ModuleManifest cmdlet 中的参数说明。

3. 为了解决基本模块清单元素可能未涵盖的任何场景，您可以选择向模块清单添加其他代码。

   出于安全考虑，PowerShell 仅运行模块清单文件中可用操作的一小部分。通常，您可以使用 if 语句、算术和比较运算符以及基本的 PowerShell 数据类型。

4. 创建模块清单后，您可以对其进行测试以确认清单中描述的所有路径均正确。要测试模块清单，请使用 Test-ModuleManifest。

   Test-ModuleManifest myModuleName.psd1

5. 确保您的模块清单位于包含您的模块的目录的顶层。

   当您将模块复制到系统并导入它时，PowerShell 使用模块清单来导入您的模块。

6. 或者，您可以通过对清单本身进行点采购来调用 Import-Module 来直接测试模块清单。

   Import-Module .\myModuleName.psd1

模块清单元素

下表描述了可以包含在模块清单中的元素。

Element Default Description RootModule
Type: String <empty string> Script module or binary module file associated with this manifest. Previous versions of PowerShell called this element the ModuleToProcess.
Possible types for the root module can be empty, which creates a Manifest module, the name of a script module (.psm1), or the name of a binary module (.exe or .dll). Placing the name of a module manifest (.psd1) or a script file (.ps1) in this element causes an error.
Example: RootModule = 'ScriptModule.psm1' ModuleVersion
Type: Version '0.0.1' Version number of this module. If a value isn't specified, New-ModuleManifest uses the default. The string must be able to convert to the type Version for example #.#.#.#. Import-Module loads the first module it finds on the $PSModulePath that matches the name, and has at least as high a ModuleVersion, as the MinimumVersion parameter. To import a specific version, use the Import-Module cmdlet's RequiredVersion parameter.
Example: ModuleVersion = '1.0' GUID
Type: GUID '<GUID>' ID used to uniquely identify this module. If a value isn't specified, New-ModuleManifest autogenerates the value. You can't currently import a module by GUID.
Example: GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857' Author
Type: String '<Current user>' Author of this module. If a value isn't specified, New-ModuleManifest uses the current user.
Example: Author = 'AuthorNameHere' CompanyName
Type: String 'Unknown' Company or vendor of this module. If a value isn't specified, New-ModuleManifest uses the default.
Example: CompanyName = 'Fabrikam' Copyright
Type: String '(c) <Author>. All rights reserved.' Copyright statement for this module. If a value isn't specified, New-ModuleManifest uses the default with the current user as the <Author>. To specify an author, use the Author parameter.
Example: Copyright = '2019 AuthorName. All rights reserved.' Description
Type: String <empty string> Description of the functionality provided by this module.
Example: Description = 'This is the module's description.' PowerShellVersion
Type: Version <empty string> Minimum version of the PowerShell engine required by this module. Valid values are 1.0, 2.0, 3.0, 4.0, 5.0, 5.1, 6.0, 6.1, 6.2, 7.0 and 7.1.
Example: PowerShellVersion = '5.0' PowerShellHostName
Type: String <empty string> Name of the PowerShell host required by this module. This name is provided by PowerShell. To find the name of a host program, in the program, type: $host.name.
Example: PowerShellHostName = 'ConsoleHost' PowerShellHostVersion
Type: Version <empty string> Minimum version of the PowerShell host required by this module.
Example: PowerShellHostVersion = '2.0' DotNetFrameworkVersion
Type: Version <empty string> Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only, such as Windows PowerShell 5.1, and only applies to .NET Framework versions lower than 4.5.
Example: DotNetFrameworkVersion = '3.5' CLRVersion
Type: Version <empty string> Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only, such as Windows PowerShell 5.1, and only applies to .NET Framework versions lower than 4.5.
Example: CLRVersion = '3.5' ProcessorArchitecture
Type: ProcessorArchitecture <empty string> Processor architecture (None, X86, Amd64) required by this module. Valid values are x86, AMD64, Arm, IA64, MSIL, and None (unknown or unspecified).
Example: ProcessorArchitecture = 'x86' RequiredModules
Type: Object[] @() Modules that must be imported into the global environment prior to importing this module. This loads any modules listed unless they've already been loaded. For example, some modules may already be loaded by a different module. It's possible to specify a specific version to load using RequiredVersion rather than ModuleVersion. When ModuleVersion is used it will load the newest version available with a minimum of the version specified. You can combine strings and hash tables in the parameter value.
Example: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; ModuleVersion="2.0"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
Example: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; RequiredVersion="1.5"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"}) RequiredAssemblies
Type: String[] @() Assemblies that must be loaded prior to importing this module. Specifies the assembly (.dll) file names that the module requires.
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.
Example: RequiredAssemblies = @("assembly1.dll", "assembly2.dll", "assembly3.dll") ScriptsToProcess
Type: String[] @() 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 log in script.
These scripts are run before any of the modules listed in the manifest are loaded.
Example: ScriptsToProcess = @("script1.ps1", "script2.ps1", "script3.ps1") TypesToProcess
Type: String[] @() Type files (.ps1xml) to be loaded when importing this module.
Example: TypesToProcess = @("type1.ps1xml", "type2.ps1xml", "type3.ps1xml") FormatsToProcess
Type: String[] @() Format files (.ps1xml) to be loaded when importing this module.
Example: FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml") NestedModules
Type: Object[] @() Modules to import as nested modules of the module specified in RootModule (alias:ModuleToProcess).
Adding a module name to this element is similar to calling Import-Module from within your script or assembly code. The main difference by using a manifest file is that it's easier to see what you're loading. And, if a module fails to load, you will not yet have loaded your actual module.
In addition to other modules, you may also load script (.ps1) files here. These files will execute in the context of the root module. This is equivalent to dot sourcing the script in your root module.
Example: NestedModules = @("script.ps1", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"}) FunctionsToExport
Type: String[] @() Specifies the functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. By default, no functions are exported. You can use this key to list the functions that are exported by the module.
The module exports the functions to the caller's session state. 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 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.
Example: FunctionsToExport = @("function1", "function2", "function3") CmdletsToExport
Type: String[] @() Specifies the cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. By default, no cmdlets are exported. You can use this key to list 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're 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.
If the manifest 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.
Example: CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet") VariablesToExport
Type: String[] '*' Specifies the variables that the module exports to the caller's session state. Wildcard characters are permitted. 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.
Example: VariablesToExport = @('$MyVariable1', '$MyVariable2', '$MyVariable3') AliasesToExport
Type: String[] @() Specifies the aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. By default, no aliases are exported. You can use this key to list the aliases that are exported by the module.
The module exports the aliases to caller's session state. 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.
Example: AliasesToExport = @("MyAlias1", "MyAlias2", "MyAlias3") DscResourcesToExport
Type: String[] @() Specifies DSC resources to export from this module. Wildcards are permitted.
Example: DscResourcesToExport = @("DscResource1", "DscResource2", "DscResource3") ModuleList
Type: Object[] @() Specifies all the modules that are packaged with this module. These modules can be entered by name, using 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.
Example: ModuleList = @("SampleModule", "MyModule", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"}) FileList
Type: String[] @() List of all files packaged with this module. As with ModuleList, FileList is an inventory list, and isn't otherwise processed.
Example: FileList = @("File1", "File2", "File3") PrivateData
Type: Object @{...} Specifies any private data that needs to be passed to the root module specified by the RootModule (alias: ModuleToProcess) key. PrivateData is a hash table that comprises several elements: Tags, LicenseUri, ProjectURI, IconUri, ReleaseNotes, Prerelease, RequireLicenseAcceptance, and ExternalModuleDependencies. Tags
Type: String[] @() Tags help with module discovery in online galleries.
Example: Tags = "PackageManagement", "PowerShell", "Manifest" LicenseUri
Type: Uri <empty string> A URL to the license for this module.
Example: LicenseUri = 'https://www.contoso.com/license' ProjectUri
Type: Uri <empty string> A URL to the main website for this project.
Example: ProjectUri = 'https://www.contoso.com/project' IconUri
Type: Uri <empty string> A URL to an icon representing this module.
Example: IconUri = 'https://www.contoso.com/icons/icon.png' ReleaseNotes
Type: String <empty string> Specifies the module's release notes.
Example: ReleaseNotes = 'The release notes provide information about the module. PreRelease
Type: String <empty string> This parameter was added in PowerShellGet 1.6.6. A PreRelease string that identifies the module as a prerelease version in online galleries.
Example: PreRelease = 'alpha' RequireLicenseAcceptance
Type: Boolean $false This parameter was added in PowerShellGet 1.5. Flag to indicate whether the module requires explicit user acceptance for install, update, or save.
Example: RequireLicenseAcceptance = $false ExternalModuleDependencies
Type: String[] @() This parameter was added in PowerShellGet v2. A list of external modules that this module is dependent upon.
Example: ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3") HelpInfoURI
Type: String <empty string> HelpInfo URI of this module.
Example: HelpInfoURI = 'https://www.contoso.com/help' DefaultCommandPrefix
Type: String <empty string> Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
Example: DefaultCommandPrefix = 'My'

示例模块清单

以下示例模块清单是在 PowerShell 7 中使用 New-ModuleManifest 创建的，包含默认键和值。

#
# Module manifest for module 'SampleModuleManifest'
#
# Generated by: User01
#
# Generated on: 10/15/2019
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

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

# Supported PSEditions
# CompatiblePSEditions = @()

# ID used to uniquely identify this module
GUID = 'b632e90c-df3d-4340-9f6c-3b832646bf87'

# Author of this module
Author = 'User01'

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

# Copyright statement for this module
Copyright = '(c) User01. All rights reserved.'

# Description of the functionality provided by this module
# Description = ''

# Minimum version of the PowerShell engine required by this module
# PowerShellVersion = ''

# Name of the PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# 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, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()

# Variables to export from this module
VariablesToExport = '*'

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
# DscResourcesToExport = @()

# 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. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        # Tags = @()

        # A URL to the license for this module.
        # LicenseUri = ''

        # A URL to the main website for this project.
        # ProjectUri = ''

        # A URL to an icon representing this module.
        # IconUri = ''

        # ReleaseNotes of this module
        # ReleaseNotes = ''

        # Prerelease string of this module
        # Prerelease = ''

        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
        # RequireLicenseAcceptance = $false

        # External dependent modules of this module
        # ExternalModuleDependencies = @()

    } # End of PSData hashtable

} # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}

参见

• about_比较_运算符
• 关于_如果
• 全局程序集缓存
• Import-Module
• New-ModuleManifest
• Test-ModuleManifest
• Update-ModuleManifest
• 编写 Windows PowerShell 模块