Acerca de los parámetros avanzados de Functions
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 atributos y argumentos 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 agrega a la función están disponibles para los usuarios, además de los parámetros comunes que PowerShell agrega automáticamente a todos los cmdlets y funciones avanzadas. Para obtener más información sobre los parámetros comunes de PowerShell, consulte about_CommonParameters.
A partir de PowerShell 3.0, puede usar la expansión con @Args para representar los parámetros en un comando. La expansión es válida en funciones simples y avanzadas. Para obtener más información, consulte about_Functions y about_Splatting.
Parámetros estáticos
Los parámetros estáticos son parámetros que siempre están disponibles en la función. La mayoría de los parámetros de los cmdlets y scripts de PowerShell son parámetros estáticos.
En el ejemplo siguiente se muestra la declaración de un parámetro ComputerName que tiene las siguientes características:
- Es obligatorio (obligatorio).
- Toma la 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 puede agregar a los parámetros de función.
Todos los atributos son opcionales. Sin embargo, si omite el atributo CmdletBinding , se reconocerá como una función avanzada, la función debe incluir el atributo Parameter .
Puede agregar uno o varios atributos en cada declaración de parámetro. No hay ningún límite en el número de atributos que se pueden agregar a una declaración de parámetros.
Atributo de parámetro
El atributo Parameter se usa para declarar los atributos de los parámetros de función.
El atributo Parameter es opcional y puede omitirlo si ninguno de los parámetros de las funciones necesita atributos. Sin embargo, para que se reconozca como una función avanzada, en lugar de una función simple, una función debe tener el atributo CmdletBinding o el atributo Parameter , o ambos.
El atributo Parameter tiene argumentos que definen las características del parámetro, como si el parámetro es obligatorio o opcional.
Use la siguiente sintaxis para declarar el atributo Parameter , un argumento y un valor de argumento. Los paréntesis que encierran el argumento y su valor deben seguir Parameter sin espacio intermedio.
Param(
[Parameter(Argument=value)]
$ParameterName
)
Use comas para separar los argumentos entre paréntesis. Use la siguiente sintaxis para declarar dos argumentos del atributo Parameter .
Param(
[Parameter(Argument1=value1,
Argument2=value2)]
)
Si usa el atributo Parameter sin argumentos, como alternativa al uso del atributo CmdletBinding , los paréntesis que siguen al nombre del atributo siguen siendo necesarios.
Param(
[Parameter()]
$ParameterName
)
Argumento obligatorio
El Mandatory argumento indica que se requiere el parámetro . Si no se especifica este argumento, el parámetro es opcional.
En el ejemplo siguiente se declara el parámetro ComputerName . Usa el Mandatory argumento para que el parámetro sea obligatorio.
Param(
[Parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Argumento Position
El Position argumento determina si el nombre del parámetro es necesario cuando se usa el parámetro en un comando. Cuando una declaración de parámetro incluye el Position argumento , se puede omitir el nombre del parámetro y PowerShell identifica el valor del parámetro sin nombre por su posición, o orden, en la lista de valores de parámetro sin nombre en el comando.
Si no se especifica el Position argumento, el nombre del parámetro o un alias o abreviatura de nombre de parámetro, debe preceder al valor del parámetro siempre que se use el parámetro en un comando.
De forma predeterminada, todos los parámetros de función son posicionales. PowerShell asigna números de posición a 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 PositionalBinding argumento del atributo $FalseCmdletBinding en . El Position argumento tiene prioridad sobre el valor del PositionalBinding argumento para los parámetros en los que se declara. Para obtener más información, consulte PositionalBinding en about_Functions_CmdletBindingAttribute.
El valor del Position argumento se especifica como un entero. Un valor de posición de 0 representa la primera posición del comando, un valor de posición de 1 representa la segunda posición del comando, etc.
Si una función no tiene parámetros posicionales, PowerShell asigna posiciones a cada parámetro en función del orden en el que se declaran los parámetros.
Sin embargo, como procedimiento recomendado, no se base en esta asignación. Cuando desee que los parámetros sean posicionales, use el Position argumento .
En el ejemplo siguiente se declara el parámetro ComputerName . Usa el Position argumento con un valor de 0. Como resultado, cuando -ComputerName se omite del comando , su valor debe ser el primer o solo valor de parámetro sin nombre en el comando.
Param(
[Parameter(Position=0)]
[String[]]
$ComputerName
)
Nota
Cuando el Get-Help cmdlet muestra el atributo de parámetro Position correspondiente, el valor de posición se incrementa en uno.
Por ejemplo, un parámetro con un Position valor de argumento de 0 tiene un atributo de parámetro de Position=1.
Argumento ParameterSetName
El ParameterSetName argumento especifica el parámetro establecido en el 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 . Por lo tanto, para ser único, cada conjunto de parámetros debe tener al menos un parámetro que no sea miembro de ningún otro conjunto de parámetros.
Nota
Para un cmdlet o una función, hay un límite de 32 conjuntos de parámetros.
En el ejemplo siguiente se declara un parámetro ComputerName en el Computer conjunto de parámetros, un parámetro UserName en el User conjunto de parámetros 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
)
Solo puede especificar un ParameterSetName valor en cada argumento y solo un ParameterSetName argumento en cada atributo Parameter . Para indicar que un parámetro aparece en más de un conjunto de parámetros, agregue atributos parameter adicionales.
En el ejemplo siguiente se agrega explícitamente el parámetro Summary a los Computer conjuntos de parámetros y User . El parámetro Summary es opcional en el Computer conjunto de parámetros y es obligatorio en el User conjunto de parámetros.
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 Cmdlet Parameter Sets.
Argumento ValueFromPipeline
El ValueFromPipeline argumento 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 obligatorio y se 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 ValueFromPipelineByPropertyName argumento indica que el parámetro acepta la entrada de una propiedad de un objeto de canalización. La propiedad object 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
)
Nota
Un parámetro con tipo que acepta la entrada de canalización (by Value) o (by PropertyName) permite el uso de bloques de script de enlace retrasado en el parámetro .
El bloque de script delay-bind se ejecuta automáticamente durante ParameterBinding. El resultado se enlaza al parámetro . El enlace de retraso no funciona para los parámetros definidos como tipo ScriptBlock o System.Object, el bloque de script se pasa a través sin invocarse.
Puede leer sobre los bloques de scripts de enlace retrasado aquí about_Script_Blocks.md.
Argumento ValueFromRemainingArguments
El ValueFromRemainingArguments argumento indica que el parámetro acepta todos los valores del parámetro en el comando que no están asignados a otros parámetros de la función.
Hay un problema conocido por el uso de colecciones con ValueFromRemainingArguments donde la colección pasada se trata como un único elemento.
En el ejemplo siguiente se muestra este problema conocido. El parámetro Remaining debe contener uno en el índice 0 y dos en el índice 1. En su lugar, ambos elementos se combinan en una sola entidad.
function Test-Remainder
{
param(
[string]
[Parameter(Mandatory = $true, Position=0)]
$Value,
[string[]]
[Parameter(Position=1, ValueFromRemainingArguments)]
$Remaining)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++)
{
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 1 elements
0: one two
Nota
Este problema se resuelve en PowerShell 6.2.
Argumento HelpMessage
El HelpMessage argumento especifica una cadena que contiene una breve descripción del parámetro o su valor. PowerShell muestra este mensaje en el símbolo del sistema que aparece cuando falta un valor de parámetro obligatorio en un comando. Este argumento no tiene ningún efecto en los parámetros opcionales.
En el ejemplo siguiente se declara un parámetro ComputerName obligatorio y un mensaje de ayuda que explica el valor del parámetro esperado.
Param(
[Parameter(Mandatory=$true,
HelpMessage="Enter one or more computer names separated by commas.")]
[String[]]
$ComputerName
)
Alias (atributo)
El atributo Alias establece un nombre alternativo para el parámetro . No hay ningún límite en el 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ámetros y variables
Los atributos de validación dirigen PowerShell para probar los valores de parámetro que los usuarios envían cuando llaman a la función avanzada. Si los valores de parámetro producen un error en 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. 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ío.
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ío.
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. 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 uno a cinco 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 en un valor de parámetro o variable. 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 uno a diez caracteres.
Param(
[Parameter(Mandatory=$true)]
[ValidateLength(1,10)]
[String[]]
$ComputerName
)
En el ejemplo siguiente, el valor de la variable $number debe ser un mínimo de un carácter de longitud y un máximo 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. PowerShell genera un error si el valor no coincide con el patrón de expresión regular.
En el ejemplo siguiente, el valor del parámetro debe contener un número de cuatro dígitos y cada dígito debe ser un número cero a nueve.
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 exactamente un número de cuatro dígitos y cada dígito debe ser un número cero a nueve.
[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 variable. 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 comprendido entre cero y diez.
Param(
[Parameter(Mandatory=$true)]
[ValidateRange(0,10)]
[Int]
$Attempts
)
En el ejemplo siguiente, el valor de la variable $number debe estar comprendido entre cero y diez.
[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 un valor de variable. PowerShell canaliza el valor al script y genera un error si el script devuelve $false o si el script produce una excepción.
Cuando se usa el atributo ValidateScript , el valor que se está validando 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(Mandatory=$true)]
[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. PowerShell genera un error si un parámetro o valor de variable no coincide con un valor del conjunto. En el ejemplo siguiente, el valor del parámetro Detail solo puede ser Bajo, Promedio o Alto.
Param(
[Parameter(Mandatory=$true)]
[ValidateSet("Low", "Average", "High")]
[String[]]
$Detail
)
En el ejemplo siguiente, el valor de la variable $flavor debe ser Chocolate, Fresa o Vainilla.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[String]$flavor = "Strawberry"
La validación se produce cada vez que se asigna esa variable incluso dentro del script. Por ejemplo, lo siguiente produce un error en tiempo de ejecución:
Param(
[ValidateSet("hello", "world")]
[String]$Message
)
$Message = "bye"
Atributo de validación ValidateNotNull
El atributo ValidateNotNull especifica que el valor del parámetro no puede ser $null. PowerShell genera un error si el valor del parámetro es $null.
El atributo ValidateNotNull está diseñado para usarse cuando no se especifica el tipo del valor del parámetro o cuando el tipo especificado acepta un valor de $null. Si especifica un tipo que no acepta un $null valor, como una cadena, el $null valor se rechaza sin el atributo ValidateNotNull , ya que 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 del parámetro no puede ser $null y no puede ser una cadena vacía (""). 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, una función o un script que solo están disponibles en determinadas condiciones.
Por ejemplo, varios cmdlets de proveedor tienen parámetros que solo están disponibles cuando se usa el cmdlet en la unidad del proveedor o en una ruta de acceso determinada de la unidad del proveedor. Por ejemplo, el parámetro Encoding está disponible en los Add-Contentcmdlets , Get-Contenty Set-Content solo cuando se usa en una unidad del sistema de archivos.
También puede crear un parámetro que aparezca solo 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 útiles, pero usarlos solo cuando sea necesario, ya que pueden ser difíciles de detectar a los usuarios. Para buscar un parámetro dinámico, el usuario debe estar en la ruta de acceso del proveedor, use el parámetro ArgumentList del Get-Command cmdlet o use el parámetro Path de Get-Help.
Para crear un parámetro dinámico para una función o script, use la DynamicParam palabra clave .
La sintaxis es la siguiente:
DynamicParam {<statement-list>}
En la lista de instrucciones, use una If instrucción para especificar las condiciones en las que el parámetro está disponible en la función .
Use el New-Object cmdlet para crear un objeto System.Management.Automation.RuntimeDefinedParameter para representar el parámetro y especificar su nombre.
Puede usar un New-Object comando para crear un objeto System.Management.Automation.ParameterAttribute para representar atributos del parámetro, como Mandatory, Position o ValueFromPipeline o su conjunto de parámetros.
En el ejemplo siguiente se muestra una función de ejemplo 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 PSet1 conjunto de parámetros y tiene un tipo de Int32.
El parámetro DP1 solo está disponible en la Get-Sample función cuando el valor del parámetro Path comienza por HKLM:, lo que indica que se usa en la unidad del HKEY_LOCAL_MACHINE Registro.
function Get-Sample {
[CmdletBinding()]
Param([String]$Name, [String]$Path)
DynamicParam
{
if ($Path.StartsWith("HKLM:"))
{
$attributes = New-Object -Type `
System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = "PSet1"
$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 obtener más información, vea RuntimeDefinedParameter.
Parámetros de modificador
Los parámetros switch son parámetros sin ningún valor de parámetro. Solo son eficaces cuando se usan y tienen un solo efecto.
Por ejemplo, el parámetro NoProfile de powershell.exe es un parámetro switch.
Para crear un parámetro switch en una función, especifique el Switch tipo en la definición de parámetro.
Por ejemplo:
Param([Switch]<ParameterName>)
O bien, puede usar otro método:
Param(
[Parameter(Mandatory=$false)]
[Switch]
$<ParameterName>
)
Los parámetros switch son fáciles de usar y se prefieren sobre los parámetros booleanos, que tienen una sintaxis más difícil.
Por ejemplo, para usar un parámetro switch, 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 parámetros switch, elija cuidadosamente el nombre del parámetro. Asegúrese de que el nombre del parámetro comunica el efecto del parámetro al usuario. Evite términos ambiguos, como Filter o Maximum , lo que podría implicar que se requiere un valor.
Atributo ArgumentCompleter
El atributo ArgumentCompleter permite agregar valores de finalización de tabulación a un parámetro específico. Al igual que DynamicParameters, los valores disponibles se calculan en tiempo de ejecución cuando el usuario presiona Tab después del nombre del parámetro.
Para agregar un atributo ArgumentCompleter , debe definir un bloque de script que determine los valores. El bloque de script debe tomar los parámetros siguientes en el orden especificado a continuación. Los nombres del parámetro no importan, ya que los valores se proporcionan de forma posicional.
La sintaxis es la siguiente:
Param(
[Parameter(Mandatory)]
[ArgumentCompleter({
param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
# Perform calculation of tab completed values here.
})]
)
Bloque de script ArgumentCompleter
Los parámetros del bloque de script se establecen en los valores siguientes:
$commandName(Posición 0): este parámetro se establece en el nombre del comando para el que el bloque de script proporciona finalización de tabulación.$parameterName(Posición 1): este parámetro se establece en el parámetro cuyo valor requiere finalización de tabulación.$wordToComplete(Posición 2): este parámetro se establece en el valor que el usuario ha proporcionado antes de presionar tab. El bloque de script debe usar este valor para determinar los valores de finalización de tabulación.$commandAst(Posición 3): este parámetro se establece en el árbol de sintaxis abstracta (AST) para la línea de entrada actual. Para obtener más información, vea Ast Class.$fakeBoundParameter(Posición 4): este parámetro se establece en una tabla hash que contiene para$PSBoundParametersel cmdlet, antes de que el usuario presione Tab. Para obtener más información, consulte about_Automatic_Variables.
El bloque de script ArgumentCompleter debe anular la inscripción de los valores mediante la canalización, comoForEach-Object , Where-Objectu otro método adecuado.
Devolver una matriz de valores hace que PowerShell trate toda la matriz como un valor de finalización de tabulación.
En el ejemplo siguiente se agrega la finalización de tabulación al parámetro Value . Si no se especifica, $Type se devuelven frutas y verduras. Si se especifica un $Type objeto , solo se especifican valores para el tipo. Además, el -like operador garantiza que si el usuario escribe el siguiente comando y usa la finalización de tabulación , solo se devuelve Apple .
Test-ArgumentCompleter -Type Fruits -Value A
function Test-ArgumentCompleter {
[CmdletBinding()]
param (
[Parameter(Mandatory)]
[ValidateSet('Fruits', 'Vegetables')]
$Type,
[Parameter(Mandatory)]
[ArgumentCompleter( {
param ( $commandName,
$parameterName,
$wordToComplete,
$commandAst,
$fakeBoundParameters )
$possibleValues = @{
Fruits = @('Apple', 'Orange', 'Banana')
Vegetables = @('Tomato', 'Squash', 'Corn')
}
if ($fakeBoundParameters.ContainsKey('Type'))
{
$possibleValues[$fakeBoundParameters.Type] | Where-Object {
$_ -like "$wordToComplete*"
}
}
else
{
$possibleValues.Values | ForEach-Object {$_}
}
} )]
$Value
)
}
Consulte también
about_Functions_Advanced_Methods