24、深入探索 PowerShell 错误处理、调试与模块创建

深入探索 PowerShell 错误处理、调试与模块创建

1. 错误处理基础

PowerShell 中的错误分为终止性错误和非终止性错误，这是它与许多编程语言不同的地方，这一特性源于它是基于 .NET 的解释型语言。
- 错误处理方式 ：可以使用 $ErrorActionPreference 变量和 -ErrorAction 参数来处理错误。为了使用常见的错误捕获方式 Try/Catch/Finally 语句，需要将错误转换为终止性错误。
- 自定义错误处理 ： Try/Catch/Finally 语句可用于提供自定义的错误处理例程。
- 手动抛出错误 ：当遇到不理想但不会自然引发错误的情况时，可以使用 Throw 语句生成自己的终止性错误。

2. 调试技巧

2.1 使用 Write - Debug 进行脚本检测

可以使用 Write - Debug 结合 -Debug 参数来访问调试输出流，从而深入了解代码的执行情况。

2.2 交互式调试

• PowerShell 内置调试器 ：可以使用 Set - PSBreakPoint 等调试 cmdlet 来访问 PowerShell 内置的调试器。
• VS Code 调试 ：使用 VS Code 进行交互式调试更加方便和强大。在 VS Code 中，有以下几个重要的调试区域：
  • 变量查看 ：在 Write - Item 函数中，有变量 $i 、 $str 和 $itemCount 。将鼠标悬停在变量上可以查看其类型。点击 Command 左侧的箭头，可以查看自动变量，如 $args 和 $MyInvocation 。展开 $PSBoundParameters 可以看到与 Write - Item 关联的参数 [itemCount] 。 Local 、 Script 和 Global 显示各个作用域中所有参数的值，例如 $i 变量存在于局部作用域，但不在脚本或全局作用域中。
  • 调用栈 ：调用栈遵循后进先出（LIFO）原则。可以看到执行流程从交互式会话开始，调用脚本 <ScriptBlock> ，该脚本运行到第 28 行调用 Do - Work 函数， Do - Work 函数运行到第 24 行调用 Write - Item 函数，最终运行到第 15 行的断点。点击调用栈中的项目，可以看到顶部窗格中的变量值会根据相应作用域进行更新。
  • 监视区域 ：在中间窗格的 WATCH 区域，可以添加想要随时了解其值的变量或表达式。操作步骤如下：
    1. 将鼠标悬停在 WATCH 窗格上，点击出现的 + 按钮。
    2. 在出现的文本框中输入 $i*2 并按 Enter ，此时表达式计算结果为 4。
    3. 按下 Continue 按钮或 F5 ，脚本继续运行直到再次遇到断点，此时表达式计算结果变为 6。

3. PowerShell 模块概述

模块是一种方便的方式来分发 PowerShell 代码，它可以实现代码的重用和自动化。模块主要有以下三个基本功能：
- 环境配置 ：提供可重复的自定义工作环境，例如 Exchange 的 PowerShell 模块可以配置 PowerShell 环境以特定方式与 Exchange 协作。
- 代码重用 ：提供函数库，供我们或他人使用，如数学模块。
- 解决方案工程 ：由于模块可以嵌套在其他模块中，因此可以分发一组模块来创建应用程序，这在 Windows 管理环境中很常见。

4. 模块位置

模块有三个默认位置，不同操作系统的位置有所不同，具体如下表所示：
| 操作系统 | 系统位置 | 所有用户位置 | 用户位置 |
| — | — | — | — |
| Windows | PowerShell 7 无，Windows PowerShell 使用 C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\ | C:\Program Files\PowerShell\Modules
C:\Program Files\PowerShell\7\Modules | C:\Users\<user name>\Documents\PowerShell\Modules |
| Linux | /opt/Microsoft/PowerShell/7/Modules | /usr/local/share/PowerShell/Modules | /home/<username>/.local/share/PowerShell/Modules |

系统位置通常用于 Microsoft 模块，用户位置在 Windows 中默认不存在，需要手动创建。所有用户位置是在 PowerShell v4 中引入的，用于非 Microsoft 模块，从 PowerShell 库下载的模块默认安装在此处。可以通过操作 $ENV:PSModulePath 变量来添加模块安装位置，Windows 中使用分号 ; 分隔，Linux 中使用冒号 : 分隔。

5. 模块加载方式

5.1 自动加载

在某些情况下，模块可以自动加载。当模块位于 $env:PSModulePath 定义的正确命名文件夹中时，PowerShell 会自动发现它们。自动加载的方式有：
- 运行模块中的 cmdlet。
- 使用 Get - Command 获取模块中的 cmdlet。
- 使用 Get - Help 获取模块中的 cmdlet。
不过，在脚本中不建议依赖自动加载，推荐使用 using 关键字来加载模块，例如：

using module ActiveDirectory

5.2 手动加载

自动加载虽然方便，但缺乏控制，可能会加载不需要的内容，并且无法控制加载的模块版本，还可能消耗大量内存。因此，可以使用 Import - Module cmdlet 手动加载模块，该 cmdlet 提供了多个选项来控制加载的方式和内容：
- -Name ：指定要导入的模块名称，如果模块不在 $ENV:PSModulePath 指定的路径中，还可以包含路径。
- -Cmdlet ：从字符串数组中导入部分 cmdlet。类似的参数还有 -Alias 、 -Function 和 -Variable 。
- -Force ：强制模块完全重新加载。默认情况下，如果模块已经加载， Import - Module 不会重新导入。
- -RequiredVersion ：指定要导入的模块版本。
- -Prefix ：为从模块导入的 cmdlet 中的名词添加前缀，以避免与会话中已存在的 cmdlet 冲突。
- -NoClobber ：如果要导入的 cmdlet 与会话中已存在的 cmdlet 同名，则阻止导入。

可以使用 Remove - Module cmdlet 卸载模块。当首次导入模块时，会导入其所需的所有嵌套模块，但使用 Import - Module - Force 重新加载模块时，只会重新加载指定的模块，而不会重新加载嵌套模块， Remove - Module 会同时移除嵌套模块。在实际操作中，重新启动一个新会话通常更快捷和干净。

6. 简单模块的创建

6.1 基本模块结构

一个最简单的模块是包含函数的脚本文件，保存为 .psm1 扩展名。例如，将以下代码保存为 .psm1 文件，放在 \users\<username>\documents\powershell\modules 文件夹（Linux 为 /home/<user>/.local/share/powershell/Modules 文件夹）中与文件名相同的文件夹内：

function Get - Square($a) {
    $result = $a * $a
    return $result
}

6.2 模块使用

在 PowerShell 会话中，可以使用以下命令加载模块：

Import - Module <ModuleName>

加载后，就可以使用模块中的函数。运行 Remove - Module 后，函数将不再可用。

7. 点源法的注意事项

在 PowerShell 的早期版本中，唯一将一个脚本中的函数包含到另一个脚本中的方法是点源法。例如，创建一个 Dot - Source.ps1 脚本，内容为：

Write - Message "dot source test"

显然，直接运行该脚本会出错，因为没有定义 Write - Message cmdlet。创建一个 Write - Message.ps1 脚本，内容如下：

$text = "default message"
function Write - Message($text) {
    Write - Output "$text"
}

在 Dot - Source.ps1 脚本开头添加以下行：

. C:\temp\poshbook\ch11\Write - Message.ps1

修改路径以反映 Write - Message.ps1 的实际保存位置，然后运行 Dot - Source.ps1 脚本，消息将被显示。然而，点源法会将脚本中的成员、变量和函数引入父作用域，可能会导致作用域混乱和变量冲突等问题。如果不确定函数的来源，可以使用 ${function:Write - Message}.File 来检查。

8. 总结

通过深入了解 PowerShell 的错误处理、调试技巧和模块创建方法，可以更好地编写、调试和分发 PowerShell 代码。错误处理帮助我们应对代码中的各种异常情况，调试技巧让我们能够快速定位和解决问题，而模块创建则提高了代码的可重用性和可维护性。在实际应用中，建议多实践，不断积累经验，以充分发挥 PowerShell 的强大功能。

• 常见问题解答
  1. 在运行脚本时，终止性错误和非终止性错误的主要区别是什么？
     终止性错误会导致脚本立即停止执行，而非终止性错误通常允许脚本继续执行。
  2. 如何访问错误的详细信息？
     可以查看错误对象的属性来获取详细信息。
  3. PowerShell 中 -ErrorActionPreference 变量的用途是什么？
     用于全局控制错误的处理方式。
  4. PowerShell 中 Write - Error cmdlet 的用途是什么？
     用于生成错误信息。
  5. 为什么要使用 Throw 语句？
     当遇到不理想但不会自然引发错误的情况时，手动抛出终止性错误。
  6. 如何在脚本中显示调试消息？
     使用 Write - Debug 结合 -Debug 参数。
  7. 如何在脚本中编写调试消息，是为谁编写的？
     使用 Write - Debug 编写调试消息，主要是为开发者自己在调试代码时使用。
  8. PowerShell 中的断点是什么？
     断点是代码中的一个位置，当程序执行到该位置时会暂停，方便开发者进行调试。
  9. stepOver 调试命令的用途是什么？
     单步执行代码，跳过函数内部的执行，直接执行完当前行。

通过以上内容的学习和实践，相信你能够更加熟练地使用 PowerShell 进行开发和维护工作。不断尝试和探索，你会发现 PowerShell 在自动化任务和系统管理方面的巨大潜力。

深入探索 PowerShell 错误处理、调试与模块创建

9. PowerShellGet 模块介绍

Microsoft 提供了名为 PowerShellGet 的模块，它包含了许多用于处理存储库和模块的资源。此模块已包含在 PowerShell 7 中，借助它可以轻松与 PowerShell 库进行交互，实现查找、注册和注销其他存储库，还能查找、安装和卸载存储库中的模块和脚本，以及对这些模块和脚本进行操作。

从 PowerShell 7.4 开始，PowerShellGet v2.2.5 模块将与版本 3 并存。版本 3 的模块名为 Microsoft.Powershell.PSResourceGet，它用单个 Install-PSResource cmdlet 替代了 Install-Module 和 Install-Script cmdlet 等诸多改变。在 PowerShell 7.4 中，这两个模块将同时存在，确保当前使用 PowerShellGet 的资源能够继续正常工作。不过，不会包含兼容性层，因此为 v2.2.5 及更早版本编写的脚本无法在版本 3 中运行，除非使用将包含在 PowerShell 7.5 中的单独的 CompatPowerShellGet 模块。

10. 模块清单

模块清单是一个 .psd1 文件，它为模块提供元数据。虽然创建简单模块时不是必需的，但在构建更复杂的模块时非常有用。模块清单可以定义模块的依赖项、导出的 cmdlet、函数、别名等。以下是一个简单的模块清单示例：

@{
    ModuleVersion = '1.0'
    GUID = '12345678-1234-1234-1234-123456789012'
    Author = 'Your Name'
    CompanyName = 'Your Company'
    Copyright = '(c) Your Name. All rights reserved.'
    Description = 'A simple PowerShell module.'
    PowerShellVersion = '5.1'
    FunctionsToExport = '*'
    CmdletsToExport = '*'
    VariablesToExport = '*'
    AliasesToExport = '*'
}

在这个示例中：
- ModuleVersion ：指定模块的版本。
- GUID ：模块的全局唯一标识符。
- Author 和 CompanyName ：分别表示作者和公司名称。
- Copyright ：版权信息。
- Description ：模块的描述。
- PowerShellVersion ：模块所需的 PowerShell 最低版本。
- FunctionsToExport 、 CmdletsToExport 、 VariablesToExport 和 AliasesToExport ：指定要导出的函数、cmdlet、变量和别名， * 表示导出所有。

11. 使用脚手架工具 Plaster

Plaster 是一个用于创建 PowerShell 模块和脚本的脚手架工具，它可以帮助我们快速生成模块的基本结构。以下是使用 Plaster 创建模块的基本步骤：
1. 安装 Plaster ：

Install-Module -Name Plaster -Force

2. 查找 Plaster 模板 ：

Find-PlasterTemplate -IncludeInstalled

3. 使用模板创建模块 ：

Invoke-Plaster -TemplatePath <TemplatePath> -DestinationPath <DestinationPath>

其中， <TemplatePath> 是 Plaster 模板的路径， <DestinationPath> 是要创建模块的目标路径。

12. 嵌套模块

模块可以嵌套在其他模块中，这为创建复杂的应用程序提供了便利。在使用嵌套模块时，需要注意以下几点：
- 加载顺序 ：嵌套模块会在父模块加载时自动加载。
- 作用域 ：嵌套模块中的函数和变量在其自身的作用域内，但可以通过适当的方式在父模块中访问。
- 版本管理 ：确保嵌套模块的版本与父模块兼容。

例如，我们有一个父模块 ParentModule ，它依赖于一个嵌套模块 ChildModule 。在 ParentModule 的清单文件中，可以通过 RequiredModules 参数指定依赖的嵌套模块：

@{
    ModuleVersion = '1.0'
    RequiredModules = @(
        @{ ModuleName = 'ChildModule'; ModuleVersion = '1.0' }
    )
}

13. 总结与实践建议

通过对 PowerShell 错误处理、调试和模块创建的全面学习，我们了解到：
- 错误处理是编写健壮代码的关键，合理使用 Try/Catch/Finally 语句和 Throw 语句可以有效应对各种异常情况。
- 调试技巧如使用 VS Code 调试器和 Write-Debug 可以帮助我们快速定位和解决代码中的问题。
- 模块的创建和使用提高了代码的可重用性和可维护性，通过合理选择模块加载方式和管理模块位置，可以更好地组织和分发代码。

为了更好地掌握这些知识，建议进行以下实践：
- 编写一些简单的脚本，故意引入错误，然后使用所学的错误处理方法进行修复。
- 在 VS Code 中调试这些脚本，熟悉调试器的各个功能。
- 创建自己的模块，尝试使用不同的方式加载和使用模块，同时使用 Plaster 工具快速搭建模块结构。

通过不断的实践和探索，我们将能够更加熟练地使用 PowerShell 进行开发和系统管理，充分发挥其在自动化任务中的强大功能。

以下是一个简单的 mermaid 流程图，展示了创建和使用 PowerShell 模块的基本流程：

graph LR
    A[编写模块代码] --> B[保存为.psm1 文件]
    B --> C{模块位置}
    C -->|系统位置| D[系统默认模块文件夹]
    C -->|所有用户位置| E[所有用户可访问的模块文件夹]
    C -->|用户位置| F[用户个人模块文件夹]
    D --> G[自动或手动加载模块]
    E --> G
    F --> G
    G --> H[使用模块中的函数和 cmdlet]
    H --> I[卸载模块]

通过这个流程图，我们可以清晰地看到从编写模块代码到最终使用和卸载模块的整个过程。希望这些知识和实践建议能够帮助你在 PowerShell 的学习和应用中取得更好的效果。