关于 Functions

项目
05/09/2024

简短说明

介绍如何在 PowerShell 中创建和使用函数。

长说明

函数是具有你分配的名称的 PowerShell 语句的列表。运行函数时，键入函数名称。列表中的语句就像在命令提示符处键入它们一样运行。

函数可以简单如下：

function Get-PowerShellProcess { Get-Process PowerShell }

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

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

函数可以返回可显示、分配给变量或传递给其他函数或 cmdlet 的值。还可以使用 return 关键字 (keyword) 指定返回值。关键字 (keyword) return 不会影响或禁止从函数返回的其他输出。但是，return关键字 (keyword) 退出该行的函数。有关详细信息，请参阅 about_Return。

函数的语句列表可以包含不同类型的语句列表，关键字 Begin为、 Process和 End。这些语句以不同的方式列出处理来自管道的输入。

筛选器是一种使用 Filter 关键字 (keyword) 的特殊函数。

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

语法

下面是函数的语法：

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

函数包括以下项：

关键字 (keyword) Function
范围 (可选)
你选择的名称
任意数量的命名参数 (可选)
括在大括号中的一个或多个 PowerShell 命令 {}

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

简单函数

函数不必复杂，就很有用。最简单的函数具有以下格式：

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}
}

可以创建一个包含有用小型函数的工具箱。如本主题 about_Profiles 及更高版本中所述，将这些函数添加到 PowerShell 配置文件。

函数名称

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

函数名称应包含谓词-名词对，其中谓词标识函数执行的操作，名词标识 cmdlet 对其执行操作的项。

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

有关标准 PowerShell 谓词的详细信息，请参阅Microsoft Docs中的已批准谓词。

带参数的函数

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

命名的参数

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

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

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

还可以在大括号外定义参数，而不Param关键字 (keyword) ，如以下示例语法所示：

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

下面是此替代语法的示例。

Function Add-Numbers($one, $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 属性添加到参数的说明中，并指定 PSDefaultValue 的 Help 属性。若要提供描述函数中 Get-SmallFilesSize 参数的默认值 (100) 的帮助字符串，请添加 PSDefaultValue 属性，如以下示例所示。

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

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

位置参数

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

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

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

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

Get-Extension myTextFile

myTextFile.txt

开关参数

开关是不需要值的参数。请改为键入函数名称，后跟 switch 参数的名称。

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

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

在函数名称后键入 On switch 参数时，函数将显示“开关打开”。如果没有 switch 参数，它将显示“关闭”。

Switch-Item -on

Switch on

Switch-Item

Switch off

运行函数时，还可以将布尔值分配给开关，如以下示例所示：

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

使用 Splatting 表示命令参数

可以使用 splatting 来表示命令的参数。此功能在 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。

将对象管道连接到函数

任何函数都可以从管道获取输入。可以使用、 Process和 End 关键字控制函数处理来自管道Begin的输入的方式。以下示例语法显示了三个关键字：

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

语句 Begin 列表仅在函数开头运行一次。

重要

如果函数定义了 Begin、 Process 或 End 块，则所有代码都必须驻留在这些块中。如果定义了任何块，则不会识别块外部的代码。

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

函数收到管道中的所有对象后，语句列表将 End 运行一次。如果未 Begin使用、 Process或 End 关键字，则所有语句都被视为语句 End 列表。

以下函数使用 Process 关键字 (keyword) 。函数显示管道中的示例：

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

若要演示此函数，请输入用逗号分隔的数字列表，如以下示例所示：

1,2,4 | Get-Pipeline

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

在管道中使用函数时，通过管道传递给函数的对象将 $input 分配给自动变量。函数在任何对象来自管道之前，使用关键字 (keyword) 运行语句Begin。从管道接收所有对象后，End函数使用关键字 (keyword) 运行语句。

以下示例显示了具有 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关键字 (keyword) ，则中的$input每个对象都会从 $input 中删除并分配给 $_。以下示例包含语句 Process 列表：

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

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

1,2,4 | Get-PipelineInput

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

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

筛选器

筛选器是在管道中的每个对象上运行的函数类型。筛选器类似于一个函数，其所有语句都在块 Process 中。

筛选器的语法如下所示：

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

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

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

函数范围

函数存在于创建该函数的范围中。

如果函数是脚本的一部分，该函数可用于该脚本中的语句。默认情况下，脚本中的函数在命令提示符处不可用。

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

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

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

函数通常创建范围。在函数中创建的项（如变量）仅存在于函数范围内。

有关 PowerShell 中范围的详细信息，请参阅 about_Scopes。

使用函数：驱动器查找和管理函数

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

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

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

Get-ChildItem function:

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

(Get-ChildItem function:help).Definition

还可以使用以下语法。

$function:help

有关驱动器的详细信息 Function: ，请参阅函数提供程序的帮助主题。键入 Get-Help Function。

在新会话中重用函数

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

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

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

编写函数帮助

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

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

Get-Help Get-MyDisks

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

函数的 Comment-Based 帮助

在注释中使用特殊关键字Create帮助主题。若要为函数创建基于注释的帮助，必须将注释放置在函数体的开头或末尾，或者放置在函数关键字 (keyword) 前面的行上。有关基于注释的帮助的详细信息，请参阅 about_Comment_Based_Help。
函数的 XML-Based 帮助

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

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

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