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

接收管道输入

接收管道输入

本课解决自定义函数无法像原生命令那样接入管道的问题。你将分别配置按值绑定与按属性名绑定,并用 process 块逐个处理输入对象,最终写出可直接参与对象管道的函数。

学习目标

  • 理解 ValueFromPipeline 与 ValueFromPipelineByPropertyName 的绑定差异
  • 使用 process 块正确处理管道中的多个对象
  • 通过参数类型、属性名和别名排查绑定失败

两种管道绑定方式

ValueFromPipeline 表示“按值绑定”:PowerShell 尝试把整个管道对象绑定到参数,参数类型必须兼容。它适合接收字符串、文件对象或其他完整对象。

ValueFromPipelineByPropertyName 表示“按属性名绑定”:PowerShell 从输入对象中寻找与参数同名或与参数别名同名的属性,再把属性值绑定给参数。它适合接收来自 Import-Csv、Select-Object 或业务对象的数据。

方式 输入对象如何绑定 常见用途
ValueFromPipeline 整个对象绑定到参数 处理字符串、进程、文件等对象
ValueFromPipelineByPropertyName 同名属性绑定到参数 接收 CSV 行、查询结果、定制对象

参数绑定与执行过程

管道中的对象会逐个进入函数。begin 只执行一次,适合初始化;process 对每个输入对象执行一次,是接收管道输入的核心;end 只执行一次,适合汇总或清理。

管道参数绑定数据流

主示例

下面的脚本用两个小函数分别演示按值绑定和按属性名绑定。两个函数都把结果作为对象写回成功输出流,因此可以继续接入后续命令。

powershell
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)" }

预期输出

text
user:alice
user:bob
Carol@Ops|Carol
David@Dev|David

UserName 能绑定到参数 Name,是因为参数声明了 [Alias('UserName')]。实际处理 CSV 时,只要列名与参数名或别名一致,就可以直接把 Import-Csv 的结果传入函数。

关键边界与排查

同一个参数同时启用两种绑定方式时,要特别注意类型转换。若参数声明为 [string],复杂对象可能先被整体转换成字符串,导致按属性名绑定没有发生。教学和生产代码中应优先让参数职责单一,或使用明确的参数集区分不同输入方式。

绑定失败时按以下顺序检查:参数是否标记为管道输入、函数是否在 process 中处理对象、输入对象类型是否兼容、属性名或别名是否完全匹配。需要观察绑定细节时,可临时运行 Trace-Command -Name ParameterBinding -PSHost,但其输出较多,定位结束后应移除。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接收管道输入

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

登录哪都通