about_Functions_Advanced_Parameters

Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TEMA

Insertar el cuerpo de la sección aquí.

DESCRIPCIÓN BREVE

Explica cómo agregar parámetros a funciones avanzadas.

DESCRIPCIÓN LARGA

Puede agregar parámetros a las funciones avanzadas que escriba y usar argumentos y atributos de parámetro para limitar los valores de parámetro que los usuarios de la función envían con el parámetro.

Los parámetros que se agregan a la función están disponibles para los usuarios además de los parámetros comunes que Windows PowerShell® agrega automáticamente a todos los cmdlets y funciones avanzadas. Para más información sobre los parámetros comunes de Windows PowerShell, consulte about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

A partir de Windows PowerShell 3.0, puede usar la expansión con @Args para representar los parámetros de un comando. Esta técnica es válida en funciones simples y avanzadas. Para obtener más información, vea about_Functions (https://go.microsoft.com/fwlink/?LinkID=113231) y about_Splatting (https://go.microsoft.com/fwlink/?LinkID=262720).

PARÁMETROS ESTÁTICOS

Los parámetros estáticos son parámetros que están siempre disponibles en la función. La mayoría de los parámetros de los cmdlets y scripts de Windows PowerShell son parámetros estáticos.

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

Es obligatorio.

Toma entrada de la canalización.

Toma una matriz de cadenas como entrada.

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

ATRIBUTOS DE PARÁMETROS

En esta sección se describen los atributos que se pueden agregar a los parámetros de función.

Todos los atributos son opcionales. Sin embargo, si se omite el atributo CmdletBinding, para que la función se reconozca como función avanzada, debe incluir el atributo Parameter.

Puede agregar uno o varios atributos en cada declaración de parámetro. No hay límite al número de atributos que se pueden agregar a una declaración de parámetro.

EL ATRIBUTO PARAMETER

El atributo Parameter se usa para declarar los atributos de parámetros de función.

El atributo Parameter es opcional y se puede omitir si ninguno de los parámetros de las funciones necesitan atributos, pero para que una función se reconozca como función avanzada (en lugar de como función sencilla), debe tener el atributo CmdletBinding, el atributo Parameter o ambos.

El atributo Parameter tiene argumentos que definen las características del parámetro, por ejemplo, si el parámetro es obligatorio u opcional.

Use la sintaxis siguiente para declarar el atributo Parameter, un argumento y un valor de argumento. Los paréntesis que rodean el argumento y su valor deben aparecer después de "Parameter" sin espacios intermedios.

        Param
          (
            [parameter(Argument=value)]
            $ParameterName
          )

Use comas para separar los argumentos entre paréntesis. Use la sintaxis siguiente para declarar dos argumentos del atributo Parameter.

        Param
          (
            [parameter(Argument1=value1,
                       Argument2=value2)]

          )

Si usa el atributo Parameter sin argumentos (como una alternativa al uso del atributo CmdletBinding), los paréntesis que siguen al nombre de atributo siguen siendo necesarios.

        Param
          (
            [parameter()]
            $ParameterName
          )

Argumento Mandatory

El argumento Mandatory indica que el parámetro es necesario. Si no se especifica este argumento, el parámetro es un parámetro opcional.

En el ejemplo siguiente se declara el parámetro ComputerName. Usa el argumento Mandatory para hacer que el parámetro sea obligatorio.

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

Argumento Position

El argumento Position determina si el nombre del parámetro es necesario cuando el parámetro se usa en un comando. Cuando una declaración de parámetro incluye el argumento Position, se puede omitir el nombre del parámetro y Windows PowerShell identifica el valor del parámetro sin nombre por su posición (u orden) en la lista de valores de parámetro sin nombre del comando.

Si no se especifica el argumento Position, el nombre del parámetro (o una abreviatura o alias de nombre de parámetro) debe preceder al valor del parámetro cada vez que el parámetro se use en un comando.

De forma predeterminada, todos los parámetros de función son posicionales. Windows PowerShell asigna números de posición a los parámetros en el orden en que los parámetros se declaran en la función. Para deshabilitar esta característica, establezca el valor del argumento PositionalBinding del atributo CmdletBinding en $False. El argumento Position tiene prioridad con respecto al valor del argumento PositionalBinding para los parámetros en los que se declara. Para obtener más información, vea PositionalBinding en about_Functions_CmdletBindingAttribute.

El valor del argumento Position se especifica como un entero. Un valor de posición de 0 representa la primera posición en el comando, un valor de posición de 1 representa la segunda posición en el comando, y así sucesivamente.

Si una función no tiene ningún parámetro posicional, Windows PowerShell asigna las posiciones a cada parámetro según el orden en que se declaran los parámetros. Sin embargo, se recomienda no confiar en esta asignación. Cuando desee que los parámetros sean posicionales, use el argumento Position.

En el ejemplo siguiente se declara el parámetro ComputerName. Usa el argumento Position con un valor de 0. Como resultado, cuando "-ComputerName" se omite del comando, su valor debe ser el primer o el único valor de parámetro sin nombre del comando.

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

NOTA:

Cuando el cmdlet Get-Help muestra el atributo de parámetro "Position?" correspondiente, el valor de posición se incrementa en 1. Por ejemplo, un parámetro con un valor de argumento Position de 0 tiene un atributo de parámetro de "Position? 1."

Argumento 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 que define la función. Por lo tanto, para que sean único, cada conjunto de parámetros debe tener al menos un parámetro que no sea miembro de otro conjunto de parámetros.

En el ejemplo siguiente se declara un parámetro ComputerName en el conjunto de parámetros Computer, un parámetro UserName en el conjunto de parámetros User y un parámetro Summary en ambos conjuntos de parámetros.

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

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

            [parameter(Mandatory=$false)]
            [Switch]
            $Summary
          )

Puede especificar solo un valor ParameterSetName en cada argumento y solo un argumento ParameterSetName en cada atributo Parameter. Para indicar que un parámetro aparece en más de un conjunto de parámetros, agregue otros atributos Parameter.

El ejemplo siguiente agrega explícitamente el parámetro Summary a los conjuntos de parámetros Computer y User. El parámetro Summary es obligatorio en un conjunto de parámetros y opcional en el otro.

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

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

            [parameter(Mandatory=$false, ParameterSetName="Computer")]
            [parameter(Mandatory=$true, ParameterSetName="User")]
            [Switch]
            $Summary
          )
        

Para obtener más información sobre los conjuntos de parámetros, vea "Conjuntos de parámetros de cmdlet" en la biblioteca MSDN en https://go.microsoft.com/fwlink/?LinkId=142183.

Argumento ValueFromPipeline

El argumento ValueFromPipeline indica que el parámetro acepta la entrada de un objeto de canalización. Especifique este argumento si la función acepta todo el objeto, no solo una propiedad del objeto.

En el ejemplo siguiente se declara un parámetro ComputerName que es obligatorio y acepta un objeto que se pasa a la función desde la canalización.

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

Argumento ValueFromPipelineByPropertyName

El argumento valueFromPipelineByPropertyName indica que el parámetro acepta la entrada de una propiedad de un objeto de canalización. La propiedad del objeto debe tener el mismo nombre o 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 declara un parámetro ComputerName que es obligatorio y acepta la entrada de la propiedad ComputerName del objeto que se pasa a la función a través de la canalización.

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

Argumento ValueFromRemainingArguments

El argumento ValueFromRemainingArguments indica que el parámetro acepta todos los valores de parámetros del comando que no están asignados a otros parámetros de la función.

En el ejemplo siguiente se declara un parámetro ComputerName que es obligatorio y acepta todos los valores de parámetro restantes que se enviaron a la función.

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

Argumento HelpMessage

El argumento HelpMessage especifica una cadena que contiene una descripción breve del parámetro o su valor. Windows PowerShell muestra este mensaje en el símbolo del sistema que aparece cuando en un comando falta un valor de parámetro obligatorio. Este argumento no afecta de ningún modo a los parámetros opcionales.

En el ejemplo siguiente se declara un parámetro ComputerName obligatorio y un mensaje de ayuda que explica el valor de parámetro que se espera.

        Param
          (
            [parameter(mandatory=$true,
                       HelpMessage="Enter one or more computer names separated by commas.")]
            [String[]]
            $ComputerName
          )

ATRIBUTO ALIAS

El atributo Alias establece un nombre alternativo para el parámetro. No hay límite 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 que agrega los alias "CN" y "MachineName" al parámetro ComputerName obligatorio.

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

ATRIBUTOS DE VALIDACIÓN DE PARÁMETRO Y VARIABLE

Los atributos de validación le indican a Windows PowerShell que debe probar los valores de parámetro que los usuarios envían cuando llaman a la función avanzada. Si los valores de parámetro no superan la prueba, se genera un error y no se llama a la función. También puede usar algunos de los atributos de validación para restringir los valores que los usuarios pueden especificar para las variables.

Atributo de validación AllowNull

El atributo AllowNull permite que el valor de un parámetro obligatorio sea null ($null). En el ejemplo siguiente se declara un parámetro ComputerName que puede tener un valor Null.

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

Atributo de validación AllowEmptyString

El atributo AllowEmptyString permite que el valor de un parámetro obligatorio sea una cadena vacía (""). En el ejemplo siguiente se declara un parámetro ComputerName que puede tener un valor de cadena vacía.

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

Atributo de validación AllowEmptyCollection

El atributo AllowEmptyCollection permite que el valor de un parámetro obligatorio sea una colección vacía (@()). En el ejemplo siguiente se declara un parámetro ComputerName que puede tener un valor de colección vacía.

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

Atributo de validación ValidateCount

El atributo ValidateCount especifica el número mínimo y máximo de valores de parámetro que acepta un parámetro. Windows PowerShell genera un error si el número de valores de parámetro del comando que llama a la función está fuera de ese intervalo.

La siguiente declaración de parámetro crea un parámetro ComputerName que toma de 1 a 5 valores de parámetro.

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

Atributo de validación ValidateLength

El atributo ValidateLength especifica el número mínimo y máximo de caracteres de un parámetro o valor de la variable. Windows PowerShell genera un error si la longitud de un valor especificado para un parámetro o una variable está fuera del intervalo.

En el ejemplo siguiente, cada nombre de equipo debe tener de uno a diez caracteres.

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

En el ejemplo siguiente, el valor de la variable $number debe tener una longitud mínima de un carácter y máxima de diez caracteres.

        [Int32][ValidateLength(1,10)]$number = 01

Atributo de validación ValidatePattern

El atributo ValidatePattern especifica una expresión regular que se compara con el parámetro o el valor de la variable. Windows PowerShell genera un error si el valor no coincide con el patrón de la expresión regular.

En el ejemplo siguiente, el valor 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)]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            [String[]]
            $ComputerName
          )

En el ejemplo siguiente, el valor de la variable $number debe ser un número de cuatro dígitos, y cada dígito debe ser un número del 0 al 9.

        [Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111

Atributo de validación ValidateRange

El atributo ValidateRange especifica un intervalo numérico para cada parámetro o valor de la variable. Windows PowerShell genera un error si algún valor está fuera de ese intervalo. En el ejemplo siguiente, el valor del parámetro Attempts debe estar entre 0 y 10.

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

En el ejemplo siguiente, el valor de la variable $number debe estar entre 0 y 10.

        [Int32][ValidateRange(0,10)]$number = 5

Atributo de validación ValidateScript

El atributo ValidateScript especifica un script que se usa para validar un parámetro o valor de la variable. Windows PowerShell canaliza el valor al script y genera un error si el script devuelve "false" o si inicia una excepción.

Cuando se usa el atributo ValidateScript, el valor que se va a validar se asigna a la variable $_. Puede usar la variable $_ para hacer referencia al valor del script.

En el ejemplo siguiente, el valor del parámetro EventDate debe ser mayor o igual que la fecha actual.

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

En el ejemplo siguiente, el valor de la variable $date debe ser mayor o igual que la fecha y hora actuales.

       [DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)

Atributo ValidateSet

El atributo ValidateSet especifica un conjunto de valores válidos para un parámetro o variable. Windows PowerShell genera un error si un parámetro o valor de la variable no coincide con un valor del conjunto. En el ejemplo siguiente, el valor del parámetro Detail solo puede ser "Low", "Average" o "High".

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateSet("Low", "Average", "High")]
            [String[]]
            $Detail
          )

En el ejemplo siguiente, el valor de la variable $flavor debe ser "Chocolate", "Strawberry" o "Vanilla".

        [String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry

Atributo de validación ValidateNotNull

El atributo ValidateNotNull especifica que el valor de parámetro no puede ser null ($null). Windows PowerShell genera un error si el valor de parámetro es null.

El atributo ValidateNotNull está diseñado para usarse cuando no se especifica el tipo del valor de parámetro o cuando el tipo especificado acepta un valor Null. (Si especifica un tipo que no acepta un valor null, como una cadena, el valor null se rechazará sin el atributo ValidateNotNull, porque no coincide con el tipo especificado).

En el ejemplo siguiente, el valor del parámetro ID no puede ser null.

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNull()]
            $ID
          )

Atributo de validación ValidateNotNullOrEmpty

El atributo ValidateNotNullOrEmpty especifica que el valor de parámetro no puede ser null ($null) y no puede ser una cadena vacía (""). Windows PowerShell genera un error si el parámetro se usa en una llamada de función, pero su valor es null, una cadena vacía o una matriz vacía.

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

PARÁMETROS DINÁMICOS

Los parámetros dinámicos son parámetros de un cmdlet, función o script que solo están disponibles en ciertas condiciones.

Por ejemplo, varios cmdlets de proveedor tienen parámetros que solo están disponibles cuando el cmdlet se usa en la unidad del proveedor, o en una ruta de acceso concreta de la unidad del proveedor. Por ejemplo, el parámetro Encoding está disponible en los cmdlets Add-Content, Get-Content y Set-Content únicamente cuando se usa en una unidad del sistema de archivos.

También puede crear un parámetro que solo aparezca cuando se usa otro parámetro en el comando de función o cuando otro parámetro tiene un valor determinado.

Los parámetros dinámicos pueden ser muy útiles, pero debe usarlos solamente cuando sea necesario, ya que a los usuarios puede resultarles difícil detectarlos. Para buscar un parámetro dinámico, el usuario debe encontrarse en la ruta de acceso del proveedor, usar el parámetro ArgumentList del cmdlet Get-Command o usar el parámetro Path de Get-Help.

Para crear un parámetro dinámico para una función o un script, use la palabra clave DynamicParam.

La sintaxis es la siguiente:

      DynamicParam {<statement-list>}

En la lista de instrucciones, use una instrucción If para especificar las condiciones en las que el parámetro está disponible en la función.

Use el cmdlet New-Object para crear un objeto System.Management.Automation.RuntimeDefinedParameter para representar el parámetro y especificar su nombre.

También puede usar un comando New-Object para crear un objeto System.Management.Automation.ParameterAttribute para representar los atributos del parámetro, como Mandatory, Position o ValueFromPipeline, o su conjunto de parámetros.

En el ejemplo siguiente se muestra una función Sample con parámetros 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 Int32. El parámetro DP1 está disponible en la función Sample solamente cuando el valor del parámetro Path contiene "HKLM:", lo que indica que se está usando en la unidad de Registro HKEY_LOCAL_MACHINE.

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $attributes.Mandatory = $false
                $attributeCollection = new-object `
                    -Type System.Collections.ObjectModel.Collection[System.Attribute]
                $attributeCollection.Add($attributes)

                $dynParam1 = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
            
                $paramDictionary = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameterDictionary
                $paramDictionary.Add("dp1", $dynParam1)
                return $paramDictionary
            }
        }
    }

Para más información, consulte "Clase RuntimeDefinedParameter" en MSDN (Microsoft Developer Network) Library en el vínculo https://go.microsoft.com/fwlink/?LinkID=145130.

Parámetros de modificador

Los parámetros de modificador son parámetros sin valor de parámetro. Son efectivos solo cuando se usan y tienen un solo efecto.

Por ejemplo, el parámetro -NoProfile de PowerShell.exe es un parámetro de modificador.

Para crear un parámetro de modificador en una función, especifique el tipo Switch en la definición del parámetro.

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

Los parámetros de modificador son fáciles de usar y son preferibles a los parámetros booleanos, que tienen una sintaxis más difícil.

Por ejemplo, para usar un parámetro de modificador, el usuario escribe el parámetro en el comando.

        -IncludeAll

Para usar un parámetro booleano, el usuario escribe el parámetro y un valor booleano.

        -IncludeAll:$true

Al crear los parámetros de modificador, elija el nombre del parámetro con cuidado. Asegúrese de que el nombre del parámetro le indica al usuario el efecto del parámetro y evite términos ambiguos, como Filter o Maximum, que parecen indicar que se requiere un valor.

VEA TAMBIÉN

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute