PowerShell 函数：校验时长并保持输出流纯净

本节目标

调用 .NET TryParse 解析分钟数，只返回整数或空值，避免诊断文字混入成功输出流而污染后续统计。

环境与运行方法

使用 PowerShell 7，保存为 lesson.ps1，执行 pwsh -NoProfile -File lesson.ps1。不修改系统配置，也不调用 Windows 专属管理接口。

核心思路

PowerShell 函数写入成功输出流的对象都会成为返回内容，随手输出一行日志也可能改变调用者得到的数据。本例把展示放在函数外。

完整示例

function Convert-Minutes {
    param([string]$Text)
    $value = 0
    if (-not [int]::TryParse($Text, [ref]$value) -or $value -lt 0 -or $value -gt 1440) {
        return $null
    }
    return $value
}
foreach ($text in @('30', '0', 'bad', '1441')) {
    $value = Convert-Minutes -Text $text
    if ($null -eq $value) { Write-Output 'invalid' }
    else { Write-Output ('ok={0}' -f $value) }
}

预期输出

ok=30
ok=0
invalid
invalid

逐步理解

[ref] 让解析结果写回变量，布尔返回值才表示解析成功。失败不能只看 value 是否零，因为合法输入也可能为零。空值放在比较左边，避免某些集合比较情形带来歧义。

若函数需要诊断，应使用适合的诊断流，不要随意 Write-Output。否则调用者可能收到混合文本和数值的数组。参数声明还可能触发类型转换，入口契约应与调用方约定一致。

常见问题与边界

• 不能用值的真假代替空值检查。
• 成功输出流中的日志也会进入结果。
• 类型转换与业务范围检查各有作用。

动手练习

增加 "1440"、"-1"，再尝试在函数中输出一行调试文字。

参考答案

新增正常结果为 1440 与失败。调试文字进入成功流后可能让返回值变成多个对象，应移除或改用诊断方式，恢复单一结果契约。