命令行与文本处理 / 系统课时
编写高级函数
编写高级函数
高级函数让普通 PowerShell 函数具备接近 Cmdlet 的参数绑定、公共参数和管道处理能力。本课将实现一个可接收管道输入的函数,并明确 Begin、Process、End 三个阶段分别应承担什么职责。
学习目标
- 使用
CmdletBinding与Param声明高级函数 - 正确规划 Begin、Process、End 的执行职责
- 使用公共参数增强诊断与错误控制能力
高级函数的判断标准
函数体中加入 [CmdletBinding()],并使用 param() 声明参数后,PowerShell 会按高级函数规则执行参数绑定。函数因此自动获得 -Verbose、-Debug、-ErrorAction、-WarningAction 等公共参数,也可以通过 $PSCmdlet 访问运行时能力。
Param 必须位于函数体开头,前面只能出现注释或属性声明。参数是否支持管道输入、是否必填、从哪个属性名绑定,都由 [Parameter()] 的选项控制。
规划三个执行阶段
Begin 在管道开始前执行一次,适合初始化计数器、连接或缓存;Process 对每个输入对象执行一次,是转换和处理的核心;End 在所有输入完成后执行一次,适合汇总、刷新缓冲区和释放资源。

没有管道输入而直接调用函数时,Process 仍会执行一次。Begin 和 End 中写入成功输出流的对象也会进入管道,因此初始化信息和调试信息应使用 Write-Verbose,不要误用普通输出。
主示例:处理管道中的名称
下面的函数逐项接收字符串,生成带序号的标准化标签。Begin 初始化计数器,Process 处理每个名称,End 只输出可选的详细诊断信息。
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 }预期输出
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返回业务结果;它面向显示,无法像对象输出一样可靠参与后续管道处理。