关于函数

简短描述

描述如何在 PowerShell 中创建和使用函数。

详细描述

函数是具有您指定的名称的 PowerShell 语句列表。当您运行函数时，您可以键入函数名称。列表中的语句运行就像您在命令提示符下键入它们一样。

函数可以很简单：

function Get-PowerShellProcess { Get-Process pwsh }

定义函数后，您可以像使用内置 cmdlet 一样使用它。例如，要调用新定义的 Get-PowerShellProcess 函数：

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

函数也可以像 cmdlet 或应用程序一样复杂。

与 cmdlet 一样，函数也可以有参数。这些参数可以是命名参数、位置参数、开关参数或动态参数。函数参数可以从命令行或管道读取。

函数可以返回可显示、分配给变量或传递给其他函数或 cmdlet 的值。您还可以使用 return 关键字指定返回值。 return 关键字不会影响或抑制函数返回的其他输出。但是，return 关键字会在该行退出该函数。欲了解更多信息，请参阅about_Return。

函数的语句列表可以包含不同类型的语句列表，其中包含关键字 begin、process、end 和 clean 。这些语句列表以不同的方式处理来自管道的输入。

filter 关键字用于创建一种在管道中的每个对象上运行的函数。过滤器类似于一个函数，其所有语句都位于 process 块中。

函数也可以像 cmdlet 一样运行。您可以创建一个像 cmdlet 一样工作的函数，而无需使用 C# 编程。有关详细信息，请参阅 about_Functions_Advanced。

这很重要

在脚本文件和基于脚本的模块中，必须先定义函数，然后才能调用它们。

句法

以下是函数的语法：

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

一个函数包括以下几项：

• function 关键字
• 范围（可选）
• 您选择的名称
• 任意数量的命名参数（可选）
• 用大括号括起来的一个或多个 PowerShell 命令 {}

有关函数中的 dynamicparam 关键字和动态参数的详细信息，请参阅 about_Functions_Advanced_Parameters。

输入处理方式

本节中描述的方法称为输入处理方法。对于函数来说，这三个方法由函数的 begin、process 和 end 块表示。 PowerShell 7.3 添加了 clean 块处理方法。

您不需要在函数中使用任何这些块。如果您不使用命名块，则 PowerShell 会将代码放入函数的 end 块中。但是，如果您使用任何这些命名块，或者定义 dynamicparam 块，则必须将所有代码放入命名块中。

以下示例显示了一个函数的概要，该函数包含用于一次性预处理的 begin 块、用于多记录处理的 process 块和一个 end 块用于一次性后处理。

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

开始

该块用于为函数提供可选的一次性预处理。 PowerShell 运行时为管道中函数的每个实例使用此块中的代码一次。

流程

该块用于为该函数提供逐条记录的处理。您可以使用 process 块而不定义其他块。 process 块执行的数量取决于您如何使用函数以及函数接收的输入。

自动变量 $_ 或 $PSItem 包含管道中用于 process 块的当前对象。 $input 自动变量包含一个仅适用于函数和脚本块的枚举器。有关详细信息，请参阅 about_Automatic_Variables。

• 在开头或管道外部调用该函数，会执行 process 块一次。
• 在管道中，process 块为每个到达函数的输入对象执行一次。

• 如果到达函数的管道输入为空，则 process 块不会执行。

  • begin、end 和 clean 块仍然执行。

这很重要

如果函数参数设置为接受管道输入，并且未定义 process 块，则逐条记录处理将失败。在这种情况下，无论输入如何，您的函数都只会执行一次。

结束

该块用于为该函数提供可选的一次性后处理。

干净

PowerShell 7.3 中添加了 clean 块。

clean 块是用户清理跨越 begin、process 和 end 的资源的便捷方法> 块。它在语义上类似于覆盖脚本函数或脚本 cmdlet 的所有其他命名块的finally 块。以下场景会强制执行资源清理：

1. 当管道执行正常完成且没有终止错误时
2. 当管道执行由于终止错误而中断时
3. 当管道被 Select-Object -First 停止时
4. 当管道被 Ctrl+c 或 StopProcessing() 停止时

clean 块会丢弃写入 Success 流的任何输出。

警告

添加 clean 块是一项重大更改。由于 clean 被解析为关键字，因此它可以防止用户直接调用名为 clean 的命令作为脚本块中的第一个语句。然而，这不太可能成为问题。仍然可以使用调用运算符 (& clean) 调用该命令。

简单的功能

函数不一定要复杂才能有用。最简单的函数具有以下格式：

function <function-name> {statements}

例如，以下函数使用以管理员身份运行选项启动 PowerShell。

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

要使用该功能，请键入：Start-PSAdmin

要向函数添加语句，请在单独的行中键入每个语句，或使用分号 ; 分隔语句。

例如，以下函数查找当前用户目录中在开始日期之后更改的所有 .jpg 文件。

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

您可以创建一个包含有用小功能的工具箱。将这些函数添加到您的 PowerShell 配置文件中，如 about_Profiles 和本主题后面部分中所述。

函数名称

您可以为函数分配任何名称，但与其他人共享的函数应遵循为所有 PowerShell 命令建立的命名规则。

函数名称应由动词-名词对组成，其中动词标识函数执行的操作，名词标识 cmdlet 执行其操作的项目。

函数应使用已批准用于所有 PowerShell 命令的标准动词。这些动词帮助我们保持命令名称一致并易于用户理解。

有关标准 PowerShell 动词的更多信息，请参阅批准的动词。

带参数的函数

您可以将参数与函数一起使用，包括命名参数、位置参数、开关参数和动态参数。有关函数中动态参数的更多信息，请参阅 about_Functions_Advanced_Parameters。

命名参数

您可以定义任意数量的命名参数。您可以包含命名参数的默认值，如本主题后面所述。

您可以使用 param 关键字在大括号内定义参数，如以下示例语法所示：

function <name> {
  param ([type]$parameter1 [,[type]$parameter2])
  <statement list>
}

您还可以在大括号之外定义参数，而无需使用 Param 关键字，如以下示例语法所示：

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

下面是这种替代语法的示例。

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

虽然首选第一种方法，但这两种方法之间没有区别。

当您运行该函数时，您为参数提供的值将分配给包含参数名称的变量。该变量的值可以在函数中使用。

以下示例是一个名为 Get-SmallFiles 的函数。此函数有一个 $Size 参数。该函数显示所有小于 $Size 参数值的文件，并且不包括目录：

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

在函数中，您可以使用 $Size 变量，它是为参数定义的名称。

要使用此功能，请键入以下命令：

Get-SmallFiles -Size 50

您还可以输入不带参数名称的命名参数值。例如，以下命令给出的结果与命名 Size 参数的命令相同：

Get-SmallFiles 50

要定义参数的默认值，请在参数名称后键入等号和值，如 Get-SmallFiles 示例的以下变体所示：

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

如果您键入不带值的 Get-SmallFiles，该函数会将 100 分配给 $size。如果您提供一个值，该函数将使用该值。

或者，您可以提供一个简短的帮助字符串来描述参数的默认值，方法是将 PSDefaultValue 属性添加到参数的描述中，并指定 Help 属性PSDefaultValue。要提供描述 Get-SmallFiles 函数中 Size 参数的默认值 (100) 的帮助字符串，请将 PSDefaultValue 属性添加为如以下示例所示。

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

有关 PSDefaultValue 属性类的详细信息，请参阅 PSDefaultValue 属性成员。

位置参数

位置参数是没有参数名称的参数。 PowerShell 使用参数值顺序将每个参数值与函数中的参数相关联。

使用位置参数时，请在函数名称后键入一个或多个值。位置参数值被分配给 $args 数组变量。函数名称后面的值被分配给 $args 数组中的第一个位置 $args[0]。

以下 Get-Extension 函数将 .txt 文件扩展名添加到您提供的文件名中：

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

开关参数

开关是不需要值的参数。相反，您可以键入函数名称，后跟开关参数的名称。

要定义开关参数，请在参数名称前指定类型[switch]，如下例所示：

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

当您在函数名称后键入 On 开关参数时，函数会显示 Switch on。如果没有 switch 参数，则显示 Switch off。

Switch-Item -on

Switch on

Switch-Item

Switch off

您还可以在运行该函数时为开关分配一个布尔值，如以下示例所示：

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

使用展开来表示命令参数

您可以使用展开来表示命令的参数。 Windows PowerShell 3.0 中引入了此功能。

在会话中调用命令的函数中使用此技术。您不需要声明或枚举命令参数，也不需要在命令参数更改时更改函数。

以下示例函数调用 Get-Command cmdlet。该命令使用@Args来表示Get-Command的参数。

function Get-MyCommand { Get-Command @Args }

当您调用Get-MyCommand函数时，您可以使用Get-Command的所有参数。参数和参数值使用@Args传递给命令。

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

@Args 功能使用 $Args 自动参数，该参数表示未声明的 cmdlet 参数和剩余参数中的值。

有关详细信息，请参阅 about_Splatting。

将对象通过管道传递给函数

任何函数都可以从管道获取输入。您可以使用 begin、process、end 和 clean 关键字控制函数如何处理来自管道的输入。以下示例语法显示了这些关键字：

process 语句列表为管道中的每个对象运行一次。当 process 块运行时，每个管道对象都会分配给 $_ 自动变量，一次分配一个管道对象。

以下函数使用 process 关键字。该函数显示来自管道的值：

function Get-Pipeline
{
  process {"The value is: $_"}
}

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

如果您想要一个可以接受管道输入或来自参数的输入的函数，那么 process 块需要处理这两种情况。例如：

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

当您在管道中使用函数时，通过管道传输到该函数的对象将分配给 $input 自动变量。该函数在任何对象来自管道之前运行带有 begin 关键字的语句。从管道接收到所有对象后，该函数将运行带有 end 关键字的语句。

以下示例显示了带有 begin 和 end 关键字的 $input 自动变量。

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

如果使用管道运行此函数，它将显示以下结果：

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

当 begin 语句运行时，该函数没有来自管道的输入。 end 语句在函数获得值后运行。

如果函数有 process 关键字，则 $input 中的每个对象都会从 $input 中删除并分配给 $_。以下示例有一个 process 语句列表：

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

在此示例中，通过管道传输到函数的每个对象都被发送到 process 语句列表。 process 语句在每个对象上运行，一次运行一个对象。当函数到达 end 关键字时，$input 自动变量为空。

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

有关详细信息，请参阅使用枚举器

PowerShell 7.3 添加了 clean 块。 clean 块是用户清理在 begin、process 和 end块。它在语义上类似于覆盖脚本函数或脚本 cmdlet 的所有其他命名块的finally 块。以下场景会强制执行资源清理：

1. 当管道执行正常完成且没有终止错误时
2. 当管道执行由于终止错误而中断时
3. 当管道被 Select-Object -First 停止时
4. 当管道被 Ctrl+C 或 StopProcessing() 停止时

警告

添加 clean 块是一项重大更改。由于 clean 被解析为关键字，因此它可以防止用户直接调用名为 clean 的命令作为脚本块中的第一个语句。然而，这不太可能成为问题。仍然可以使用调用运算符 (& clean) 调用该命令。

过滤器

过滤器是一种在管道中的每个对象上运行的函数。过滤器类似于一个函数，其所有语句都位于 process 块中。

过滤器的语法如下：

filter [<scope:>]<name> {<statement list>}

以下过滤器从管道中获取日志条目，然后显示整个条目或仅显示条目的消息部分：

filter Get-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

它可以按如下方式使用：

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

功能范围

函数存在于它创建的范围内。

如果函数是脚本的一部分，则该函数可用于该脚本中的语句。默认情况下，脚本中的函数在该脚本之外不可用。

您可以指定函数的范围。例如，在以下示例中将该函数添加到全局范围：

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

当函数位于全局范围内时，您可以在脚本、函数和命令行中使用该函数。

函数创建了一个新的范围。函数中创建的项（例如变量）仅存在于函数作用域中。

有关详细信息，请参阅 about_Scopes。

使用功能查找和管理功能：驱动器

PowerShell 中的所有函数和筛选器都会自动存储在 Function: 驱动器中。此驱动器由 PowerShell 函数 提供程序公开。

引用 Function: 驱动器时，请在 Function 后键入冒号，就像引用 C 或 D 计算机的驱动器。

以下命令显示当前 PowerShell 会话中的所有功能：

Get-ChildItem function:

函数中的命令作为脚本块存储在函数的定义属性中。例如，要显示 PowerShell 附带的帮助功能中的命令，请键入：

(Get-ChildItem function:help).Definition

您还可以使用以下语法。

$function:help

有关Function: 驱动器的更多信息，请参阅Function 提供程序的帮助主题。输入获取帮助函数。

在新会话中重用函数

当您在 PowerShell 命令提示符下键入函数时，该函数将成为当前会话的一部分。该功能在会话结束之前一直可用。

要在所有 PowerShell 会话中使用您的函数，请将该函数添加到您的 PowerShell 配置文件中。有关配置文件的更多信息，请参阅 about_Profiles。

您还可以将函数保存在 PowerShell 脚本文件中。在文本文件中键入函数，然后使用 .ps1 文件扩展名保存该文件。

为函数编写帮助

Get-Help cmdlet 获取函数以及 cmdlet、提供程序和脚本的帮助。要获取函数的帮助，请键入 Get-Help，后跟函数名称。

例如，要获取 Get-MyDisks 函数的帮助，请键入：

Get-Help Get-MyDisks

您可以使用以下两种方法之一为函数编写帮助：

• 基于注释的函数帮助

  在评论中使用特殊关键字创建帮助主题。要为函数创建基于注释的帮助，注释必须放置在函数体的开头或结尾，或者放置在函数关键字之前的行上。有关基于注释的帮助的详细信息，请参阅 about_Comment_Based_Help。

• 基于 XML 的函数帮助

  创建基于 XML 的帮助主题，例如通常为 cmdlet 创建的类型。如果您要将帮助主题本地化为多种语言，则需要基于 XML 的帮助。

  要将函数与基于 XML 的帮助主题相关联，请使用基于注释的帮助关键字 .EXTERNALHELP。如果没有此关键字，Get-Help 将无法找到函数帮助主题，并且调用 Get-Help 函数将仅返回自动生成的帮助。

  有关 .EXTERNALHELP 关键字的详细信息，请参阅 about_Comment_Based_Help。有关基于 XML 的帮助的详细信息，请参阅如何编写 Cmdlet 帮助。

参见

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_功能_高级
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_参数
• about_个人资料
• about_范围
• about_Script_Blocks