about_Parameters

简短说明

介绍如何在 PowerShell 中使用命令参数。

长说明

大多数 PowerShell 命令(如 cmdlet、函数和脚本)依赖于参数,允许用户选择选项或提供输入。 这些参数遵循命令名称,并采用以下格式:

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

参数的名称前面是连字符 (-) ,它向 PowerShell 发出信号,即连字符后面的单词是参数名称。 参数名称和值可以用空格或冒号字符分隔。 某些参数不需要或接受参数值。 其他参数需要值,但不需要命令中的参数名称。

参数的类型和这些参数的要求各不相同。 若要查找有关命令参数的信息,请使用 Get-Help cmdlet。 例如,若要查找有关 cmdlet 参数 Get-ChildItem 的信息,请键入:

Get-Help Get-ChildItem

若要查找有关脚本参数的信息,请使用脚本文件的完整路径。 例如:

Get-Help $home\Documents\Scripts\Get-Function.ps1

Get-Help该 cmdlet 返回有关命令的各种详细信息,包括说明、命令语法、有关参数的信息,以及演示如何在命令中使用参数的示例。

还可以使用 cmdlet 的参数 Get-Help 参数查找有关特定参数的信息。 或者,可以将 Parameter 参数与通配符 ( * ) 值一起使用,以查找有关命令的所有参数的信息。 例如,以下命令获取有关 cmdlet 的所有参数 Get-Member 的信息:

Get-Help Get-Member -Parameter *

默认参数值

可选参数具有默认值,该值是命令中未指定参数时使用或假定的值。

例如,许多 cmdlet 的 ComputerName 参数的默认值是本地计算机的名称。 因此,除非指定 ComputerName 参数,否则命令中使用本地计算机名称。

若要查找默认参数值,请参阅 cmdlet 的帮助主题。 参数说明应包含默认值。

还可以为 cmdlet 或高级函数的任何参数设置自定义默认值。 有关设置自定义默认值的信息,请参阅 about_Parameters_Default_Values

参数属性表

使用 cmdlet 的 Get-HelpFullParameterOnline 参数时,Get-Help将显示参数属性表,其中包含有关参数的详细信息。

此信息包括使用参数所需的详细信息。 例如,cmdlet 的 Get-ChildItem 帮助主题包括以下有关其 Path 参数的详细信息:

-Path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

参数信息包括参数语法、参数说明和参数属性。 以下部分介绍参数属性。

必需参数

此设置指示参数是否是必需的,也就是说,使用此 cmdlet 的所有命令是否都必须包含此参数。 如果值为 True ,并且命令中缺少参数,PowerShell 会提示你输入参数的值。

参数位置

Position如果设置设置为非负整数,则不需要参数名称。 这种类型的参数称为位置参数,数字指示参数必须相对于其他位置参数显示的位置。 命名参数可以在 cmdlet 名称后的任何位置列出。 如果包括位置参数的参数名称,则可以在 cmdlet 名称之后的任何位置列出该参数。

例如, Get-ChildItem cmdlet 具有 Path 和 Exclude 参数。 PositionPath 的设置为 0,这意味着它是一个位置参数。 排除Position的设置已命名

这意味着 Path 不需要参数名称,但其参数值必须是命令中第一个或仅未命名的参数值。 但是,由于 Exclude 参数是命名参数,因此可以将它放置在命令中的任何位置。

由于这两个参数的设置 Position ,可以使用以下命令中的任何一个:

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

如果要包含另一个位置参数而不包括参数名称,则必须按照设置指定的顺序放置该 Position 参数。

参数类型

此设置指定参数值的 Microsoft .NET Framework 类型。 例如,如果类型为 Int32,则参数值必须是整数。 如果类型为字符串,则参数值必须是字符串。 如果字符串包含空格,该值必须用引号括起来,或者空格的前面必须是转义字符 (`) 。

默认值

此设置指定参数在未提供其他值时将假定的值。 例如,Path 参数的默认值通常是当前目录。 必需的参数永远不会有默认值。 对于许多可选参数,没有默认值,因为如果未使用参数,该参数将不起作用。

接受多个值

此设置指示参数是否接受多个参数值。 当参数接受多个值时,可以将逗号分隔的列表键入为命令中的参数值,或者将逗号分隔的列表保存为变量 (数组) ,然后将变量指定为参数值。

例如,cmdlet 的 Get-ServiceName 参数接受多个值。 以下命令均有效:

Get-Service -Name winrm, netlogon
$s = "winrm", "netlogon"
Get-Service -Name $s

接受管道输入

此设置指示是否可以使用管道运算符 (|) 将值发送到参数。

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

当参数为“True (by Value) ”时,PowerShell 会在尝试其他方法解释命令之前尝试将任何管道值与该参数相关联。

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

例如,仅当值具有名为 Name 的属性时,才能将值通过管道传递给 Name 参数。

备注

接受管道输入的类型化参数 (by Value) 或 () by PropertyName 允许对参数使用 延迟绑定 脚本块。

延迟绑定脚本块在 ParameterBinding 期间自动运行。 结果绑定到参数。 延迟 绑定不适用于定义为 类型 ScriptBlock 的参数,或者 System.Object脚本块在 未调用的情况下 传递。

可以在此处阅读 有关延迟绑定 脚本块 的信息,about_Script_Blocks.md

接受通配符

此设置指示参数的值是否可以包含通配符,以便参数值可以与目标容器中的多个现有项匹配。

通用参数

常见参数是可用于任何 cmdlet 的参数。 有关常见参数的详细信息,请参阅 about_CommonParameters

另请参阅