#函数

#简介

函数把一段可复用的代码封装起来，通过名称调用。PowerShell 函数可以接收参数、返回值，也可以像 cmdlet 一样接收管道输入。使用 [CmdletBinding()] 还可以获得高级函数的通用参数支持。

#定义与调用

使用 function 关键字定义函数：

function Get-Greeting {
    "Hello, World"
}

Get-Greeting

Hello, World

#param 块

参数在函数开头的 param 块中声明：

function Get-Greeting {
    param(
        [string]$Name,
        [int]$Times = 1
    )

    for ($i = 0; $i -lt $Times; $i++) {
        "Hello, $Name"
    }
}

Get-Greeting -Name "Tom" -Times 2

Hello, Tom
Hello, Tom

参数可以指定类型，例如 [string]、[int]。
使用 = 默认值 设置默认值。
调用时参数名可以省略，按位置传入。

#返回值与输出

PowerShell 函数会把所有未被捕获的输出作为返回值：

function Add-Numbers {
    param([int]$A, [int]$B)
    $A + $B
}

$result = Add-Numbers -A 2 -B 3
$result

也可以使用 return 提前结束函数并返回结果：

function Test-Positive {
    param([int]$Value)
    if ($Value -le 0) {
        return $false
    }
    return $true
}

PowerShell 的 return 并不会阻止之前的输出被返回。函数中任何未赋值给变量的输出都会进入结果流。

#作用域

函数拥有自己的作用域。函数内定义的变量默认是局部变量，函数执行结束后不再可用：

function Set-Local {
    $localValue = "inside"
    $localValue
}

Set-Local
$localValue

第二行不会输出内容，因为 $localValue 不存在于函数外部。需要访问外部变量时，可使用 $script: 或 $global: 前缀。

#高级函数

在 param 块之前添加 [CmdletBinding()]，函数就变成高级函数，自动获得 -Verbose、-ErrorAction 等通用参数：

function Write-Message {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Message
    )

    Write-Verbose "准备输出消息"
    Write-Output $Message
}

Write-Message -Message "hello" -Verbose

Mandatory 表示参数必填，未提供时会提示输入。
高级函数还可以使用 begin、process、end 块。

#begin / process / end

处理管道输入时，可以把函数体拆成三个块：

function Measure-Text {
    [CmdletBinding()]
    param(
        [Parameter(ValueFromPipeline)]
        [string]$Text
    )

    begin {
        $count = 0
    }
    process {
        $count += $Text.Length
    }
    end {
        "Total length: $count"
    }
}

"abc", "de" | Measure-Text

Total length: 5

begin 在管道开始前执行一次。
process 对每个管道对象执行一次。
end 在处理完所有对象后执行一次。

#注释帮助

可以为函数添加基于注释的帮助，使用 Get-Help 查看：

function Get-Greeting {
    <#
    .SYNOPSIS
    返回问候语。
    .PARAMETER Name
    要问候的名字。
    .EXAMPLE
    Get-Greeting -Name "Tom"
    #>
    param([string]$Name = "World")
    "Hello, $Name"
}

Get-Help Get-Greeting

更多帮助系统的用法见 Get-Help 帮助手册。