命令行与文本处理 / 系统课时
接收管道输入
接收管道输入
本课解决自定义函数无法像原生命令那样接入管道的问题。你将分别配置按值绑定与按属性名绑定,并用 process 块逐个处理输入对象,最终写出可直接参与对象管道的函数。
学习目标
- 理解
ValueFromPipeline与ValueFromPipelineByPropertyName的绑定差异 - 使用
process块正确处理管道中的多个对象 - 通过参数类型、属性名和别名排查绑定失败
两种管道绑定方式
ValueFromPipeline 表示“按值绑定”:PowerShell 尝试把整个管道对象绑定到参数,参数类型必须兼容。它适合接收字符串、文件对象或其他完整对象。
ValueFromPipelineByPropertyName 表示“按属性名绑定”:PowerShell 从输入对象中寻找与参数同名或与参数别名同名的属性,再把属性值绑定给参数。它适合接收来自 Import-Csv、Select-Object 或业务对象的数据。
| 方式 | 输入对象如何绑定 | 常见用途 |
|---|---|---|
ValueFromPipeline |
整个对象绑定到参数 | 处理字符串、进程、文件等对象 |
ValueFromPipelineByPropertyName |
同名属性绑定到参数 | 接收 CSV 行、查询结果、定制对象 |
参数绑定与执行过程
管道中的对象会逐个进入函数。begin 只执行一次,适合初始化;process 对每个输入对象执行一次,是接收管道输入的核心;end 只执行一次,适合汇总或清理。

主示例
下面的脚本用两个小函数分别演示按值绑定和按属性名绑定。两个函数都把结果作为对象写回成功输出流,因此可以继续接入后续命令。
function Add-UserPrefix {
[CmdletBinding()]
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string]$InputObject
)
process {
"user:$($InputObject.ToLowerInvariant())"
}
}
function Get-UserBadge {
[CmdletBinding()]
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[Alias('UserName')]
[string]$Name,
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string]$Department
)
process {
[pscustomobject]@{
Badge = "$Name@$Department"
Name = $Name
}
}
}
'Alice', 'Bob' |
Add-UserPrefix
@(
[pscustomobject]@{ UserName = 'Carol'; Department = 'Ops' }
[pscustomobject]@{ UserName = 'David'; Department = 'Dev' }
) |
Get-UserBadge |
ForEach-Object { "$($_.Badge)|$($_.Name)" }预期输出
user:alice
user:bob
Carol@Ops|Carol
David@Dev|DavidUserName 能绑定到参数 Name,是因为参数声明了 [Alias('UserName')]。实际处理 CSV 时,只要列名与参数名或别名一致,就可以直接把 Import-Csv 的结果传入函数。
关键边界与排查
同一个参数同时启用两种绑定方式时,要特别注意类型转换。若参数声明为 [string],复杂对象可能先被整体转换成字符串,导致按属性名绑定没有发生。教学和生产代码中应优先让参数职责单一,或使用明确的参数集区分不同输入方式。
绑定失败时按以下顺序检查:参数是否标记为管道输入、函数是否在 process 中处理对象、输入对象类型是否兼容、属性名或别名是否完全匹配。需要观察绑定细节时,可临时运行 Trace-Command -Name ParameterBinding -PSHost,但其输出较多,定位结束后应移除。