TEMA

about_Functions_Advanced_Parameters
DESCRIPCIN BREVE
Explica cmo agregar parmetros estticos y dinmicos a las funciones que
declaran el atributo CmdletBinding.
DESCRIPCIN DETALLADA
Puede declarar sus propios parmetros al escribir las funciones,
y tambin escribir las funciones de tal forma que puedan tener
acceso a los parmetros comunes que estn disponibles para los cmdlets
compilados. Para obtener ms informacin sobre los parmetros comunes
de Windows PowerShell, vea about_CommonParameters.
Parmetros estticos
En el ejemplo siguiente se muestra una declaracin de parmetro
que define un parmetro ComputerName. Este parmetro tiene las
caractersticas siguientes:
- Es obligatorio.
- Toma la entrada de la canalizacin.
- 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
parmetro es el atributo Parameter. Sin embargo, tambin es
posible declarar el atributo Alias y varios argumentos de
validacin. No hay ningn lmite en cuanto al nmero de atributos
que se pueden agregar a una declaracin de parmetro.
Atributo Parameter
El atributo Parameter se utiliza para declarar un parmetro de
la funcin.
Este atributo tiene los argumentos con nombre siguientes, que
se utilizan para definir las caractersticas del parmetro,
como si es obligatorio u opcional.
Argumento con nombre Mandatory
El argumento Mandatory indica que el parmetro se necesita
cuando se ejecuta la funcin. Si no se especifica este argumento,
significa que el parmetro es opcional. En el ejemplo siguiente se
muestra la declaracin de un parmetro que es necesario al ejecutar
la funcin.
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Argumento con nombre Position
El argumento Position especifica la posicin del parmetro.
Si no se especifica este argumento, se debe especificar
explcitamente el nombre del parmetro o su alias al establecer el
parmetro. Adems, si ninguno de los parmetros de una funcin tiene
posiciones, el motor de tiempo de ejecucin de Windows PowerShell se
las asigna segn el orden en el que se recibe cada uno de ellos.
En el ejemplo siguiente se muestra la declaracin de un
parmetro cuyo valor se debe especificar como el primer
argumento cuando se ejecuta el cmdlet. Observe que esta funcin se
podra ejecutar aunque no se especifique el nombre del parmetro.
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
Argumento con nombre ParameterSetName
El argumento ParameterSetName especifica el conjunto de
parmetros al que pertenece un parmetro. Si no se especifica
ningn conjunto de parmetros, el parmetro pertenece a todos los
conjuntos de parmetros definidos por la funcin. Este comportamiento
significa que cada conjunto de parmetros debe tener un parmetro
nico que no sea miembro de ningn otro conjunto de parmetros. En el
ejemplo siguiente se muestra la declaracin de dos parmetros que
pertenecen a dos conjuntos de parmetros diferentes.
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Equipo")]
[String[]]
$ComputerName
)
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Usuario")]
[String[]]
$UserName
)
Para obtener ms informacin sobre los conjuntos de
parmetros, vea "Cmdlet Parameter Sets" en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkId=142183.
Argumento con nombre ValueFromPipeline
El argumento ValueFromPipeline especifica que el parmetro acepta
entrada procedente de un objeto de la canalizacin. 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 declaracin de parmetro de un parmetro ComputerName
obligatorio que acepta el objeto de entrada que se pasa a la funcin
desde la canalizacin.
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
Argumento con nombre ValueFromPipelineByPropertyName
El argumento valueFromPipelineByPropertyName especifica que
el parmetro acepta entrada procedente de una propiedad de un
objeto de la canalizacin. Este atributo se debe especificar si se
cumplen las condiciones siguientes:
- El parmetro tiene acceso a una propiedad del objeto canalizado.
- La propiedad tiene el mismo nombre que el parmetro o
la propiedad tiene el mismo alias que el parmetro.
Por ejemplo, si la funcin tiene un parmetro ComputerName y
el objeto canalizado tiene una propiedad ComputerName, el
valor de la propiedad ComputerName se asigna al parmetro
ComputerName de la funcin.
En el ejemplo siguiente se muestra la declaracin de un parmetro
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
parmetro acepta todos los argumentos restantes que no estn
enlazados a los parmetros de la funcin. En el ejemplo
siguiente se muestra la declaracin de un parmetro
ComputerName que acepta todos los argumentos restantes del
objeto de entrada que se pasa a la funcin.
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)
Argumento con nombre HelpMessage
El argumento HelpMessage especifica un mensaje que contiene una
descripcin breve del parmetro. En el ejemplo siguiente se muestra una
declaracin de parmetro que proporciona una descripcin del parmetro.
Param
(
[parameter(Mandatory=$true,
HelpMessage="Matriz de nombres de equipos.")]
[String[]]
$ComputerName
)
Atributo Alias
El atributo Alias especifica otro nombre para el parmetro. No
hay ningn lmite con respecto al nmero de alias que se pueden
asignar a un parmetro. En el ejemplo siguiente se muestra una
declaracin de parmetro obligatorio que agrega el alias "CN"
al parmetro ComputerName.
Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)
Atributos de validacin de parmetros
Estos atributos definen cmo validar el motor de tiempo de
ejecucin de Windows PowerShell los argumentos de las funciones
avanzadas.
Atributo de validacin AllowNull
El atributo AllowNull permite establecer en Null el argumento
de un parmetro de cmdlet obligatorio. En el ejemplo siguiente, el
parmetro ComputerName puede contener un valor Null aunque sea un
parmetro obligatorio.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowNull()]
$ComputerName
)
Atributo de validacin AllowEmptyString
El atributo AllowEmptyString permite usar una cadena vaca como
argumento de un parmetro de cmdlet obligatorio. En el ejemplo
siguiente, el parmetro ComputerName puede contener una cadena vaca
("") aunque sea un parmetro obligatorio.
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowEmptyString()]
$ComputerName
)
Atributo de validacin AllowEmptyCollection
El atributo AllowEmptyCollection permite usar una coleccin
vaca como argumento de un parmetro obligatorio.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[AllowEmptyCollection()]
$ComputerName
)
Atributo de validacin ValidateCount
El atributo ValidateCount especifica el nmero mnimo y mximo de
argumentos que el parmetro puede aceptar. El motor de tiempo de
ejecucin de Windows PowerShell genera un error si el nmero de
argumentos queda fuera de ese intervalo. En el ejemplo siguiente, el
parmetro ComputerName puede tener entre uno y cinco argumentos.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)
Atributo de validacin ValidateLength
El atributo ValidateLength especifica la longitud mnima y
mxima del argumento del parmetro. El motor de tiempo de
ejecucin de Windows PowerShell genera un error si la longitud del
argumento del parmetro 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 validacin ValidatePattern
El atributo ValidatePattern especifica una expresin regular
que valida el patrn del argumento del parmetro. El motor de
tiempo de ejecucin de Windows PowerShell genera un error si el
argumento del parmetro no coincide con este patrn. En el ejemplo
siguiente, el argumento del parmetro debe ser un nmero de cuatro
dgitos y cada dgito debe ser un nmero del 0 al 9.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
$ComputerName
)
Atributo de validacin ValidateRange
El atributo ValidateRange especifica los valores mnimo y
mximo del argumento del parmetro. El motor de tiempo de
ejecucin de Windows PowerShell genera un error si el
argumento del parmetro queda fuera de ese intervalo. En el
ejemplo siguiente, el argumento del parmetro no puede ser
menor que 0 ni mayor que 10.
Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)
Atributo de validacin ValidateScript
El atributo ValidateScript especifica un script que se
utiliza para validar el argumento del parmetro. El motor de
tiempo de ejecucin de Windows PowerShell genera un error si el
resultado del script es false o si el script inicia una excepcin. En
el ejemplo siguiente, el valor del parmetro Count debe ser menor que 4.
Param
(
[parameter()]
[Int]
[ValidateScript({$_ -lt 4})]
$Count
)
Atributo ValidateSet
El atributo ValidateSet especifica un conjunto de valores
vlidos para el argumento del parmetro. El motor de tiempo
de ejecucin de Windows PowerShell genera un error si el
argumento del parmetro no coincide con un valor del conjunto.
En el ejemplo siguiente, el argumento del parmetro puede contener
solamente los nombres Esteban, Mara y Carlos.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateRange("Esteban", "Mara", "Carlos")]
$UserName
)
Atributo de validacin ValidateNotNull
El atributo ValidateNotNull especifica que el argumento del
parmetro no puede se establecer en Null. El motor de tiempo de
ejecucin de Windows PowerShell genera un error si el valor del
parmetro es Null.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNull()]
$UserName
)
Atributo de validacin ValidateNotNullOrEmpty
El atributo ValidateNotNullOrEmpty especifica que el argumento del
parmetro no puede establecerse en Null ni estar vaco. El motor de
tiempo de ejecucin de Windows PowerShell genera un error si se
especifica el parmetro pero su valor es Null, una cadena vaca o una
matriz vaca.
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNullOrEmpty()]
$UserName
)
Parmetros dinmicos
Los parmetros dinmicos son parmetros de cmdlet, de funcin o de
script, que solo estn disponibles bajo determinadas condiciones. Por
ejemplo, algunos cmdlets de proveedores tienen parmetros que slo
estn disponibles cuando el cmdlet se usa en la ruta de acceso del
proveedor. Un parmetro dinmico muy conocido es el parmetro 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 parmetro dinmico de una funcin o un script, utilice la palabra
clave DynamicParam. La sintaxis es la siguiente:
Dynamicparam {<lista-instrucciones>}
De la lista de instrucciones, utilice una instruccin If para
especificar las condiciones bajo las que el parmetro est disponible
en la funcin. Use el cmdlet New-Object para crear un objeto
System.Management.Automation.RuntimeDefinedParameter que represente el
parmetro y especifique su nombre. Se puede utilizar un comando
New-Object para crear un objeto
System.Management.Automation.ParameterAttribute que represente los
atributos del parmetro, como son Mandatory, Position,
ValueFromPipeline o su conjunto de parmetros. En el siguiente ejemplo
se muestra una funcin de ejemplo con parmtros estndar denominados
Name y Path, y un parmetro dinmico opcional denominado DP1. El
parmetro DP1 est en el conjunto de parmetros PSet1 y tiene un tipo
de Int32. El parmetro DP1 solo est disponible en la funcin Sample
cuando el valor del parmetro 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 ms informacin, vea
System.Management.Automation.PSCmdlet.WriteVerbose en MSDN
Library,en http://go.microsoft.com/fwlink/?LinkId=145130.
VEA TAMBIN
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Functions_Advanced_Methods