25、创建首个 PowerShell 模块：从基础到高级应用

最新推荐文章于 2025-09-29 07:52:45 发布

会议雕塑

最新推荐文章于 2025-09-29 07:52:45 发布

阅读量31

点赞数

CC 4.0 BY-SA版权

分类专栏： PowerShell 7实战指南文章标签： PowerShell模块脚本转换嵌套模块

本文链接：https://blog.youkuaiyun.com/pandas7gardener/article/details/151862276

PowerShell 7实战指南专栏收录该内容

34 篇文章 ¥499.90

订阅专栏¥69.90

会员秒杀 ¥9.9 重磅福利

超级会员免费看

创建首个 PowerShell 模块：从基础到高级应用

1. 将脚本转换为模块

模块允许我们控制从代码中导出的函数和变量，并将它们作为一个组进行管理。将脚本转换为模块的基本过程是将文件扩展名从 .ps1 更改为 .psm1 。

例如，将之前编写的 Write-Message.ps1 脚本复制一份并保存为 Write-Message.psm1 。然后，打开一个新会话，使用以下命令将模块导入会话：

Import-Module C:\temp\poshbook\ch11\Write-Message.psm1

2. 编写简单模块

导入模块后，我们可以查看模块的详细信息。使用以下命令：

Get-Module Write-Message
Get-Module Write-Message | Format-List

通过这些命令，我们可以看到脚本模块、其位置以及导出的命令。还可以使用 Get-Command 检查 Write-Message 函数的详细信息，确认其来源是 Write-Message 模块。

接下来，我们可以在模块文件中添加新的函数：

function setMessage {
    Write-Output "$text"
}

使用 -Force 参数重新导入模块，这样模块中就有了两个函数。再次运行 Get-Module ，可以看到这两个函数都可见。

如果不想让 setMessage 函数被外部使用，可以使用 Export-ModuleMember 命令控制导出的函数。在 Write-Message.psm1 文件底部添加以下行：

Export-ModuleMember -Function Write-Message

然后使用 -Force 参数重新导入模块，此时只有 Write-Message 函数被导出，尝试运行 setMessage 会出错。此外， Export-ModuleMember 还可以用于导出变量和别名：

Export-ModuleMember -variable $MyVariable

3. 嵌套模块

为了避免在每个脚本中重复编写相同的函数，我们可以将一些常用函数封装在模块中。例如，将之前编写的 Write-Log.ps1 脚本复制到一个名为 Write-Log.psm1 的模块文件中，并编辑该文件，移除以下行：

Write-Log "Is this thing on?"

然后在 Write-Message.psm1 模块中添加几行代码，以调用 Write-Log 模块并运行其中的函数：

Import-Module "C:\temp\poshbook\ch11\write-log.psm1"
$text = "default message"
function Write-Message($text) {
    Write-Output "$text"
    Write-Log "$text"
}
function setMessage {
    Write-Output "$text"
}

导入 Write-Message 模块后，通过 Get-Module 的输出可以看到有四个导出的函数，其中两个来自 Write-Message 模块，两个来自 Write-Log 模块，并且 Write-Log 模块是嵌套的。嵌套模块只能被调用模块访问，直接使用 Get-Command 或 Get-Module Write-Log 可能看不到加载的函数，但检查创建的日志文件可以确认其正常工作。

如果不想让嵌套模块隐藏，可以使用 Import-Module 的 -Global 参数：

Import-Module -Global "C:\temp\poshbook\ch11\write-log.psm1"

4. 更多类型的模块

4.1 二进制模块

在模块中创建的函数虽然使用起来像 cmdlet，但实际上仍然是函数。要编写自定义 cmdlet，需要编写二进制模块。PowerShell 基于 .NET，是一种解释型语言，通常用 C# 等编译型语言编写。

二进制模块没有 .psm1 扩展名，而是一个从 C# 等代码编译而来的 .NET 程序集，具有 .dll 扩展名。可以通过以下方式创建二进制模块：

$code = @"
using System.Management.Automation;
namespace SendMessage
{
    [Cmdlet(VerbsCommunications.Send, "Message")]
    public class SendMessageCommand : Cmdlet
    {
        [Parameter(Mandatory = true)]
        public string Name { get; set; }
        protected override void ProcessRecord()
        {
            WriteObject(Name + " loves PowerShell!");
        }
    }
}
"@
Add-Type -TypeDefinition $Code -OutputAssembly c:\temp\MyBinaryModule.dll

使用 Import-Module 导入二进制模块：

Import-Module c:\temp\MyBinaryModule.dll

运行 Get-Module 可以看到模块类型为 Binary ，并且导出的是 cmdlet 而不是函数。二进制模块加载到会话后不能卸载，如果需要修改，必须先关闭 PowerShell。

4.2 CDXML 模块和 PowerShell SnapIns

CDXML 是 Common Information Model 命令的 XML 包装器，以前常用于 Windows 管理模块，但现在已基本被弃用，因为这种方式编写的模块加载和运行速度比脚本模块慢。PowerShell SnapIns 也是 Windows PowerShell 的弃用形式，在 PowerShell 7 中不受支持，无需关注。

4.3 清单模块

脚本模块通常是单一的整体文件，适合个人使用，但在生产环境中，可能需要将函数拆分为单独的文件，并包含版本信息和其他元数据及资源。为了组织更复杂的模块，需要一个模块清单，它是一个保存为 .psd1 扩展名的哈希表。

例如，浏览 PowerShellGet 模块，可以看到它包含多个文件和文件夹，其中 PowerShellGet.psd1 是模块清单。清单文件中的键分为三组，涵盖以下方面：
- 生产数据 ：包括作者、编写时间、适用对象以及运行的系统类型。
- 模块构建 ：大致分为加载内容和导出内容，涉及嵌套模块的加载、格式化信息、类型信息和程序集，还定义了导出的函数、变量和别名。 RootModule 定义了调用其他所有内容的主模块文件（即主 .psm1 文件）。
- 模块内容 ：列出模块中包含的所有模块、文件和其他资产。这些键是可选的，但通常应准确填充。

可以使用 New-ModuleManifest 命令创建新的清单文件：

New-ModuleManifest -Path 'C:\temp\newmodule\newmodule.psd1' -ModuleVersion '1.0.0'

也可以直接在文本编辑器或 VS Code 中编辑清单文件，但编辑后最好使用 Test-ModuleManifest 命令进行测试：

Test-ModuleManifest -Path 'C:\temp\newmodule\newmodule.psd1'

5. 使用 Plaster 等脚手架工具

如果长期开发模块或与他人协作，使用框架将所有内容拆分为单独的文件和资产是个好主意，这就是脚手架工具的用武之地。Plaster 是一个不错的选择，它最初由 Microsoft 开发，现在由 PowerShell.Org 维护。

Plaster 使用模板文件，该文件由清单（类似于模块清单）和一组内容文件及目录组成。模板用 XML 编写，高度可定制。清单有三个部分：
- 元数据 ：包含模板的名称、版本和作者等信息。
- 参数：定义用户可以对模块结构做出的选择，例如创建和包含哪些文件和文件夹。
- 内容：指定 Plaster 将执行的操作，如复制文件、修改文件以及检查所需模块是否安装。

安装和使用 Plaster 的步骤如下：
1. 从 PowerShell 库安装模块：

Install-Module Plaster

导入模块：

Import-Module Plaster

查看可用的模板：

Get-PlasterTemplate

复制 NewPowerShellScriptModule 的路径，然后运行 Plaster 脚手架工具：

Invoke-Plaster

运行 Invoke-Plaster 时，需要提供默认模板的路径和目标路径（必须是文件夹），还需要提供模块的名称和版本，以及是否将 VS Code 设置为默认编辑器。

使用 Plaster 创建的模块包含脚本模块文件、模块清单文件、测试脚本文件夹和 VS Code 设置文件夹。生成的模块文件有一个特点：如果文件中的函数使用标准的 cmdlet 命名约定（如 Verb-Noun），则会被导出；否则不会被导出。

以下是创建模块的流程总结：

graph LR
    A[将脚本转换为模块] --> B[编写简单模块]
    B --> C[嵌套模块]
    C --> D[更多类型的模块]
    D --> E[使用脚手架工具]

通过以上步骤和方法，我们可以创建、管理和扩展各种类型的 PowerShell 模块，提高代码的复用性和可维护性。无论是个人项目还是团队协作，合理使用模块都能带来显著的效率提升。

创建首个 PowerShell 模块：从基础到高级应用

6. 各类型模块特点对比

为了更清晰地了解不同类型模块的特点，我们可以通过以下表格进行对比：
| 模块类型 | 扩展名 | 加载与运行速度 | 可卸载性 | 适用场景 |
| — | — | — | — | — |
| 脚本模块 | .psm1 | 较快 | 可卸载 | 个人使用、简单功能实现 |
| 二进制模块 | .dll | 快 | 不可卸载 | 编写自定义 cmdlet |
| CDXML 模块 | - | 慢 | - | 已基本弃用 |
| PowerShell SnapIns | - | - | - | 已弃用 |
| 清单模块 | .psd1 | - | - | 生产环境，复杂模块管理 |

7. 模块开发的注意事项

在开发 PowerShell 模块时，有一些注意事项需要我们牢记：
- 命名规范 ：函数和 cmdlet 应遵循标准的命名约定，如 Verb-Noun，这样不仅便于理解和使用，还能确保在使用某些工具（如 Plaster）时能正确导出。
- 版本管理 ：使用清单模块时，要合理设置版本信息，方便后续的更新和维护。可以在创建清单时指定版本号，如 New-ModuleManifest -Path 'C:\temp\newmodule\newmodule.psd1' -ModuleVersion '1.0.0' 。
- 错误处理 ：在模块中添加适当的错误处理机制，提高代码的健壮性。例如，在调用嵌套模块或执行关键操作时，捕获可能出现的异常并进行处理。
- 测试：使用像 Pester 这样的测试框架进行单元测试和测试驱动开发，确保模块的功能正确性。虽然 Pester 的详细使用超出了本文范围，但它是模块开发中不可或缺的一部分。

8. 模块的调试与优化

当模块出现问题时，我们需要进行调试。以下是一些调试和优化的方法：
- 输出调试信息 ：在函数中添加 Write-Debug 语句，输出详细的调试信息。例如：

function Write-Message($text) {
    Write-Debug "Entering Write-Message with text: $text"
    Write-Output "$text"
    Write-Debug "Exiting Write-Message"
}

然后在 PowerShell 会话中设置 $DebugPreference = "Continue" ，即可看到调试信息。
- 性能分析 ：使用 Measure-Command 来测量函数的执行时间，找出性能瓶颈。例如：

Measure-Command { Write-Message "Test message" }

根据分析结果，对代码进行优化，如减少不必要的循环、使用更高效的算法等。

9. 模块的发布与共享

如果我们开发的模块具有一定的通用性和实用性，可以将其发布和共享。以下是基本的步骤：
1. 打包模块 ：确保模块的所有文件和资源都包含在一个目录中，并且有正确的模块清单。
2. 注册存储库 ：如果要发布到 PowerShell 库，需要先注册存储库。可以使用以下命令：

Register-PSRepository -Name MyRepo -SourceLocation https://example.com/repo -InstallationPolicy Trusted

发布模块 ：使用 Publish-Module 命令将模块发布到指定的存储库。例如：

Publish-Module -Path C:\path\to\module -Repository MyRepo

10. 总结与展望

本文详细介绍了 PowerShell 模块的创建、管理和扩展，从将脚本转换为模块开始，逐步深入到嵌套模块、不同类型模块的使用，以及如何利用脚手架工具提高开发效率。通过合理使用模块，我们可以提高代码的复用性和可维护性，无论是个人开发者还是团队协作，都能从中受益。

未来，随着 PowerShell 的不断发展，模块的功能和应用场景可能会进一步扩展。例如，可能会有更多的工具和框架支持模块的开发和管理，也可能会出现新的模块类型以满足不同的需求。我们需要持续关注 PowerShell 的发展动态，不断学习和掌握新的技术，以更好地应对各种挑战。

以下是模块开发过程中涉及的关键操作步骤总结：

graph LR
    A[模块开发] --> B[创建模块]
    B --> B1[脚本转模块]
    B --> B2[编写简单模块]
    B --> B3[嵌套模块]
    B --> B4[选择模块类型]
    A --> C[调试优化]
    C --> C1[输出调试信息]
    C --> C2[性能分析]
    A --> D[发布共享]
    D --> D1[打包模块]
    D --> D2[注册存储库]
    D --> D3[发布模块]

通过遵循以上步骤和方法，我们可以更加高效地开发和管理 PowerShell 模块，为自动化任务和系统管理提供强大的支持。