Sie sind auf Seite 1von 8

TOPIC

about_Parameters

SHORT DESCRIPTION Describes how to work with cmdlet parameters in Windows PowerShell.

LONG DESCRIPTION Most Windows PowerShell cmdlets and functions r ely on parameters to allow users to select options or provide input. The p arameters follow the cmdlet or function name and typically have the followi ng form:

-<parameter_name> <parameter_value>

The name of the parameter is preceded by a hyph en (-), which signals to Windows PowerShell that the word following the hyphen is a parameter and not a value being passed to the cmdlet or funct ion. Not all parameters require a value, and not all parameter names mu st be specified. In some cases, the parameter name is implied and does n ot need to be included in the command.

The type of parameters and the requirements for those parameters vary by cmdlet and by function from cmdlet to cmdlet. T o find information about the parameters of a cmdlet, use the Get-Help cmdlet . For example, to find information about the parameters of the Get-Chi ldItem cmdlet, type:

get-help get-childitem

To find information about the parameters of a f unction, review the parameter definitions. Parameters are defined e ither after the function name or inside the body of the function, using the Param keyword. For more information, see about_Functions.

Some functions also contain comment-based Help about parameters. Use the Get-Help cmdlet with these functions. For more information, see the help topic for Get-Help and about_Comment_Based_Help

.

The Get-Help Cmdlet returns various details abo ut the cmdlet or function, including a description of the cmdlet or functi on, the command syntax, information about the parameters, and examples showing how to use the cmdlet or function.

You can also use the Parameter parameter of the Get-Help cmdlet or function to find information about a particular paramete r. Or, you can use the wildcard character (*) with the Parameter param eter to find information about all the parameters of the cmdlet or funct ion. For example, the following command gets information about all th e parameters of the Get-Member cmdlet or function:

get-help get-member -parameter *

This information includes the details you need to know to use the parameter. For example, the Help topic for the Get-ChildItem cmdlet includes the following details about its Path p arameter:

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

ory

Required?

false

Position?

1

Default value

Current direct

Accept pipeline input?

true (ByValue,

ByPropertyName) Accept wildcard characters? true

The parameter information includes the paramete r syntax, a description of the parameter, and the paramet er attributes. The following sections describe the parameter a ttributes.

Parameter Required? This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet m ust include this parameter. When the value is "True" and the par ameter is missing from the command, Windows PowerShell prompts yo

u

for a value for the parameter.

Parameter Position?

This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. I

f

set to "0" or "named,"

a parameter name is required. This type of para meter is referred to as

a named parameter. A named parameter can be lis ted in any position after the cmdlet name.

If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type o

f parameter is referred to as a positional parameter, and the number in dicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name f or a positional parameter, the parameter can be listed in any p osition after the cmdlet name.

For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1 , which means that it is a positional parameter. The "Parameter posit ion?" setting for Exclude is 0, which means that it is a named parameter.

This means that Path does not require the param

eter name, but its parameter value must be the first or only unnam ed parameter value in the command. However, because the Exclude pa rameter is a named parameter, you can place it in any position in the command.

As a result of the "Parameter position?" settin gs for these two parameters, you can use any of the following co mmands:

ppt

ocs

Get-ChildItem -path c:\techdocs -exclude *.

Get-ChildItem c:\techdocs -exclude *.ppt Get-ChildItem -exclude *.ppt -path c:\techd

Get-ChildItem -exclude *.ppt c:\techdocs

If you were to include another positional param eter without including the parameter name, that parameter would have t o be placed in the order specified by the "Parameter position?" setting.

Parameter Type This setting specifies the Microsoft .NET Frame work type of the parameter value. For example, if the type is Int32, the p arameter value must be an integer. If the type is string, the parameter v alue 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 param eter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directo ry. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has n

o effect if it is not used.

Accepts Multiple Values? This setting indicates whether a parameter acce pts multiple parameter values. When a parameter accepts mult iple values, you can type a comma-separated list as the valu

e 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.

For example, the ServiceName parameter of the G

et-Service

cmdlet accepts multiple values. The following c ommands 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 ----- False not pipe a value to the

Description ----------- Indicates that you can

parameter.

Indicates that you can

parameter, just so the

Framework type specifi ed for the parameter or the value can be converted

True (by Value) pipe any value to the

value has the .NET

to the specified .NET

Framework type.

When a parameter is "T

PowerShell tries to as

with that parameter be fore it tries other methods to interpret the comma

sociate any piped values

rue (by Value)", Windows

nd.

True (by Property Name) Indicates that you can pipe a value to the

parameter, but the .NE

parameter must include

a property with the same

T Framework type of the

name as the parameter.

ipe a value to a Name

e value has a property

For example, you can p

parameter only when th

called "Name".

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 Common parameters are parameters that you can u se with any cmdlet. For more information, about common parameters, type:

help about_commonparameters

SEE ALSO about_Command_syntax about_Comment_Based_Help about_Functions_Advanced about_Pipelines about_Wildcards