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