关于模块清单

简短描述

描述编写模块清单文件的设置和实践。

详细描述

模块清单是包含哈希表的 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

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

清单设置

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

• 输入类型：您可以在清单中为此设置指定的对象类型。
• 必需：如果此值为是，则导入模块并将其发布到 PowerShell 库都需要该设置。如果为否，则两者都不需要。如果是 PowerShell Gallery，则仅在发布到 PowerShell Gallery 时需要它。
• 未设置时的值：此设置在导入且未明确设置时具有的值。
• 接受通配符：此设置是否可以采用通配符值。

RootModule

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

系统字符串

不

$null

不

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

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

该路径应该相对于模块清单。

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

• .ps1 或 .psm1 文件使模块类型为脚本
• .psd1 文件使模块类型为 Manifest
• .dll 文件使模块类型为Binary
• .cdxml 文件使模块类型为 CIM
• .xaml 文件使模块类型为Workflow

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

有用的提示

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

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

@{
    RootModule = ''
}

笔记

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

ModuleVersion

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

系统字符串

是的

None

不

当您运行 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

兼容的 PS 版本

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

系统.String[]

桌面、核心

不

$null

不

如果此设置的值为 $null，则无论会话的 PSEdition 为何，都可以导入模块。您可以将其设置为一个或多个可接受的值。

有关 PSEdition 的信息，请参阅：

• about_PowerShell_版本
• 具有兼容 PowerShell 版本的模块。

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

笔记

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

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

@{
    # CompatiblePSEditions = @()
}

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

@{
    CompatiblePSEditions = @('Core')
}

GUID

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

系统字符串

不

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'
}

作者

此设置标识模块作者。

系统字符串

PowerShell 画廊

$null

不

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

@{
    Author = 'Contoso Developer Experience Team'
}

CompanyName

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

系统字符串

不

$null

不

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

@{
    CompanyName = 'Contoso, Ltd.'
}

版权

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

系统字符串

不

$null

不

本清单声明了一份版权声明，保留自 2022 年起 Contoso, Ltd. 的所有权利。

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

描述

此设置在较高级别上描述了模块。

系统字符串

PowerShell 画廊

$null

不

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

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

PowerShell版本

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

系统字符串

不

$null

不

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

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

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

@{
    # PowerShellVersion = ''
}

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

@{
    PowerShellVersion = '7.2'
}

PowerShell主机名

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

系统字符串

不

$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'
}

PowerShell主机版本

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

系统字符串

不

$null

不

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

警告

虽然可以在没有 PowerShellHostName 设置的情况下使用此设置，但它会增加出现意外行为的可能性。仅当您同时使用 PowerShellHostName 设置时才使用此设置。

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

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

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

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

DotNetFramework版本

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

系统字符串

不

$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 后，您可以在 Microsoft .NET Framework 的最新可用版本至少为 4.0 的任何 Windows PowerShell 会话中导入此模块。您还可以在任何 PowerShell 会话中导入它。

@{
    DotNetFrameworkVersion = '4.0'
}

CLR版本

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

系统字符串

不

$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 后，您可以在 CLR 的最新可用版本至少为 4.0 的任何 Windows PowerShell 会话中导入此模块。您还可以在任何 PowerShell 会话中导入它。

@{
    CLRVersion = '4.0'
}

ProcessorArchitecture

此设置指定模块所需的处理器架构。

系统字符串

无、MSIL、X86、IA64、Amd64、Arm

不

无

不

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

例如，此清单声明其模块可以在任何会话中导入，无论系统的处理器架构如何。

@{
    # ProcessorArchitecture = ''
}

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

@{
    ProcessorArchitecture = 'Amd64'
}

RequiredModules

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

System.String[]、System.Collections.Hashtable[]

不

$null

不

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

当该值是路径时，该路径可以是完全限定的或相对的。

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

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

• 模块名称 - 必需。指定模块名称。
• 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 键的值中指定的模块文件之前加载指定的程序集。

系统.String[]

不

$null

不

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

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

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

待处理脚本

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

系统.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.

处理类型

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

系统.String[]

不

$null

不

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

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

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

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

处理格式

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

系统.String[]

不

$null

不

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

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

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

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

NestedModules

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

System.String[]、System.Collections.Hashtable[]

不

$null

不

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

当该值是路径时，该路径可以是完全限定的或相对的。

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

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

• 模块名称 - 必需。指定模块名称。
• GUID - 可选。指定模块的 GUID。

• 还必需至少指定以下三个键之一。 RequiredVersion 键不能与 ModuleVersion 或 MaximumVersion 键一起使用。您可以通过同时指定 ModuleVersion 和 MaximumVersion 键来定义模块可接受的版本范围。

  • ModuleVersion - 指定模块的最低可接受版本。
• RequiredVersion - 指定模块的准确、必需的版本。
• MaximumVersion - 指定模块可接受的最大版本。

笔记

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

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

• 导出函数
• CmdletToExport
• 要导出的变量
• 导出别名

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

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

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

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

导出函数

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

系统.String[]

不

$null

是的

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

有用的提示

为了性能和可发现性，您应该始终明确列出您希望模块在此设置中导出的函数，而不使用任何通配符。

例如，当您导入注释掉设置的模块时，根模块和任何嵌套模块中的所有函数都会被导出。

@{
    # FunctionsToExport = @()
}

此清单在功能上与根本不指定设置相同。

@{
    FunctionsToExport = '*'
}

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

@{
    FunctionsToExport = @()
}

笔记

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

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

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

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

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

导出的 Cmdlet

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

系统.String[]

不

$null

是的

您可以使用通配符指定此设置中的条目。导出的 cmdlet 列表中的所有匹配 cmdlet 均已导出。

有用的提示

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

例如，当您导入注释掉此设置的模块时，将导出根模块和任何嵌套模块中的所有 cmdlet。

@{
    # CmdletsToExport = @()
}

此清单在功能上与根本不指定设置相同。

@{
    CmdletsToExport = '*'
}

将 CmdletsToExport 设置为空数组后，导入此模块时，根模块或任何嵌套模块导出的 cmdlet 均不可用。

@{
    CmdletsToExport = @()
}

笔记

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

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

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

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

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

要导出的变量

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

系统.String[]

不

$null

是的

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

有用的提示

为了性能和可发现性，您应该始终明确列出您希望模块在此设置中导出的变量，而不使用任何通配符。

例如，当您导入注释掉此设置的模块时，根模块和任何嵌套模块中的所有变量都会被导出。

@{
    # VariablesToExport = @()
}

此清单在功能上与根本不指定设置相同。

@{
    VariablesToExport = '*'
}

笔记

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

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

@{
    VariablesToExport = @()
}

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

@{
    VariablesToExport = @(
        'SomeExample'
    )
}

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

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

Dsc资源导出

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

系统.String[]

不

$null

是的

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

有用的提示

为了可发现性，您应该始终明确列出模块导出的所有 DSC 资源。

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

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

@{
    # DscResourcesToExport = @()
}

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

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
    )
}

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

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

ModuleList

此设置是此设置中包含的模块的信息清单列表。该列表不会影响模块的行为。

System.String[]、System.Collections.Hashtable[]

不

$null

不

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

当该值是路径时，该路径可以是完全限定的或相对的。

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

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

• 模块名称 - 必需。指定模块名称。
• 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'
    )
}

FileList

此设置是此模块中包含的文件的信息清单列表。该列表不会影响模块的行为。

系统.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 画廊，渐强

$null

不

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

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

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

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

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

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

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.

私有数据.PSData

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

System.Collections.Hashtable

PowerShell 库、实验功能、Crescendo 模块

$null

不

PSData 子属性用于以下场景：

• PowerShell 库 - 当您使用 New-ModuleManifest 创建模块清单时，cmdlet 会使用将模块发布到 PowerShell 库时所需的占位符键预填充 PSData 哈希表。有关模块清单和发布到 PowerShell 库的详细信息，请参阅影响 PowerShell 库 UI 的包清单值。
• 实验功能 - 有关实验功能的元数据保存在 PSData 的 ExperimentalFeatures 属性中。 ExperimentalFeatures 属性是一个哈希表数组，其中包含功能的名称和描述。有关更多信息，请参阅在模块中声明实验性功能。
• Crescendo 模块 - 当您导出 Crescendo 清单以创建新模块时，Export-CrescendoModule 会将值 CrescendoBuilt 添加到 PSData.Tags 属性。您可以使用此标签在 PowerShell 库中查找使用 Crescendo 创建的模块。有关详细信息，请参阅导出 CrescendoModule。

帮助信息URI

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

系统字符串

不

$null

不

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

HelpInfo XML 文件支持 PowerShell 3.0 中引入的可更新帮助功能。它包含有关模块的可下载帮助文件的位置以及每个受支持的语言环境的最新帮助文件的版本号的信息。

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

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

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

默认命令前缀

此设置指定一个前缀，当模块中的所有命令导入到会话中时，该前缀将添加到这些命令的名词前面。前缀有助于防止用户会话中的命令名称冲突。

系统字符串

不

$null

不

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

此设置是在 PowerShell 3.0 中引入的。

导入此清单后，从此模块导入的任何 cmdlet 都会在其名称中的名词前面添加 Example。例如，Get-Item 将作为 Get-ExampleItem 导入。

@{
    DefaultCommandPrefix = 'Example'
}

参见

• about_PowerShell_版本
• New-ModuleManifest
• Test-ModuleManifest
• 具有兼容 PowerShell 版本的模块
• 影响 PowerShell 库 UI 的包清单值
• PowerShell 模块创作注意事项