通过

about_Module_Manifests

  • 项目

简短说明

介绍编写模块清单文件的设置和做法。

长说明

模块清单是包含哈希表的 PowerShell 数据文件 (.psd1)。 哈希表中的键值对用于描述该模块的内容和属性、定义先决条件以及控制如何处理组件。

清单不需要加载模块，但需要将模块发布到 PowerShell 库。 清单还使你能够将模块的实现与加载方式分开。 使用清单，可以定义要求、兼容性、加载顺序等。

在不指定清单设置的任何参数使用 New-ModuleManifest 时，它会写入最小清单文件。 以下代码片段演示了此默认输出，为简洁起见，截断了注释和间距：

@{
# RootModule = ''
ModuleVersion = '1.0'
# CompatiblePSEditions = @()
GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b'
Author = 'username'
CompanyName = 'Unknown'
Copyright = '(c) 2022 username. All rights reserved.'
# Description = ''
# PowerShellVersion = ''
# PowerShellHostName = ''
# PowerShellHostVersion = ''
# DotNetFrameworkVersion = ''
# CLRVersion = ''
# ProcessorArchitecture = ''
# RequiredModules = @()
# RequiredAssemblies = @()
# ScriptsToProcess = @()
# TypesToProcess = @()
# FormatsToProcess = @()
# NestedModules = @()
FunctionsToExport = @()
CmdletsToExport = @()
VariablesToExport = '*'
AliasesToExport = @()
# DscResourcesToExport = @()
# ModuleList = @()
# FileList = @()
PrivateData = @{
    PSData = @{
        # Tags = @()
        # LicenseUri = ''
        # ProjectUri = ''
        # IconUri = ''
        # ReleaseNotes = ''
    } # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfoURI = ''
# DefaultCommandPrefix = ''
}

在发布模块之前，可以使用 Test-ModuleManifest 来验证模块清单。 如果清单无效或模块无法导入当前会话，则 Test-ModuleManifest 会返回错误，因为会话不符合清单中设置的要求。

在模块清单中使用脚本代码

为清单文件中设置分配的值可以是 PowerShell 计算的表达式。 这样，就可以基于变量构造路径并有条件地分配值。

使用 Import-Module 导入模块时，将在 Restricted 语言模式下评估清单。 Restricted 模式限制可以使用的命令和变量。

允许的命令

  • Import-LocalizedData
  • ConvertFrom-StringData
  • Write-Host
  • Out-Host
  • Join-Path

允许的变量

  • $PSScriptRoot
  • $PSEdition
  • $EnabledExperimentalFeatures
  • 任何环境变量，例如 $ENV:TEMP

有关详细信息，请参阅 about_Language_Modes。

清单设置

以下部分详细介绍了模块清单中的每个可用设置，以及如何使用这些设置。 它们以背景概述开始，然后是一个矩阵，列出以下内容：

  • 输入类型：可以在清单中为此设置指定的对象类型。
  • 必需：如果此值为 Yes，则需要设置才能导入模块并将其发布到 PowerShell 库。 如果为 No，则这两者都不需要。 如果为 PowerShell Gallery，则只需发布到 PowerShell 库。
  • 值（如果未设置）：此设置在导入时未显式设置的值。
  • 接受通配符：此设置是否可以采用通配符值。

RootModule

此设置指定模块的主文件或根文件。 导入模块时，由根模块文件导出的成员将导入到调用方的会话状态中。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

该值必须是以下项之一的路径：

  • 脚本 (.ps1)
  • 脚本模块 (.psm1)
  • 模块清单 (.psd1)
  • 程序集 (.dll)
  • cmdlet 定义 XML 文件 (.cdxml)
  • Windows PowerShell 5.1 工作流 (.xaml)

路径应与模块清单相对。

如果模块清单未在 RootModule 键中指定任何根文件，则该清单将成为模块的主文件，并且该模块将成为清单模块(ModuleType = Manifest)。 定义 RootModule 时，模块的类型取决于使用的文件扩展名：

  • .ps1 或 .psm1 文件使模块类型为 脚本
  • .psd1 文件使模块类型为 清单
  • .dll 文件使模块类型为 二进制
  • .cdxml 文件使模块类型为 CIM
  • .xaml 文件使模块类型为 工作流

默认情况下，会导出 RootModule 中的所有模块成员。

提示

模块加载速度在 二进制、脚本 和 CIM 模块类型之间有所不同。 有关详细信息，请参阅 PowerShell 模块创作注意事项

例如，此模块的 ModuleType 是清单。 此模块唯一可以导出的模块成员是在使用 NestedModules 设置指定的模块中定义的模块。

@{
    RootModule = ''
}

注意

也可以在模块清单中将此设置指定为 ModuleToProcess。 虽然此设置的名称有效，但最佳做法是改用 RootModule。

ModuleVersion

此设置指定模块的版本。 当系统上存在多个版本的模块时，默认情况下，运行 Import-Module 时会加载最新版本。

值
输入类型 System.String
必需 是
值（如果未设置） 无
接受通配符 否

运行 Import-Module 时，此设置的值必须可转换为 System.Version。

例如，此清单将模块的版本声明为 '1.2.3'。

@{
    ModuleVersion = '1.2.3'
}

导入模块并检查 Version 属性时，请注意，它是 System.Version 对象，而不是字符串：

$ExampleModule = Import-Module example.psd1
$ExampleModule.Version
$ExampleModule.Version.GetType().Name

Major  Minor  Build  Revision
-----  -----  -----  --------
1      2      3      -1

Version

CompatiblePSEditions

此设置指定模块的兼容 PSEdition。

值
输入类型 System.String[]
接受的值 %>
必需 否
值（如果未设置） $null
接受通配符 否

如果此设置的值为 $null，则可以导入模块，而无须考虑会话的 PSEdition。 可以将它设置为一个或多个接受的值。

有关 PSEdition 的信息，请参阅：

定义此设置后，模块只能导入会话，其中 $PSEdition 自动变量的值包含在设置中。

注意

由于版本 5.1 中引入了 $PSEdition 自动变量，旧版 Windows PowerShell 无法加载使用 CompatiblePSEditions 设置的模块。

例如，可以在任何会话中导入此模块清单：

@{
    # CompatiblePSEditions = @()
}

指定设置后，此模块只能在 $PSEdition 自动变量的值为 Core 的会话中导入。

@{
    CompatiblePSEditions = @('Core')
}

GUID

此设置指定模块的唯一标识符。 GUID 用于区分同名模块。

值
输入类型 System.String
必需 否
值（如果未设置） 00000000-0000-0000-0000-000000000000
接受通配符 否

运行 Import-Module 时，此设置的值必须可转换为 System.Guid。

注意

虽然这不是必需的设置，但在清单中不指定 GUID 没有益处，并可能导致模块的名称冲突。

可以创建新的 GUID 以在清单中使用：

New-Guid | Select-Object -ExpandProperty Guid

8456b025-2fa5-4034-ae47-e6305f3917ca

@{
    GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
}

如果计算机上存在同名的另一个模块，仍可以通过指定模块的完全限定名称以导入所需模块：

Import-Module -FullyQualifiedName @{
    ModuleName    = 'Example'
    GUID          = '8456b025-2fa5-4034-ae47-e6305f3917ca'
    ModuleVersion = '1.0.0'
}

作者

此设置标识模块作者。

值
输入类型 System.String
必需 PowerShell 库
值（如果未设置） $null
接受通配符 否

此清单声明模块的作者是 Contoso 开发人员体验团队。

@{
    Author = 'Contoso Developer Experience Team'
}

CompanyName

此设置标识创建了该模块的公司或供应商。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

此清单声明模块是由 Contoso, Ltd 创建的。

@{
    CompanyName = 'Contoso, Ltd.'
}

此设置指定模块的版权声明。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

截至 2022 年，本清单声明版权归 Contoso, Ltd. 所有。

@{
    Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.'
}

说明

此设置介绍高级别的模块。

值
输入类型 System.String
必需 PowerShell 库
值（如果未设置） $null
接受通配符 否

此清单包含简短说明。 还可以使用此处的字符串编写较长或多行说明。

@{
    Description = 'Example commands to show a valid module manifest'
}

PowerShellVersion

此设置指定此模块所需的最低 PowerShell 版本。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

运行 Import-Module 时，此设置的值必须可转换为 System.Version。

如果未设置此设置，则 PowerShell 不会根据当前版本限制模块的导入。

例如，此清单声明模块与 PowerShell 和 Windows PowerShell 的每个版本兼容。

@{
    # PowerShellVersion = ''
}

将 PowerShellVersion 设置为 7.2 后，只能在 PowerShell 7.2 或更高版本中导入模块。

@{
    PowerShellVersion = '7.2'
}

PowerShellHostName

此设置指定模块所需的 PowerShell 主机程序的名称，例如 Windows PowerShell ISE Host 或 ConsoleHost。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

可以使用 $Host.Name 语句找到会话的主机名称。 例如，可以看到远程会话的主机 ServerRemoteHost 而非 ConsoleHost：

$Host.Name
Enter-PSSession -ComputerName localhost
$Host.Name

ConsoleHost
[localhost]: PS C:\Users\username\Documents> $Host.Name
ServerRemoteHost

此模块可以导入到任何主机。

@{
    # PowerShellHostName = ''
}

将 PowerShellHostName 设置为 ServerRemoteHost后，只能在远程 PowerShell 会话中导入模块。

@{
    PowerShellHostName = 'ServerRemoteHost'
}

PowerShellHostVersion

此设置指定模块所需的 PowerShell 主机程序的最低版本。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

运行 Import-Module 时，此设置的值必须可转换为 System.Version。

注意

虽然此设置可以在不使用 PowerShellHostName 设置的情况下使用，但它会增加意外行为的几率。 仅当同时使用 PowerShellHostName 设置时使用此设置。

例如，无论主机的版本如何，都可以从 ConsoleHost 中运行的任何 PowerShell 会话导入此清单的模块。

@{
    PowerShellHostName = 'ConsoleHost'
    # PowerShellHostVersion = ''
}

将 PowerShellHostVersion 设置为 5.1后，只能从在主机版本为 5.1 或更高版本的 ConsoleHost 中运行的任何 PowerShell 会话导入模块。

@{
    PowerShellHostName    = 'ConsoleHost'
    PowerShellHostVersion = '5.1'
}

DotNetFrameworkVersion

此设置指定模块需要的 Microsoft .NET Framework 的最低版本。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

注意

此设置仅适用于 PowerShell Desktop 版本（如 Windows PowerShell 5.1），并且仅适用于低于 4.5 的 .NET Framework 版本。 此要求对较新版本的 PowerShell 或 .NET Framework 不起作用。

运行 Import-Module 时，此设置的值必须可转换为 System.Version。

例如，此清单声明其模块可以在任何 PowerShell 或 Windows PowerShell 会话中导入，而不考虑 Microsoft .NET Framework 的版本。

@{
    # DotNetFrameworkVersion = ''
}

将 DotNetFrameworkVersion 设置为 4.0 后，可以在 Windows PowerShell 的任何会话中导入此模块，其中 Microsoft .NET Framework 的最新版本应至少为 4.0。 还可以在任何 PowerShell 会话中导入它。

@{
    DotNetFrameworkVersion = '4.0'
}

CLRVersion

此设置指定模块需要的 Microsoft .NET Framework 的公共语言运行时 (CLR) 的最低版本。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

注意

此设置仅适用于 PowerShell Desktop 版本（如 Windows PowerShell 5.1），并且仅适用于低于 4.5 的 .NET Framework 版本。 此要求对较新版本的 PowerShell 或 .NET Framework 不起作用。

运行 Import-Module 时，此设置的值必须可转换为 System.Version。

例如，此清单声明其模块可以在任何 PowerShell 或 Windows PowerShell 会话中导入，而不考虑 Microsoft .NET Framework 的 CLR 版本。

@{
    # CLRVersion = ''
}

将 CLRVersion 设置为 4.0后，可以在 Windows PowerShell 的任何会话中导入此模块，其中 CLR 的最新版本至少为 4.0。 还可以在任何 PowerShell 会话中导入它。

@{
    CLRVersion = '4.0'
}

ProcessorArchitecture

此设置指定模块需要的处理器体系结构。

值
输入类型 System.String
接受的值
必需 否
值（如果未设置） None
接受通配符 否

运行 Import-Module 时，此设置的值必须可转换为 System.Reflection.ProcessorArchitecture。

例如，此清单声明可以在任何会话中导入其模块，而不考虑系统的处理器体系结构。

@{
    # ProcessorArchitecture = ''
}

将 ProcessorArchitecture 设置为 Amd64后，只能在具有匹配体系结构的计算机上运行的会话中导入此模块。

@{
    ProcessorArchitecture = 'Amd64'
}

RequiredModules

此设置指定必须处于全局会话状态的模块。 如果所需模块未处于全局会话状态，则 PowerShell 将导入它们。 如果所需的模块不可用，Import-Module 命令将失败。

值
输入类型 %>
必需 否
值（如果未设置） $null
接受通配符 否

此设置的条目可以是模块名称、完整的模块规范或模块文件的路径。

如果该值是路径，则可以是完全限定路径或相对路径。

当该值为名称或模块规范时，PowerShell 会在 PSModulePath 中搜索指定的模块。

模块规范是具有以下键的哈希表。

  • ModuleName - 必需。 指定模块名称。
  • GUID - 可选。 指定模块的 GUID。
  • 它还必需指定以下三个键中的至少一个。 RequiredVersion 键不能与 ModuleVersion 或 MaximumVersion 键一起使用。 可以通过同时指定 ModuleVersion 和 MaximumVersion 键来定义模块的可接受版本范围。
    • ModuleVersion - 指定模块的最低可接受版本。
    • RequiredVersion - 指定模块所需的准确版本。
    • MaximumVersion - 指定模块的最高可接受版本。

注意

Windows PowerShell 5.0 中添加了 RequiredVersion。 已在 Windows PowerShell 5.1 中添加 MaximumVersion。

例如，此清单声明其模块不需要任何其他模块来使其功能。

@{
    # RequiredModules = @()
}

此清单声明它需要 PSReadLine 模块。 在此清单上运行 Import-Module 时，PowerShell 会导入可用于会话的最新版本的 PSReadLine。 如果没有可用的版本，则导入将返回错误。

@{
    RequiredModules = @(
        'PSReadLine'
    )
}

提示

在 PowerShell 2.0 中，Import-Module 不会自动导入所需的模块。 它只会验证所需模块是否处于全局会话状态。

此清单声明需要其自己的模块文件夹中供应商的 PSReadLine 模块版本。 在此清单上运行 Import-Module 时，PowerShell 将从指定路径导入供应商的 PSReadLine。

@{
    RequiredModules = @(
        'Vendored\PSReadLine\PSReadLine.psd1'
    )
}

此清单声明它指定需要 PSReadLine 模块版本 2.0.0。 在此清单上运行 Import-Module 时，PowerShell 会导入 PSReadLine 版本 2.0.0（如果可用）。 如果不可用，则 Import-Module 将返回错误。

@{
    RequiredModules = @(
        @{
            ModuleName      = 'PSReadLine'
            RequiredVersion = '2.0.0'
        }
    )
}

此清单声明它要求在版本 2.0.0 或更高版本中导入 PSReadLine 模块。

@{
    RequiredModules = @(
        @{
            ModuleName    = 'PSReadLine'
            ModuleVersion = '2.0.0'
        }
    )
}

此清单声明它要求在版本 2.0.0 或更低版本中导入 PSReadLine 模块。

@{
    RequiredModules = @(
        @{
            ModuleName     = 'PSReadLine'
            MaximumVersion = '2.0.0'
        }
    )
}

此清单声明它要求在版本等于或高于 2.0.0 但低于 2.99.99 的版本导入 PSDesiredStateConfiguration 模块。

@{
    RequiredModules = @(
        @{
            ModuleName     = 'PSDesiredStateConfiguration'
            ModuleVersion  = '2.0.0'
            MaximumVersion = '2.99.99'
        }
    )
}

RequiredAssemblies

此设置指定模块所需的程序集 (.dll) 文件。 PowerShell 先加载指定的程序集，然后再更新类型或格式、导入嵌套模块，或导入在 RootModule 键的值中指定的模块文件。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 否

此设置的条目可以是程序集的文件名或路径。 列出所有必需的程序集，即使它们也被列为 NestedModules 设置中的二进制模块也是如此。

此清单需要 example.dll 程序集。 在此清单中指定的任何格式或类型文件加载之前，PowerShell 会从与模块清单位于同一目录中的 Assemblies 文件夹中加载 example.dll。

@{
    RequiredAssemblies = @(
        'Assemblies\Example.dll'
    )
}

ScriptsToProcess

此设置指定导入模块时在调用方的会话状态中运行的脚本 (.ps1) 文件。 可以像使用登录脚本一样使用这些脚本来准备环境。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 否

若要指定在模块的会话状态中运行的脚本，请使用 NestedModules 键。

导入此清单时，PowerShell 会在当前会话中运行 Initialize.ps1。

@{
    ScriptsToProcess = @(
        'Scripts\Initialize.ps1'
    )
}

例如，如果 Initialize.ps1 写入信息性消息并设置 $ExampleState 变量：

if ([string]::IsNullOrEmpty($ExampleState)) {
    Write-Information "Example not initialized."
    Write-Information "Initializing now..."
    $ExampleState = 'Initialized'
} else {
    Write-Information "Example already initialized."
}

导入模块时，脚本将运行，编写这些消息，并在会话中设置 $ExampleState。

$InformationPreference = 'Continue'
"Example State is: $ExampleState"
Import-Module .\example7x.psd1
"Example State is: $ExampleState"
Import-Module .\example7x.psd1 -Force

Example State is:

Example not initialized.
Initializing now...

Example State is: Initialized

Example already initialized.

TypesToProcess

此设置指定在导入模块时运行的类型文件 (.ps1xml)。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 否

导入模块时，PowerShell 使用指定的文件运行 Update-TypeData cmdlet。 由于没有确定类型文件的作用域，因此它们会影响会话中的所有会话状态。

有关类型文件的详细信息，请参阅 about_Types.ps1xml。

例如，导入此清单时，PowerShell 会从模块清单所在的同一目录中的 Types 文件夹中加载 Example.ps1xml 文件中指定的类型。

@{
    TypesToProcess = @(
        'Types\Example.ps1xml'
    )
}

FormatsToProcess

此设置指定在导入模块时运行的格式设置文件 (.ps1xml)。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 否

导入模块时，PowerShell 使用指定的文件运行 Update-FormatData cmdlet。 由于没有确定格式设置文件的作用域，因此它们会影响会话中的所有会话状态。

有关类型文件的详细信息，请参阅 about_Format.ps1xml

例如，导入此模块时，PowerShell 会从模块清单所在的同一目录中的 Formats 文件夹中加载 Example.ps1xml 文件中指定的格式。

@{
    FormatsToProcess = @(
        'Formats\Example.ps1xml'
    )
}

NestedModules

此设置指定导入模块的会话状态中的脚本模块 (.psm1) 和二进制模块 (.dll)。 还可以指定脚本文件 (.ps1)。 此设置中的文件按列出顺序运行。

值
输入类型 %>
必需 否
值（如果未设置） $null
接受通配符 否

此设置的条目可以是模块名称、完整的模块规范或模块或脚本文件的路径。

如果该值是路径，则可以是完全限定路径或相对路径。

当该值为模块名称或模块规范时，PowerShell 会在 PSModulePath 中搜索指定的模块。

模块规范是具有以下键的哈希表。

  • ModuleName - 必需。 指定模块名称。
  • GUID - 可选。 指定模块的 GUID。
  • 它还必需指定以下三个键中的至少一个。 RequiredVersion 键不能与 ModuleVersion 或 MaximumVersion 键一起使用。 可以通过同时指定 ModuleVersion 和 MaximumVersion 键来定义模块的可接受版本范围。
    • ModuleVersion - 指定模块的最低可接受版本。
    • RequiredVersion - 指定模块所需的准确版本。
    • MaximumVersion - 指定模块的最高可接受版本。

注意

Windows PowerShell 5.0 中添加了 RequiredVersion。 已在 Windows PowerShell 5.1 中添加 MaximumVersion。

任何需要从嵌套模块导出的项都必须由嵌套模块使用 Export-ModuleMember cmdlet 导出，或列在其中一个导出属性中：

  • FunctionsToExport
  • CmdletsToExport
  • VariablesToExport
  • AliasesToExport

模块会话状态中的嵌套模块对根模块可用，但它们不会由调用方的会话状态中的 Get-Module 命令返回。

将在模块的会话状态（而不是调用方的会话状态）中运行在此设置中列出的脚本 (.ps1)。 若要在调用方会话状态下运行脚本，请在 scriptsToProcess 设置中列出脚本文件名。

例如，导入此清单时，Helpers.psm1 模块将加载到根模块的会话状态。 除非另有限制，否则将导出嵌套模块中声明的任何 cmdlet。

@{
    NestedModules = @(
        'Helpers\Helpers.psm1'
    )
}

FunctionsToExport

此设置指定模块导出的函数。 可以使用此设置来限制由模块导出的函数。 它可以从导出的函数列表中删除函数，但不能将函数添加到该列表中。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 是

可以使用通配符在此设置中指定条目。 导出的函数列表中的所有匹配函数都会得到导出。

提示

为了获得性能和可发现性，应始终显式列出希望模块在此设置中导出的函数，而无需使用任何通配符。

例如，导入带有注释禁止设置的模块时，将导出根模块中的所有函数和任何嵌套模块。

@{
    # FunctionsToExport = @()
}

此清单在功能上等同于完全不指定设置。

@{
    FunctionsToExport = '*'
}

当 FunctionsToExport 设置为空数组，导入此模块时，根模块或任何嵌套模块导出都不可用。

@{
    FunctionsToExport = @()
}

注意

如果使用 New-ModuleManifest 命令创建模块清单，并且未指定 FunctionsToExport 参数，则创建的清单会将此设置指定为空数组。 除非编辑清单，否则不会导出模块中的函数。

当 FunctionsToExport 设置为仅包含 Get-Example 函数，仅导入此模块时，即使根模块或任何嵌套模块导出了其他函数，也只能使用 Get-Example 函数。

@{
    FunctionsToExport = @(
        'Get-Example'
    )
}

当使用通配符字符串设置 FunctionsToExport，导入此模块时，名称以 Example 结尾的任何函数都将可用，即使根模块或任何嵌套模块将其他函数导出为模块成员也是如此。

@{
    FunctionsToExport = @(
        '*Example'
    )
}

CmdletsToExport

此设置指定模块导出的 cmdlet。 可以使用此设置来限制由模块导出的 cmdlet。 它可以从导出的模块成员列表中移除 cmdlet，但不能将 cmdlet 添加到该列表中。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 是

可以使用通配符在此设置中指定条目。 导出的 cmdlet 列表中的所有匹配 cmdlet 都会得到导出。

提示

为了获得性能和可发现性，应始终显式列出希望模块在此设置中导出的 cmdlet，而无需使用任何通配符。

例如，导入带有注释禁止设置的模块时，将导出根模块中的所有 cmdlet 和任何嵌套模块。

@{
    # CmdletsToExport = @()
}

此清单在功能上等同于完全不指定设置。

@{
    CmdletsToExport = '*'
}

当 FunctionsToExport 设置为空数组，导入此模块时，cmdlet、根模块或任何嵌套模块导出都不可用。

@{
    CmdletsToExport = @()
}

注意

如果使用 New-ModuleManifest 命令创建模块清单，并且未指定 CmdletsToExport 参数，则创建的清单会将此设置指定为空数组。 除非编辑清单，否则不会导出模块中的 cmdlet。

当 CmdletsToExport 设置为仅包含 Get-Example cmdlet，仅导入此模块时，即使根模块或任何嵌套模块导出了其他 cmdlet，也只能使用 Get-Example cmdlet。

@{
    CmdletsToExport = @(
        'Get-Example'
    )
}

当使用通配符字符串设置 cmdletToExport，导入此模块时，名称以 Example 结尾的任何 cmdlet 都将可用，即使根模块或任何嵌套模块将其他 cmdlet 导出为模块成员也是如此。

@{
    CmdletsToExport = @(
        '*Example'
    )
}

VariablesToExport

此设置指定模块导出的变量。 可以使用此设置来限制由模块导出的变量。 它可以从导出的模块成员列表中删除变量，但不能将变量添加到该列表中。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 是

可以使用通配符在此设置中指定条目。 导出的模块成员列表中的所有匹配变量都会得到导出。

提示

为了获得性能和可发现性，应始终显式列出希望模块在此设置中导出的变量，而无需使用任何通配符。

例如，导入带有注释禁止设置的模块时，将导出根模块中的所有变量和任何嵌套模块。

@{
    # VariablesToExport = @()
}

此清单在功能上等同于完全不指定设置。

@{
    VariablesToExport = '*'
}

注意

如果使用 New-ModuleManifest 命令创建模块清单，并且未指定 VariablesToExport 参数，则创建的清单会将此设置指定为 '*'。 除非编辑清单，否则将导出模块中的所有变量。

当 VariablesToExport 设置为空数组，导入此模块时，变量、根模块或任何嵌套模块导出都不可用。

@{
    VariablesToExport = @()
}

当 VariablesToExport 设置为仅包含 SomeExample 变量，仅导入此模块时，即使根模块或任何嵌套模块导出了其他变量，也只能使用 $SomeExample 变量。

@{
    VariablesToExport = @(
        'SomeExample'
    )
}

当使用通配符字符串设置 VariablesToExport，导入此模块时，名称以 Example 结尾的任何变量都将可用，即使根模块或任何嵌套模块将其他变量导出为模块成员也是如此。

@{
    VariablesToExport = @(
        '*Example'
    )
}

DscResourcesToExport

此设置指定模块导出的 DSC 资源。 可以使用此设置来限制模块导出的基于类的 DSC 资源。 它可以从导出的模块成员列表中删除 DSC 资源，但无法将 DSC 资源添加到列表中。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 是

可以使用通配符在此设置中指定条目。 将导出模块中所有匹配的基于类的 DSC 资源。

提示

为了便于发现，应始终显式列出模块导出的所有 DSC 资源。

有关创作和使用 DSC 资源的详细信息，请参阅 DSC 的文档。

此清单导出根模块和任何嵌套模块中定义的所有基于类和基于 MOF 的 DSC 资源。

@{
    # DscResourcesToExport = @()
}

此清单导出根模块和任何嵌套模块中定义的所有基于 MOF 的 DSC 资源，但仅导出一个基于类的 DSC 资源 ExampleClassResource。

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
    )
}

此清单导出它包含的所有 DSC 资源。 即使未列出基于 MOF 的资源，模块仍会将其导出。

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
        'ExampleMofResourceFirst'
    )
}

ModuleList

此设置是一份信息清单，列出了其中包含的模块。 此列表不会影响模块的行为。

值
输入类型 %>
必需 否
值（如果未设置） $null
接受通配符 否

此设置的条目可以是模块名称、完整的模块规范或模块或脚本文件的路径。

如果该值是路径，则可以是完全限定路径或相对路径。

当该值为模块名称或模块规范时，PowerShell 会在 PSModulePath 中搜索指定的模块。

模块规范是具有以下键的哈希表。

  • ModuleName - 必需。 指定模块名称。
  • GUID - 可选。 指定模块的 GUID。
  • 它还必需指定以下三个键中的至少一个。 RequiredVersion 键不能与 ModuleVersion 或 MaximumVersion 键一起使用。 可以通过同时指定 ModuleVersion 和 MaximumVersion 键来定义模块的可接受版本范围。
    • ModuleVersion - 指定模块的最低可接受版本。
    • RequiredVersion - 指定模块所需的准确版本。
    • MaximumVersion - 指定模块的最高可接受版本。

注意

Windows PowerShell 5.0 中添加了 RequiredVersion。 已在 Windows PowerShell 5.1 中添加 MaximumVersion。

此清单不提供其包含模块的信息列表。 它可以具有模块，也可能没有模块。 即使未指定此设置，RootModule、ScriptsToProcess 或 NestedModules 设置中列出的任何模块仍然正常运行。

@{
    # ModuleList = @()
}

此清单声明它包含的唯一模块是 Example.psm1 和 Submodules 文件夹中的子模块 First.psm1 和 Second.psm1。

@{
    ModuleList = @(
        'Example.psm1'
        'Submodules\First.psm1'
        'Submodules\Second.psm1'
    )
}

文件列表

此设置是一份信息清单，列出了此模块包含的文件。 此列表不会影响模块的行为。

值
输入类型 System.String[]
必需 否
值（如果未设置） $null
接受通配符 是

此设置的条目应是包含模块清单的文件夹的文件的相对路径。

当用户对定义此设置的清单调用 Get-Module 时，FileList 属性会包含这些文件的完整路径，将模块的路径与每个条目的相对路径联接在一起。

此清单不包含其文件的列表。

@{
    # FileList = @()
}

此清单声明它包含的唯一文件列在此设置中。

@{
    FileList = @(
        'Example.psd1'
        'Example.psm1'
        'Assemblies\Example.dll'
        'Scripts\Initialize.ps1'
        'Submodules\First.psm1'
        'Submodules\Second.psm1'
    )
}

PrivateData

此设置定义可用于根模块范围中的任何命令或函数的哈希表。

值
输入类型 System.Collections.Hashtable
必需 PowerShell 库，Crescendo
值（如果未设置） $null
接受通配符 否

导出 Crescendo 清单以创建新模块时，Export-CrescendoModule 会将两个键添加到 PrivateData

  • CrescendoGenerated - 导出模块时的时间戳
  • CrescendoVersion - 用于导出模块的 Crescendo 版本

可以添加自己的键来保存要跟踪的元数据。添加到此设置的任何键都可用于根模块中使用 $MyInvocation.MyCommand.Module.PrivateData 的函数和 cmdlet。 哈希表在模块范围本身中不可用，仅在模块中定义的 cmdlet 中可用。

例如，此清单定义 PrivateData 中的 PublishedDate 键。

@{
    PrivateData = @{
        PublishedDate = '2022-06-01'
    }
}

模块中的 Cmdlet 可以使用 $MyInvocation 变量访问此值。

Function Get-Stale {
    [CmdletBinding()]
    param()

    $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate
    $CurrentDate = Get-Date

    try {
        $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop
    } catch {
        # The date was set in the manifest, set to an invalid value, or
        # the script module was directly imported without the manifest.
        Throw "Unable to determine published date. Check the module manifest."
    }

    if ($CurrentDate -gt $PublishedDate.AddDays(30)) {
        Write-Warning "This module version was published more than 30 days ago."
    } else {
        $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate
        "This module will be stale in $($TimeUntilStale.Days) days"
    }
}

导入模块后，该函数使用 PrivateData 中的值来确定模块的发布时间。

Get-Stale -TestDate '2022-06-15'
Get-Stale -TestDate '2022-08-01'

This module will be stale in 16 days

WARNING: This module version was published more than 30 days ago.

PrivateData.PSData

PSData 子属性定义支持特定扩展方案的值的哈希表。

值
输入类型 System.Collections.Hashtable
必需 PowerShell 库，实验功能，Crescendo 模块
值（如果未设置） $null
接受通配符 否

PSData 子属性用于以下场景：

  • PowerShell 库 - 使用 New-ModuleManifest 创建模块清单时，cmdlet 会预先填充 PSData 哈希表，以及将模块发布到 PowerShell 库时所需的占位键。 有关模块清单和发布到 PowerShell 库的详细信息，请参阅 影响 PowerShell 库 UI 的程序包清单值。
  • Crescendo 模块 - 导出 Crescendo 清单以创建新模块时，Export-CrescendoModule 会向 PSData.Tags 属性添加值 CrescendoBuilt。 可以使用此标记在使用 Crescendo 创建的 PowerShell 库中查找模块。 有关详细信息，请参阅 Export-CrescendoModule。

HelpInfoURI

此设置指定模块的 HelpInfo XML 文件的 Internet 地址。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

此设置的值必须为以 http 或 https 开头的统一资源标识符 (URI)。

HelpInfo XML 文件支持在 PowerShell 3.0 中引入的“可更新帮助”功能。 它包含有关该模块的可下载帮助文件的位置，以及每个支持的区域设置的最新帮助文件的版本号的信息。

有关可更新的帮助的信息，请参阅 about_Updatable_Help。 有关 HelpInfo XML 文件的信息，请参阅支持可更新的帮助。

例如，此模块支持可更新的帮助。

@{
    HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603'
}

DefaultCommandPrefix

此设置指定将模块中的所有命令导入会话中时在其名词前预置的前缀。 前缀有助于防止用户会话中的命令名称发生冲突。

值
输入类型 System.String
必需 否
值（如果未设置） $null
接受通配符 否

模块用户可以通过指定 Import-Module cmdlet 的 Prefix 参数来替代此前缀。

此设置在 PowerShell 3.0 中引入。

导入此清单时，从该模块导入的任何 cmdlet 都会在其名称的名次前加上 Example。 例如，Get-Item 会作为 Get-ExampleItem 导入。

@{
    DefaultCommandPrefix = 'Example'
}

另请参阅