Chip 2008 June/CHIP-2008-06.iso/software/PowerShell/PowerShell_Setup_x86.msi/product.cab/about_scriptcmdletparameters.help_EN.txt

Text File | 2007-10-29 | 9.9 KB | 379 lines

TOPIC
Script Cmdlet Parameters

SHORT DESCRIPTION
How to declare script cmdlet parameters.

LONG DESCRIPTION
Script cmdlets can declare their own parameters, as well as access the
common parameters available to compiled cmdlets.

Note: Common parameters include -Verbose, -Debug, -ErrorAction,
      -ErrorVariable, and -OutVariable.

The following example shows a parameter declaration that defines a
ComputerName parameter that takes an array of strings as input, is
required, takes input from the pipeline, and its value is validated
to make sure that it is not set to Null. There are no limits to the
number of attributes that can be added to a parameter declaration.

Param
  (
    [Mandatory]
    [ValueFromPipeline]
    [String[]]
    $ComputerName
  )



When declaring parameters there are several attributes that can be added
to the parameter declaration. These include parameter metadata attributes
and parameter validation attributes.



PARAMETER METADATA ATTRIBUTES

These attributes define the characteristics of the parameter, such as is
the parameter required or optional.


Mandatory Attribute
Syntax: [Mandatory]

This attribute indicates that a value must be specified for the parameter.
If this attribute is not specified, the parameter is
an optional parameter. The following example shows the declaration of a
parameter that is required when the cmdlet is run.

  Param
  (
    [Mandatory]
    [String[]]
    $ComputerName
  )



Position Attribute
Syntax: [Position(<Int32>)]

This attribute specifies the position of the parameter. If this attribute
is not specified, the parameter name or alias must be explicitly specified
when setting the parameter. Also, if none of the parameters of a cmdlet
have positions, then the PowerShell runtime assigns positions to each
parameter based on the order that they are received.

The following example shows the parameter
declaration of a parameter whose value must be specified as the first
argument when the cmdlet is run. Notice that this cmdlet could be run with
or without specifying the name of the parameter.

  Param
  (
    [Position(0)]
    [String[]]
    $ComputerName
  )


Alias Attribute
Syntax: [Alias(<String[]>)]

This attribute specifies an alias that can be used as a short cut in
place of the parameter name. The following example shows the parameter
declaration a parameter that can be set using "ComputerName" or "CN".

  Param
  (
    [Alias("CN")]
    [String[]]
    $ComputerName
  )


ParameterSetName Attribute
Syntax: [ParameterSetName(<String>)]

This attribute specifies which parameter set a parameter belongs to. If
no parameter set is specified, the parameter belongs to all parameter
sets. Also, it is important to remember that each parameter set must
have one unique parameter that is not a member of any other parameter
set. The following example shows the parameter declaration of two
parameters that belong to two different parameter sets.

  Param
  (
    [Mandatory]
    [ParameterSetName ("Name")]
    [String[]]
    $ComputerName,

    [Mandatory]
    [ParameterSetName ("User")]
    [String[]]
    $ComputerUser
  )


For information on parameter sets, see Cmdlet Parameters in The Windows
PowerShell Programmer's Guide on MSDN.


ValueFromPipeline Attribute
Syntax: [ValueFromPipeline]

This attribute specifies that the parameter accepts input from pipeline
object. Specify this attribute if the cmdlet accesses the complete object,
not just a property of the object. The following example shows the
parameter declaration of a ComputerName parameter that accepts the input
object passed to the cmdlet through the pipeline.

  Param
  (
    [ValueFromPipeline]
    [String[]]
    $ComputerName
  )


ValueFromPipelineByPropertyName Attribute
Syntax: [ValueFromPipelineByPropertyName]

This attribute specifies that the parameter accepts input from a property
of a pipeline object. Specify this attribute if the parameter accesses a
a property of the piped-in object that has either the same name or the same
alias as this parameter. For example, if the cmdlet has a Computer Name
parameter and the piped in object has a ComputerName property, the value of
the ComputerName property is assigned to the ComputerName parameter of the
cmdlet.

The following example shows the parameter declaration of a ComputerName
parameter that accepts input from the ComputerName property of the input
object passed to the cmdlet.

  Param
  (
    [ValueFromPipelineByPropertyName]
    [String[]]
    $ComputerName
  )


ValueFromRemainingArduments Attribute
Syntax: [ValueFromRemainingArguments]

This attribute specifies that the parameter accepts all the remaining
arguments that are not bound to the parameters of the cmdlet. The
following example shows the parameter declaration of a ComputerName
parameter that accepts all the remaining arguments of the input object
passed to the cmdlet.

  Param
  (
    [ValueFromRemainingArguments]
    [Object[]]
    $ComputerName
  )


HelpMessage Attribute
Syntax: [HelpMessage(<String>)]

This attribute specifies a message that contains a short description of
the cmdlet parameter. The following example shows the parameter
declaration that provides a description of the parameter.

  Param
  (
    [HelpMessage ("An array of computer names.")]
    [String[]]
    $ComputerName
  )



PARAMETER VALIDATION ATTRIBUTES

These attributes define how the Windows PowerShell runtime validates the
values of script cmdlet parameters.


AllowNull Attribute
Syntax: [AllowNull]

Allows null as the argument of a mandatory cmdlet parameter. In the
following example, the ComputerName parameter can be Null even though
it is a mandatory parameter.

  Param
  (
    [Mandatory]
    [AllowNull]
    [String[]]
    $ComputerName
  )


AllowEmptyString Attribute
Syntax: [AllowEmptyString]

Allows an empty string as the argument of a mandatory cmdlet parameter.
In the following example, the ComputerName parameter can be an empty
string ("") even though it is a mandatory parameter.

  Param
  (
    [Mandatory]
    [AllowEmpty]
    [String]
    $ComputerName
  )


AllowEmptyCollection Attribute
Syntax: [AllowEmptyCollection]

Allows an empty collection as the argument of a mandatory cmdlet parameter.
In the folcollection even though it is a mandatory parameter.

  Param
  (
    [Mandatory]
    [AllowEmpty]
    [String]
    $ComputerName
  )


ValidateCount Attribute
Syntax: [ValidateCount(<Int32>,<Int32>)]

This attribute specifies the minimum and maximum number of arguments that
the parameter can accept. The Windows PowerShell runtime generates an
error if the number of arguments is outside that range. In the following
example, the ComputerName parameter can have 1 to 5 arguments.

  Param
  (
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
  )


ValidateLength Attribute
Syntax: [ValidateLengtht(<Int32>,<Int32>)]

This attribute specifies the minimum and maximum length of the parameter
argument. The Windows PowerShell runtime generates an error if the length
of the parameter argument is outside that range. In the following example,
the specified computer names must have 1 to 10 characters.

  Param
  (
    [ValidateLength(1,10)]
    [String[]]
    $ComputerName
  )



ValidatePattern Attribute
Syntax: [ValidatePatternt(<String)]

This attribute specifies a regular expression that validates the pattern
of the parameter argument. The Windows PowerShell runtime generates an
error if the parameter argument does not match this pattern. In the
following example, the argument of the parameter must be a four digit
number, with each digit being a number 0 to 9.

  Param
  (
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [String[]]
    $ComputerNames
  )


ValidateRange Attribute
Syntax: [ValidateRange(<Int32>,<Int32>)]

This attribute specifies the minimum and maximum values of the parameter
argument. The Windows PowerShell runtime generates an error if the
parameter argument is outside that range. In the following example, the
argument of the parameter cannot be less than 0 or grater than 10.

  Param
  (
    [ValidateRange(0, 10)]
    [Int[]]
    $Count
  )


ValidateScript Attribute
Syntax: [ValidateScript(<ScriptBlock>)]

This attribute specifies a script that is used to validate the parameter
argument. The Windows PowerShell runtime generates an error if the
script block result is false or throws an exception.


ValidateSet Attribute
Syntax: [ValidateSet(<String[]>]


This attribute specifies a set of valid values for the argument of the
parameter. The Windows PowerShell runtime generates an error if the
parameter argument does not match one of the values in the set. In the
following example, the argument of the parameter can contain only the
names Steve, Mary, and Carl.

  Param
  (
    [ValidateSet("Steve", "Mary". "Carl")]
    [String[]]
    $UserNames
  )


ValidateNotNull Attribute
Syntax: [ValidateNotNull]


This attribute specifies that the argument of the parameter cannot be
set to Null. The Windows PowerShell runtime generates an error if the
parameter value is Null.

  Param
  (
    [ValidateNotNull]
    [String[]]
    $UserNames
  )


ValidateNotNullOrEmpty Attribute
Syntax: [ValidateNotNulorEmptyl

This attribute specifies that the argument of the parameter cannot be set
to Null or empty. The Windows PowerShell runtime generates an error if the
parameter is specified but its value is Null, an empty string, or an empty
array.

  Param
  (
    [ValidateNotNullOrEmpty]
    [String[]]
    $UserNames
  )



SEE ALSO

about_ScriptCmdlets
about_ScriptCmdletAttributes
about_ScriptCmdletMethods