TEMA
    about_Functions_Advanced_Parameters

DESCRIPCIÓN BREVE
    Explica cómo agregar parámetros estáticos y dinámicos a las funciones que 
    declaran el atributo CmdletBinding.

DESCRIPCIÓN DETALLADA
    Puede declarar sus propios parámetros al escribir las funciones, 
    y también escribir las funciones de tal forma que puedan tener 
    acceso a los parámetros comunes que están disponibles para los cmdlets 
    compilados. Para obtener más información sobre los parámetros comunes 
    de Windows PowerShell, vea about_CommonParameters.

Parámetros estáticos

    En el ejemplo siguiente se muestra una declaración de parámetro 
    que define un parámetro ComputerName. Este parámetro tiene las 
    características siguientes:

        - Es obligatorio.
        - Toma la entrada de la canalización.
        - Toma una matriz de cadenas como entrada.

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

    El único atributo obligatorio que se debe utilizar al declarar un 
    parámetro es el atributo Parameter. Sin embargo, también es 
    posible declarar el atributo Alias y varios argumentos de 
    validación. No hay ningún límite en cuanto al número de atributos 
    que se pueden agregar a una declaración de parámetro.


  Atributo Parameter

      El atributo Parameter se utiliza para declarar un parámetro de 
      la función.
      Este atributo tiene los argumentos con nombre siguientes, que 
      se utilizan para definir las características del parámetro, 
      como si es obligatorio u opcional.


    Argumento con nombre Mandatory

        El argumento Mandatory indica que el parámetro se necesita 
        cuando se ejecuta la función. Si no se especifica este argumento, 
        significa que el parámetro es opcional. En el ejemplo siguiente se 
        muestra la declaración de un parámetro que es necesario al ejecutar 
        la función.

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


    Argumento con nombre Position

        El argumento Position especifica la posición del parámetro. 
        Si no se especifica este argumento, se debe especificar 
        explícitamente el nombre del parámetro o su alias al establecer el 
        parámetro. Además, si ninguno de los parámetros de una función tiene 
        posiciones, el motor de tiempo de ejecución de Windows PowerShell se 
        las asigna según el orden en el que se recibe cada uno de ellos. 

        En el ejemplo siguiente se muestra la declaración de un 
        parámetro cuyo valor se debe especificar como el primer 
        argumento cuando se ejecuta el cmdlet. Observe que esta función se 
        podría ejecutar aunque no se especifique el nombre del parámetro.

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


    Argumento con nombre ParameterSetName

        El argumento ParameterSetName especifica el conjunto de 
        parámetros al que pertenece un parámetro. Si no se especifica 
        ningún conjunto de parámetros, el parámetro pertenece a todos los 
        conjuntos de parámetros definidos por la función. Este comportamiento 
        significa que cada conjunto de parámetros debe tener un parámetro 
        único que no sea miembro de ningún otro conjunto de parámetros. En el 
        ejemplo siguiente se muestra la declaración de dos parámetros que 
        pertenecen a dos conjuntos de parámetros diferentes. 

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Equipo")] 
            [String[]]
            $ComputerName
          ) 

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Usuario")] 
            [String[]]
            $UserName
          ) 

        Para obtener más información sobre los conjuntos de 
        parámetros, vea "Cmdlet Parameter Sets" en MSDN Library, en 
        https://go.microsoft.com/fwlink/?LinkId=142183.


    Argumento con nombre ValueFromPipeline

        El argumento ValueFromPipeline especifica que el parámetro acepta 
        entrada procedente de un objeto de la canalización. Este argumento se 
        debe especificar si el cmdlet tiene acceso al objeto completo, no 
        simplemente a una propiedad del objeto. En el ejemplo siguiente se 
        muestra la declaración de parámetro de un parámetro ComputerName 
        obligatorio que acepta el objeto de entrada que se pasa a la función 
        desde la canalización.

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


    Argumento con nombre ValueFromPipelineByPropertyName

        El argumento valueFromPipelineByPropertyName especifica que 
        el parámetro acepta entrada procedente de una propiedad de un 
        objeto de la canalización. Este atributo se debe especificar si se 
        cumplen las condiciones siguientes:

            - El parámetro tiene acceso a una propiedad del objeto canalizado.

            - La propiedad tiene el mismo nombre que el parámetro o 
              la propiedad tiene el mismo alias que el parámetro.

        Por ejemplo, si la función tiene un parámetro ComputerName y 
        el objeto canalizado tiene una propiedad ComputerName, el 
        valor de la propiedad ComputerName se asigna al parámetro 
        ComputerName de la función.

        En el ejemplo siguiente se muestra la declaración de un parámetro 
        ComputerName que acepta la entrada procedente de la propiedad 
        ComputerName del objeto de entrada que se pasa al cmdlet.

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


    Argumento con nombre ValueFromRemainingArguments

        El argumento ValueFromRemainingArguments especifica que el 
        parámetro acepta todos los argumentos restantes que no están 
        enlazados a los parámetros de la función. En el ejemplo 
        siguiente se muestra la declaración de un parámetro 
        ComputerName que acepta todos los argumentos restantes del 
        objeto de entrada que se pasa a la función.

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


    Argumento con nombre HelpMessage

        El argumento HelpMessage especifica un mensaje que contiene una 
        descripción breve del parámetro. En el ejemplo siguiente se muestra una 
        declaración de parámetro que proporciona una descripción del parámetro.

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage="Matriz de nombres de equipos.")] 
                      [String[]]
            $ComputerName
          ) 


     Atributo Alias

      El atributo Alias especifica otro nombre para el parámetro. No 
      hay ningún límite con respecto al número de alias que se pueden 
      asignar a un parámetro. En el ejemplo siguiente se muestra una 
      declaración de parámetro obligatorio que agrega el alias "CN" 
      al parámetro ComputerName.

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


    Atributos de validación de parámetros

      Estos atributos definen cómo validará el motor de tiempo de 
      ejecución de Windows PowerShell los argumentos de las funciones 
      avanzadas.


    Atributo de validación AllowNull

        El atributo AllowNull permite establecer en Null el argumento 
        de un parámetro de cmdlet obligatorio. En el ejemplo siguiente, el 
        parámetro ComputerName puede contener un valor Null aunque sea un 
        parámetro obligatorio. 

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


    Atributo de validación AllowEmptyString

        El atributo AllowEmptyString permite usar una cadena vacía como 
        argumento de un parámetro de cmdlet obligatorio. En el ejemplo 
        siguiente, el parámetro ComputerName puede contener una cadena vacía 
        ("") aunque sea un parámetro obligatorio. 

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


    Atributo de validación AllowEmptyCollection

        El atributo AllowEmptyCollection permite usar una colección 
        vacía como argumento de un parámetro obligatorio. 

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


    Atributo de validación ValidateCount

        El atributo ValidateCount especifica el número mínimo y máximo de 
        argumentos que el parámetro puede aceptar. El motor de tiempo de 
        ejecución de Windows PowerShell genera un error si el número de 
        argumentos queda fuera de ese intervalo. En el ejemplo siguiente, el 
        parámetro ComputerName puede tener entre uno y cinco argumentos. 

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


    Atributo de validación ValidateLength

        El atributo ValidateLength especifica la longitud mínima y 
        máxima del argumento del parámetro. El motor de tiempo de 
        ejecución de Windows PowerShell genera un error si la longitud del 
        argumento del parámetro queda fuera de ese intervalo.
        En el ejemplo siguiente, los nombres de equipo especificados 
        deben tener entre uno y diez caracteres. 

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


    Atributo de validación ValidatePattern

        El atributo ValidatePattern especifica una expresión regular 
        que valida el patrón del argumento del parámetro. El motor de 
        tiempo de ejecución de Windows PowerShell genera un error si el 
        argumento del parámetro no coincide con este patrón. En el ejemplo 
        siguiente, el argumento del parámetro debe ser un número de cuatro 
        dígitos y cada dígito debe ser un número del 0 al 9. 

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


    Atributo de validación ValidateRange

        El atributo ValidateRange especifica los valores mínimo y 
        máximo del argumento del parámetro. El motor de tiempo de 
        ejecución de Windows PowerShell genera un error si el 
        argumento del parámetro queda fuera de ese intervalo. En el 
        ejemplo siguiente, el argumento del parámetro no puede ser 
        menor que 0 ni mayor que 10. 


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


    Atributo de validación ValidateScript

        El atributo ValidateScript especifica un script que se 
        utiliza para validar el argumento del parámetro. El motor de 
        tiempo de ejecución de Windows PowerShell genera un error si el 
        resultado del script es false o si el script inicia una excepción. En 
        el ejemplo siguiente, el valor del parámetro Count debe ser menor que 4.

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


    Atributo ValidateSet

        El atributo ValidateSet especifica un conjunto de valores 
        válidos para el argumento del parámetro. El motor de tiempo 
        de ejecución de Windows PowerShell genera un error si el 
        argumento del parámetro no coincide con un valor del conjunto.
        En el ejemplo siguiente, el argumento del parámetro puede contener 
        solamente los nombres Esteban, María y Carlos. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange("Esteban", "María", "Carlos")] 
            $UserName
          ) 


    Atributo de validación ValidateNotNull


        El atributo ValidateNotNull especifica que el argumento del 
        parámetro no puede se establecer en Null. El motor de tiempo de 
        ejecución de Windows PowerShell genera un error si el valor del 
        parámetro es Null.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNull()]
            $UserName
          ) 


    Atributo de validación ValidateNotNullOrEmpty

        El atributo ValidateNotNullOrEmpty especifica que el argumento del 
        parámetro no puede establecerse en Null ni estar vacío. El motor de 
        tiempo de ejecución de Windows PowerShell genera un error si se 
        especifica el parámetro pero su valor es Null, una cadena vacía o una 
        matriz vacía.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNullOrEmpty()]
            $UserName
          ) 


    Parámetros dinámicos

        Los parámetros dinámicos son parámetros de cmdlet, de función o de  
        script, que solo están disponibles bajo determinadas condiciones. Por 
        ejemplo, algunos cmdlets de proveedores tienen parámetros que sólo 
        están disponibles cuando el cmdlet se usa en la ruta de acceso del 
        proveedor. Un parámetro dinámico muy conocido es el parámetro Encoding 
        del cmdlet Set-Item, que está disponible solo cuando el cmdlet Set-Item 
        se utiliza en una ruta de acceso del proveedor FileSystem. Para crear 
        un parámetro dinámico de una función o un script, utilice la palabra 
        clave DynamicParam. La sintaxis es la siguiente:



        Dynamicparam {<lista-instrucciones>} 


        De la lista de instrucciones, utilice una instrucción If para 
        especificar las condiciones bajo las que el parámetro está disponible 
        en la función. Use el cmdlet New-Object para crear un objeto 
        System.Management.Automation.RuntimeDefinedParameter que represente el 
        parámetro y especifique su nombre. Se puede utilizar un comando 
        New-Object para crear un objeto 
        System.Management.Automation.ParameterAttribute que represente los 
        atributos del parámetro, como son Mandatory, Position, 
        ValueFromPipeline o su conjunto de parámetros. En el siguiente ejemplo 
        se muestra una función de ejemplo con parámtros estándar denominados 
        Name y Path, y un parámetro dinámico opcional denominado DP1. El 
        parámetro DP1 está en el conjunto de parámetros PSet1 y tiene un tipo 
        de Int32. El parámetro DP1 solo está disponible en la función Sample 
        cuando el valor del parámetro Path contiene "HKLM:", lo que indica que 
        se está utilizando la unidad de registro HKEY_LOCAL_MACHINE. 


        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
        }
      } 
        Para obtener más información, vea 
        System.Management.Automation.PSCmdlet.WriteVerbose en MSDN 
        Library,en https://go.microsoft.com/fwlink/?LinkId=145130. 


       VEA TAMBIÉN
       about_Functions_Advanced
       about_Functions_CmdletBindingAttribute
       about_Functions_Advanced_Methods  




Tabla de contenido