如何编写 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

模块清单元素

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

示例模块清单

以下示例模块清单是在 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_Comparison_Operators
• about_If
• 全局程序集缓存
• Import-Module
• New-ModuleManifest
• Test-ModuleManifest
• Update-ModuleManifest
• 编写 Windows PowerShell 模块