about_Parameters

项目
10/07/2023

简短说明

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

长说明

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

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

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

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

Get-Help Get-ChildItem

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

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

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

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

Get-Help Get-Member -Parameter *

默认参数值

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

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

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

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

参数属性表

使用 Get-Helpcmdlet 的 Full、Parameter 或 Online 参数时，Get-Help 显示参数属性表，其中包含有关参数的详细信息。

此信息包括使用参数时需要知道的详细信息。例如，Get-ChildItem cmdlet 的帮助主题包含以下有关其 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 参数。 Path 的 Position 设置为 0，这意味着它是一个位置参数。 Exclude 的 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 参数的默认值通常是当前目录。必需的参数永远不会有默认值。对于许多可选参数，没有默认值，因为此参数在未使用时无效。

接受多个值

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

例如，Get-Service cmdlet 的 Name 参数接受多个值。以下命令均有效：

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。