关于参数About Parameters

简短说明Short description

介绍如何在 PowerShell 中使用命令参数。Describes how to work with command parameters in PowerShell.

长说明Long description

大多数 PowerShell 命令(如 cmdlet、函数和脚本)都依赖于参数,以允许用户选择选项或提供输入。Most PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. 参数跟在命令名之后,格式如下:The parameters follow the command name and have the following form:

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

参数的名称前面带有连字符 ( ) ,这向 PowerShell 发出信号,表示连字符后面的单词是参数名称。The name of the parameter is preceded by a hyphen (-), which signals to PowerShell that the word following the hyphen is a parameter name. 参数名称和值可以用空格或冒号字符分隔。The parameter name and value can be separated by a space or a colon character. 某些参数不需要或接受参数值。Some parameters do not require or accept a parameter value. 其他参数需要一个值,但是在命令中不需要参数名称。Other parameters require a value, but do not require the parameter name in the command.

参数的类型和这些参数的要求各不相同。The type of parameters and the requirements for those parameters vary. 若要查找有关命令的参数的信息,请使用 Get-Help cmdlet。To find information about the parameters of a command, use the Get-Help cmdlet. 例如,若要查找有关该 cmdlet 的参数的信息 Get-ChildItem ,请键入:For example, to find information about the parameters of the Get-ChildItem cmdlet, type:

Get-Help Get-ChildItem

若要查找有关脚本的参数的信息,请使用脚本文件的完整路径。To find information about the parameters of a script, use the full path to the script file. 例如:For example:

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

Get-HelpCmdlet 返回有关命令的各种详细信息,包括说明、命令语法、有关参数的信息,以及演示如何在命令中使用参数的示例。The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command.

你还可以使用 cmdlet 的参数参数 Get-Help 查找有关特定参数的信息。You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. 或者,可以将 参数 参数与通配符 ( ) 值一起使用, * 查找有关该命令的所有参数的信息。Or, you can use the Parameter parameter with the wildcard character ( * ) value to find information about all parameters of the command. 例如,以下命令将获取有关该 cmdlet 的所有参数的信息 Get-MemberFor example, the following command gets information about all parameters of the Get-Member cmdlet:

Get-Help Get-Member -Parameter *

默认参数值Default parameter values

可选参数具有默认值,该值是在命令中未指定参数时使用或假设的值。Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command.

例如,许多 cmdlet 的 ComputerName 参数的默认值是本地计算机的名称。For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. 因此,在命令中使用本地计算机名称,除非指定 ComputerName 参数。As a result, the local computer name is used in the command unless the ComputerName parameter is specified.

若要查找默认参数值,请参阅 cmdlet 的帮助主题。To find the default parameter value, see help topic for the cmdlet. 参数说明应包含默认值。The parameter description should include the default value.

还可以为 cmdlet 或高级函数的任何参数设置自定义默认值。You can also set a custom default value for any parameter of a cmdlet or advanced function. 有关设置自定义默认值的信息,请参阅 about_Parameters_Default_ValuesFor information about setting custom default values, see about_Parameters_Default_Values.

参数属性表Parameter attribute table

当你使用 cmdlet 的 FullparameterOnline 参数时 Get-Help ,将 Get-Help 显示一个参数属性表,其中包含有关参数的详细信息。When you use the Full , Parameter , or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter.

此信息包括你需要知道使用参数的详细信息。This information includes the details you need to know to use the parameter. 例如,cmdlet 的帮助主题 Get-ChildItem 包含有关其 Path 参数的以下详细信息:For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter:

-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

参数信息包括参数语法、参数说明和参数特性。The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. 以下各节介绍参数特性。The following sections describe the parameter attributes.

必需参数Parameter Required

此设置指示参数是否是必需的,即是否所有使用此 cmdlet 的命令都必须包含此参数。This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. 如果值为 True ,并且命令中缺少参数,则 PowerShell 将提示你输入参数的值。When the value is True and the parameter is missing from the command, PowerShell prompts you for a value for the parameter.

参数位置Parameter Position

如果 Position 设置设置为正整数,则不需要参数名称。If the Position setting is set to a positive integer, the parameter name is not required. 这种类型的参数称为位置参数,数值指示参数必须与其他位置参数出现的位置。This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. 命名的参数可以在 cmdlet 名称后的任何位置中列出。A named parameter can be listed in any position after the cmdlet name. 如果包含位置参数的参数名称,则可以在 cmdlet 名称后的任何位置中列出参数。If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name.

例如, Get-ChildItem cmdlet 具有 Path 和 Exclude 参数。For example, the Get-ChildItem cmdlet has Path and Exclude parameters. Position路径 的设置为 0 ,这意味着它是一个位置参数。The Position setting for Path is 0 , which means that it is a positional parameter. Position排除 的设置 命名 为。The Position setting for Exclude is named .

这意味着该 路径 不需要参数名,但其参数值必须是命令中的第一个或唯一一个未命名的参数值。This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. 但是,因为 Exclude 参数是命名参数,你可以将其放在命令中的任意位置。However, because the Exclude parameter is a named parameter, you can place it in any position in the command.

由于 Position 这两个参数的设置,你可以使用以下任一命令:As a result of the Position settings for these two parameters, you can use any of the following commands:

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

如果要包含另一个位置参数而不包括参数名称,则该参数必须按设置指定的顺序放置 PositionIf you were to include another positional parameter without including the parameter name, that parameter must be placed in the order specified by the Position setting.

参数类型Parameter Type

此设置指定参数值的 Microsoft .NET 框架类型。This setting specifies the Microsoft .NET Framework type of the parameter value. 例如,如果类型为 Int32 ,则参数值必须是整数。For example, if the type is Int32 , the parameter value must be an integer. 如果类型为 string,则参数值必须为字符串。If the type is string, the parameter value must be a character string. 如果字符串包含空格,则必须用引号将该值引起来,或者必须在空格前面加上转义符 ( ") 。If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character ( ` ).

默认值Default Value

如果未提供其他值,则此设置将指定参数将假设的值。This setting specifies the value that the parameter will assume if no other value is provided. 例如,Path 参数的默认值通常为当前目录。For example, the default value of the Path parameter is often the current directory. 必需的参数决不会有默认值。Required parameters never have a default value. 对于许多可选参数,没有默认值,因为如果不使用参数,则该参数不起作用。For many optional parameters, there is no default because the parameter has no effect if it is not used.

接受多个值Accepts Multiple Values

此设置指示参数是否接受多个参数值。This setting indicates whether a parameter accepts multiple parameter values. 当参数接受多个值时,可以在命令中键入以逗号分隔的列表作为参数的值,或将逗号分隔的列表保存 (数组中的数组) ,然后将该变量指定为参数值。When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value.

例如,cmdlet 的 ServiceName 参数 Get-Service 接受多个值。For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. 以下命令都是有效的:The following commands are both valid:

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

接受管道输入Accepts Pipeline Input

此设置指示是否可以使用管道运算符 ( ) 将 | 值发送到参数。This setting indicates whether you can use the pipeline operator ( | ) to send a value to the parameter.

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 (值) " 时,PowerShell 会尝试将任何管道值与该参数相关联,然后再尝试其他方法来解释该命令。When a parameter is "True (by Value)", PowerShell tries to associate any piped values with that parameter before it tries other methods to interpret the command.

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 参数。For example, you can pipe a value to a Name parameter only when the value has a property called Name .

备注

一个类型化参数,该参数接受管道输入 (by Value) 或 (by PropertyName) 允许在参数上使用 延迟绑定 脚本块。A typed parameter that accepts pipeline input (by Value) or (by PropertyName) enables use of delay-bind script blocks on the parameter.

延迟绑定 脚本块在 ParameterBinding 期间自动运行。The delay-bind script block is run automatically during ParameterBinding . 结果绑定到参数。The result is bound to the parameter. 延迟绑定对于定义为类型或的参数 起作用 ScriptBlock ,不 System.Object 调用脚本块。 withoutDelay binding does not work for parameters defined as type ScriptBlock or System.Object, the script block is passed through without being invoked.

你可以在此处了解 about_Script_Blocks 的 延迟绑定 脚本块 You can read about delay-bind script blocks here about_Script_Blocks.md

接受通配符Accepts Wildcard Characters

此设置指示参数的值是否可以包含通配符,使参数值可以与目标容器中的多个现有项匹配。This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container.

通用参数Common Parameters

常见参数是可与任何 cmdlet 一起使用的参数。Common parameters are parameters that you can use with any cmdlet. 有关常见参数的详细信息,请参阅 about_CommonParametersFor more information about common parameters, see about_CommonParameters.

另请参阅See also

about_Command_syntaxabout_Command_syntax

about_Comment_Based_Helpabout_Comment_Based_Help

about_Functions_Advancedabout_Functions_Advanced

about_Parameters_Default_Valuesabout_Parameters_Default_Values

about_pipelinesabout_Pipelines

about_Wildcardsabout_Wildcards