Software: Apache. PHP/5.5.15 

uname -a: Windows NT SVR-DMZ 6.1 build 7600 (Windows Server 2008 R2 Enterprise Edition) i586 

SYSTEM 

Safe-mode: OFF (not secure)

C:\Windows\SysWOW64\WindowsPowerShell\v1.0\en-US\   drwxrwxrwx
Free 4.1 GB of 39.52 GB (10.37%)
Detected drives: [ a ] [ c ] [ d ] [ e ] [ f ]
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     about_functions_advanced_parameters.help.txt (15.76 KB)      -rw-rw-rw-

TOPIC
    about_Functions_Advanced_Parameters

SHORT DESCRIPTION
    Explains how to add static and dynamic parameters to functions that declare 
    the CmdletBinding attribute.

LONG DESCRIPTION
    You can declare your own parameters when you write functions, and you can 
    write functions so that they can access the common parameters that are 
    available to compiled cmdlets. For more information about the 
    Windows PowerShell common parameters, see about_CommonParameters.


 
 Static Parameters

    The following example shows a parameter declaration that defines a 
    ComputerName parameter. This parameter has the following characteristics:

        - It is required.
        - It takes input from the pipeline.
        - It takes an array of strings as input.

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          ) 
  

    The only required attribute that must be used when you declare a parameter
    is the Parameter attribute. However, you can also declare the Alias 
    attribute and several validation arguments. There are no limits to the 
    number of attributes that you can add to a parameter declaration.


  Parameter Attribute

      The Parameter attribute is used to declare a parameter of the function.
      This attribute has the following named arguments that are used to define
      the characteristics of the parameter, such as whether the parameter is
      required or optional.


    Mandatory Named Argument

        The Mandatory argument indicates that the parameter is required when
        the function is run. If this argument is not specified, the parameter 
        is an optional parameter. The following example shows the declaration
        of a parameter that is required when the function is run.

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          ) 


    Position Named Argument

        The Position argument specifies the position of the parameter. If this
        argument is not specified, the parameter name or its alias must be 
        explicitly specified when the parameter is set. Also, if none of the 
        parameters of a function have positions, the Windows PowerShell runtime
        assigns positions to each parameter based on the order in which the 
        parameters are received. 

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

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


    ParameterSetName Named Argument

        The ParameterSetName argument specifies the parameter set to which a 
        parameter belongs. If no parameter set is specified, the parameter 
        belongs to all the parameter sets defined by the function. This 
        behavior means 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
          (
            [parameter(Mandatory=$true,
                      ParameterSetName=”Computer”)]
            [String[]]
            $ComputerName
          ) 

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName=”User”)]
            [String[]]
            $UserName
          ) 

        For more information about parameter sets, see "Cmdlet Parameter Sets" 
        in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142183.


    ValueFromPipeline Named Argument

        The ValueFromPipeline argument specifies that the parameter accepts 
        input from a pipeline object. Specify this argument if the cmdlet 
        accesses the complete object, not just a property of the object. The
        following example shows the parameter declaration of a mandatory 
        ComputerName parameter that accepts the input object that is passed
        to the function from the pipeline.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          ) 


    ValueFromPipelineByPropertyName Named Argument

        The valueFromPipelineByPropertyName argument specifies that the 
        parameter accepts input from a property of a pipeline object. Specify
        this attribute if the following conditions are true:

            - The parameter accesses a property of the piped object.

            - The property has the same name as the parameter, or the property
              has the same alias as the parameter.

        For example, if the function has a ComputerName parameter, and the 
        piped object has a ComputerName property, the value of the ComputerName
        property is assigned to the ComputerName parameter of the function.

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

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)]
            [String[]]
            $ComputerName
          ) 


    ValueFromRemainingArguments Named Argument

        The ValueFromRemainingArguments argument specifies that the parameter
        accepts all of the remaining arguments that are not bound to the 
        parameters of the function. The following example shows the parameter 
        declaration of a ComputerName parameter that accepts all the remaining
        arguments of the input object that is passed to the function.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)]
            [String[]]
            $ComputerName
          ) 


    HelpMessage Named Argument

        The HelpMessage argument specifies a message that contains a short 
        description of the parameter. The following example shows a parameter 
        declaration that provides a description of the parameter.

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage=”An array of computer names.”)]
            [String[]]
            $ComputerName
          ) 


  Alias Attribute

      The Alias attribute specifies another name for the parameter. There is 
      no limit to the number of aliases that can be assigned to a parameter. 
      The following example shows a mandatory parameter declaration that adds 
      the "CN" alias to the ComputerName parameter.

        Param
          (
            [parameter(Mandatory=$true)]
            [alias(“CN”)]
            [String[]]
            $ComputerName
          ) 


  Parameter Validation Attributes

      These attributes define how the Windows PowerShell runtime validates the 
      arguments of advanced functions.


    AllowNull Validation Attribute

        The AllowNull attribute allows the argument of a mandatory cmdlet 
        parameter to be set to Null. In the following example, the ComputerName
        parameter can  contain a value of Null even though this parameter is a 
        mandatory parameter.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String]
            [AllowNull()]
            $ComputerName
          ) 


    AllowEmptyString Validation Attribute

        The AllowEmptyString attribute allows an empty string as the argument
        of a mandatory cmdlet parameter. In the following example, the 
        ComputerName parameter can contain an empty string ("") even though
        this parameter is a mandatory parameter.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String]
            [AllowEmptyString()]
            $ComputerName
          ) 


    AllowEmptyCollection Validation Attribute

        The AllowEmptyCollection attribute allows an empty collection as the
        argument of a mandatory parameter. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [AllowEmptyCollection()]
            $ComputerName
          ) 


    ValidateCount Validation Attribute

        The ValidateCount 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
        one to five arguments.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateCount(1,5)]
            $ComputerName
          ) 


    ValidateLength Validation Attribute

        The ValidateLength 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 one
        to 10 characters. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateLength(1,10)]
            $ComputerName
          ) 


    ValidatePattern Validation Attribute

        The ValidatePattern 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, and each digit must be a number 0 to 9.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            $ComputerName
          ) 


    ValidateRange Validation Attribute

        The ValidateRange 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 greater than 10.  


        Param
          (
            [parameter(Mandatory=$true)]
            [Int[]]
            [ValidateRange(0,10)]
            $Count
          ) 


    ValidateScript Validation Attribute

        The ValidateScript attribute specifies a script that is used to 
        validate the parameter argument. The Windows PowerShell runtime
        generates an error if the script result is false or if the script
        throws an exception. In the following example the value of the Count
        parameter must be less than 4.

        Param
          (
            [parameter()]
            [Int]
            [ValidateScript({$_ -lt 4})]
            $Count
          ) 


    ValidateSet Attribute

        The ValidateSet attribute secifies 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 a value in the set.
        In the following example, the argument of the parameter can contain 
        only the names Steve, Mary, and Carl.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange(“Steve”, “Mary”, “Carl”)]
            $UserName
          ) 


    ValidateNotNull Validation Attribute


        The ValidateNotNull 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
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNull()]
            $UserName
          ) 


    ValidateNotNullOrEmpty Validation Attribute

        The ValidateNotNullOrEmpty attribute specifies that the argument of 
        the parameter cannot be set to Null or it cannot be 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
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNullOrEmpty()]
            $UserName
          ) 


 Dynamic Parameters 

    Dynamic parameters are parameters of a cmdlet, function, or script
    that are available only under certain conditions. 

    For example, several provider cmdlets have parameters that are
    available only when the cmdlet is used in the provider path.
    One familiar dynamic parameter is the Encoding parameter of the 
    Set-Item, cmdlet, which is available only when the Set-Item cmdlet
    is used in a FileSystem provider path.

    To create a dynamic parameter for a function or script, use the 
    DynamicParam keyword.

    The syntax is as follows.

      DynamicParam {<statement-list>} 

    In the statement list, use an If statement to specify the
    conditions under which the parameter is available in the function.

    Use the New-Object cmdlet to create a 
    System.Management.Automation.RuntimeDefinedParameter object to 
    represent the parameter and specify its name. 

    You can also use a New-Object command to create a 
    System.Management.Automation.ParameterAttribute object to represent
    attributes of the parameter, such as Mandatory, Position, or
    ValueFromPipeline or its parameter set.

    The following example shows a sample function with standard 
    parameters called Name and Path, and an optional dynamic parameter
    named DP1. The DP1 parameter is in the PSet1 parameter set and has
    a type of Int32. The DP1 parameter is available in the Sample
    function only when the value of the Path parameter contains "HKLM:",
    indicating that it is being used in the HKEY_LOCAL_MACHINE registry
    drive.
 

    function Sample {
      Param ([String]$Name, [String]$Path)

      DynamicParam
      {
        if ($path -match "*HKLM*:")
        {
          $dynParam1 = new-object 
            System.Management.Automation.RuntimeDefinedParameter("dp1",
            [Int32], $attributeCollection)

          $attributes = new-object System.Management.Automation.ParameterAttribute
          $attributes.ParameterSetName = 'pset1'
          $attributes.Mandatory = $false

          $attributeCollection = new-object 
            -Type System.Collections.ObjectModel.Collection``1[System.Attribute]
          $attributeCollection.Add($attributes)
 
          $paramDictionary = new-object 
            System.Management.Automation.RuntimeDefinedParameterDictionary
          $paramDictionary.Add("dp1", $dynParam1)
        
          return $paramDictionary
        } End if
      }
    }  

    For more information, see "RuntimeDefinedParameter Class" in 
    the MSDN (Microsoft Developer Network) library at
    http://go.microsoft.com/fwlink/?LinkID=145130.        



SEE ALSO
    about_Advanced Functions
    about_Functions_Advanced_Methods
    about_Functions_CmdletBindingAttribute