主题
about_Functions
简短说明
说明如何在 Windows PowerShell 中创建和使用函数。
详细说明
函数是具有指定名称的语句列表。在运行函数时，需键入函数名称。列表中语句的运行效果
与在命令提示符下键入它们时的运行效果相同。
与 cmdlet 类似，函数也可带有参数。参数可以是命名参数、位置参数、开关参数或动态参数。
函数参数可从命令行或通过管道读取。
函数返回的值可以显示出来、赋给变量或传递到其他函数或 cmdlet。
函数的语句列表可包含带有 Begin、Process 和 End 关键字的不同语句列表类型。
这些语句列表以不同方式对来自管道的输入进行处理。
筛选器是使用 Filter 关键字的一种特殊函数。
函数的工作方式也可类似于 cmdlet。可在不使用 C# 编程的情况下创建工作方式类似于 cmdlet 的函数。
有关详细信息，请参阅 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>}
}
函数中包含以下各项：
- 一个 Function 关键字
- 一个作用域（可选）
- 一个由您选择的名称
- 任意数目的命名参数（可选）
- 括在大括号 ({}) 内的一条或多条 Windows PowerShell 命令
有关函数中的 Dynamicparam 关键字和动态参数的详细信息，请参阅
about_Functions_Advanced_Parameters。
简单函数
函数不必很复杂即可非常有用。以下函数可获取不属于当前系统的 System 帐户的环境变量：
function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<System>"}
}
若要运行该函数，请键入“other_env”。
可创建一个包含有用小型函数的工具箱，并将这些函数添加到 Windows PowerShell 配置文件中，如
about_Profiles 中以及本主题后面内容所述。
使用参数的函数
可在函数中使用参数，包括命名参数、位置参数、开关参数和动态参数。有关函数中的动态参数的详细信
息，请参阅 about_Functions_Advanced_Parameters。
命名参数
可以定义任意数目的命名参数。可为命名参数提供默认值，如本主题后面的内容所述。
可以使用 Param 关键字在大括号内定义参数，如以下示例语法所示：
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
也可以在大括号外定义参数而不使用 Param 关键字，如以下示例语法所示：
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
这两种方法之间没有差别。您可以自行选择使用任何方法。
在运行函数时，为参数提供的值将赋给包含该参数名的变量。可在函数中使用该变量的值。
以下示例是一个名为"Small_files"的函数。此函数有一个 $size 参数。该函数显示小于 $size 参
数的值的所有文件，并排除目录：
function small_files {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
在该函数中，可以使用 $size 变量，该变量是为该参数定义的名称。
若要使用该函数，请键入以下命令：
C:\PS> function small_files -size 50
也可以为命名参数输入值而不使用该参数的名称。例如，以下命令与指定 Size 参数名的
命令所得结果相同：
C:\PS> function small_files 50
若要定义参数的默认值，请在参数名称的后面键入等号和值，如 Small_files 示例的
以下变化形式所示：
function small_files ($size = 100) {
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
如果键入"small_files"而不带任何值，则函数将 100 赋给 $size。如果提供一个值，
则函数将使用该值。
位置参数
位置参数是不带参数名称的参数。Windows PowerShell 根据参数值的顺序将每个参数值
与函数中的参数相关联。
在使用位置参数时，请在函数名称的后面键入一个或多个值。位置参数值赋给 $args 数组变量。
跟在函数名称后面的值赋给 $args 数组中的第一个位置 $args[0]。
以下 Extension 函数将 .txt 文件扩展名添加到您提供的文件名：
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension myTextFile
myTextFile.txt
函数可使用一个以上的位置参数。以下示例显示随函数名称输入的所有值。
function repeat { foreach ($arg in $args) { "The input is
$arg" } }
C:\PS>repeat one
The input is one
C:\PS> repeat one two three
The input is one
The input is two
The input is three
此函数可使用任意数目的值。该函数将每个值赋给 $args 数组中的一个位置。
开关参数
开关是不需要值的参数。在键入函数名称后键入开关参数的名称即可使用开关参数。
若要定义开关参数，请在参数名称前面指定类型 [switch]，如以下示例所示：
function switchExample {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
如果在函数名称后面键入 On 开关参数，则函数将显示“Switch on”。如果不使用该开关参数，则函数
将显示"Switch off"。
C:\PS> SwitchExample -on
Switch on
C:\PS> SwitchExample
Switch off
也可在运行函数时将布尔值赋予开关，如以下示例所示：
C:\PS> SwitchExample -on:$true
Switch on
C:\PS> SwitchExample -on:$false
Switch off
通过管道将对象传递给函数
任何函数都可通过管道获取输入。可以使用 Begin、Process 和 End 关键字来控制函数处理来自管道
的输入的方式。以下示例语法显示了这三个关键字：
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Begin 语句列表只运行一次，位于函数开头。
Process 语句列表针对管道中的每个对象运行一次。
当 Process 块运行时，将每个管道对象逐次赋予 $_ 自动变量。
在函数收到管道中的所有对象之后，将运行一次 End 语句列表。如果未使用 Begin、Process 或 End
关键字，则将所有语句视同一个 End 语句列表。
以下函数使用 Process 关键字。该函数显示来自管道的示例：
function pipelineFunction
{
process {"The value is: $_"}
}
若要演示此函数，请输入用逗号分隔的数字数组，如以下示例所示：
C:\PS> 1,2,4 | pipelineFunction
The value is: 1
The value is: 2
The value is: 4
在管道中使用函数时，通过管道传递给函数的对象将赋给 $input 自动变量。在从管道传入任何对象之
前，函数会运行带有 Begin 关键字的语句。在通过管道收到所有对象之后，函数将运行带有 End 关键字
的语句。
以下示例显示了和 Begin 和 End 关键字一起使用的 $input 自动变量。
function PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
如果使用管道运行此函数，则函数将显示以下结果：
C:\PS> 1,2,4 | PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
当 Begin 语句运行时，函数还没有来自管道的输入。End 语句在函数获取值之后运行。
如果函数中有 Process 关键字，则函数将读取 $input 中的数据。以下示例包含一个 Process 语句列
表：
function PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
在此示例中，通过管道传递给函数的每个对象都将发送到 Process 语句列表。Process 语句将对每个对
象逐次运行。当函数到达 End 关键字时，$input 自动变量为空。
C:\PS> 1,2,4 | PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
筛选器
筛选器是一种对管道中的每个对象运行的函数。筛选器与将所有语句都放在 Process 块中的函数类似。
筛选器的语法如下：
filter [<scope:>]<name> {<statement list>}
以下筛选器通过管道获取日志条目，然后显示整个条目或仅显示条目的消息部分：
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message } else
{ $_ }
}
函数作用域
函数存在于创建它的作用域中。
如果函数是脚本的一部分，则该函数可供该脚本内的语句使用。默认情况下，脚本中的函数在命令提示符下不可用。
可以指定函数的作用域。例如，以下示例将函数添加到全局作用域：
function global:get-dependentsvs { get-service |
where {$_.dependentservices} }
当函数处于全局作用域中时，可以在脚本中、函数中和命令行上使用该函数。
函数通常会创建一个作用域。在函数中创建的项（如变量）仅存在于该函数作用域中。
有关 Windows PowerShell 中的作用域的详细信息，请参阅 about_Scope。
使用 Function: 驱动器查找和管理函数 Windows PowerShell
中的所有函数和筛选器都自动存储在 Function: 驱动器中。此驱动器由 Windows PowerShell Function 提供程序公开。
若要引用 Function: 驱动器，请在 Function 后键入一个冒号，就像引用计算机上的 C 或 D 驱动器
一样。
以下命令显示了 Windows PowerShell 的当前会话中的所有函数：
C:\PS> dir function:
函数中的命令作为脚本块存储在该函数的 definition 属性中。例如，若要显示 Windows
PowerShell 附带的 Help 函数中的命令，请键入：
(dir function:help).definition
有关 Function: 驱动器的详细信息，请参阅"函数"。
在新会话中重用函数
在 Windows PowerShell 命令提示符下键入一个函数时，该函数将成为当前会话的一部分。在会话结束
之前该函数一直可用。
若要在所有 Windows PowerShell 会话中使用您的函数，请将该函数添加到 Windows PowerShell 配
置文件中。有关配置文件的详细信息，请参阅 about_Profiles。
也可以将函数保存在 Windows PowerShell 脚本文件中。在一个文本文件中键入函数，然后以 .ps1
作为文件扩展名来保存该文件。
编写函数帮助
Get-Help cmdlet 可获取函数、cmdlet、提供程序和脚本的帮助。若要获取函数帮助，请键入 Get-
Help，并在后面键入函数名称。
例如，若要获取 MyDisks 函数的帮助，请键入：
get-help MyDisks
可使用以下两种方法之一来编写函数帮助：
-- 基于注释的函数帮助
通过在注释中使用特殊关键字来创建帮助主题。若要创建基于注释的函数帮助，必须将注释放在函数体的
开头或末尾，或放在 function 关键字前面的行中。有关基于注释的帮助的详细信息，请参阅
about_Comment_Based_Help。
-- 基于 XML 的函数帮助
创建基于 XML 的帮助主题，例如通常为 cmdlet 创建的类型。如果要将帮助主题本地化为多种语言，
则需要使用基于 XML 的帮助。
若要将函数与基于 XML 的帮助主题相关联，请使用 .ExternalHelp 帮助注释关键字。有关
ExternalHelp 关键字的详细信息，请参阅 about_Comment_Based_Help。有关基于 XML 的帮助的
详细信息，请参阅 MSDN 中的“如何编写 Cmdlet 帮助”。
另请参阅
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBinding
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function（提供程序）