命令行与文本处理 / 系统课时

编写高级函数

编写高级函数

高级函数让普通 PowerShell 函数具备接近 Cmdlet 的参数绑定、公共参数和管道处理能力。本课将实现一个可接收管道输入的函数,并明确 Begin、Process、End 三个阶段分别应承担什么职责。

学习目标

  • 使用 CmdletBinding 与 Param 声明高级函数
  • 正确规划 Begin、Process、End 的执行职责
  • 使用公共参数增强诊断与错误控制能力

高级函数的判断标准

函数体中加入 [CmdletBinding()],并使用 param() 声明参数后,PowerShell 会按高级函数规则执行参数绑定。函数因此自动获得 -Verbose、-Debug、-ErrorAction、-WarningAction 等公共参数,也可以通过 $PSCmdlet 访问运行时能力。

Param 必须位于函数体开头,前面只能出现注释或属性声明。参数是否支持管道输入、是否必填、从哪个属性名绑定,都由 [Parameter()] 的选项控制。

规划三个执行阶段

Begin 在管道开始前执行一次,适合初始化计数器、连接或缓存;Process 对每个输入对象执行一次,是转换和处理的核心;End 在所有输入完成后执行一次,适合汇总、刷新缓冲区和释放资源。

高级函数的 Begin、Process、End 生命周期

没有管道输入而直接调用函数时,Process 仍会执行一次。Begin 和 End 中写入成功输出流的对象也会进入管道,因此初始化信息和调试信息应使用 Write-Verbose,不要误用普通输出。

主示例:处理管道中的名称

下面的函数逐项接收字符串,生成带序号的标准化标签。Begin 初始化计数器,Process 处理每个名称,End 只输出可选的详细诊断信息。

powershell
function Convert-NameTag {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [string]$Name,

        [Parameter(Mandatory)]
        [string]$Prefix
    )

    begin {
        # Begin 只执行一次,用于准备跨对象共享的状态。
        $index = 0
        Write-Verbose 'Starting name conversion.'
    }

    process {
        $index++
        $normalized = $Name.Trim().ToUpperInvariant()

        # Process 的输出会立即进入下游管道。
        [pscustomobject]@{
            Index = $index
            Tag   = '{0}:{1}' -f $Prefix, $normalized
        }
    }

    end {
        Write-Verbose ('Converted {0} item(s).' -f $index)
    }
}

@('alice', 'bob') |
    Convert-NameTag -Prefix 'USER' |
    ForEach-Object { '{0}|{1}' -f $_.Index, $_.Tag }

预期输出

text
1|USER:ALICE
2|USER:BOB

实际调用时可以追加 -Verbose 查看 Begin 和 End 中的诊断消息;详细信息的前缀会随 PowerShell 的显示语言略有不同,但对象输出不受影响。

公共参数与副作用保护

[CmdletBinding()] 提供的公共参数不需要重复声明。函数内部应使用 Write-Verbose、Write-Warning 和 Write-Error 写入对应信息流,让调用者通过公共参数决定显示或处理方式。

函数若会删除文件、修改服务或覆盖配置,应改用 [CmdletBinding(SupportsShouldProcess)],并在执行副作用前调用 $PSCmdlet.ShouldProcess()。这样函数会自动获得 -WhatIf 与 -Confirm,但纯查询或纯转换函数不应无意义地启用它们。

常见边界

  • 不要在 Begin 中处理当前输入对象,因为管道对象尚未逐项进入 Process。
  • 不要在 Process 中重复创建可复用的连接或大型对象,应在 Begin 初始化并在 End 释放。
  • 不要用 Write-Host 返回业务结果;它面向显示,无法像对象输出一样可靠参与后续管道处理。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写高级函数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通