about_Functions_Advanced_Parameters
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 envían con el parámetro .
Cuando se usa el CmdletBinding atributo , PowerShell agrega automáticamente los parámetros comunes. No se pueden crear parámetros que usen los mismos nombres que los parámetros comunes. Para obtener más información, consulta 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.
Conversión de tipos de valores de parámetro
Al proporcionar cadenas como argumentos a parámetros que esperan un tipo diferente, PowerShell convierte implícitamente las cadenas en el tipo de destino del parámetro. Las funciones avanzadas realizan un análisis invariable de referencia cultural de valores de parámetro.
Por el contrario, se realiza una conversión que distingue referencias culturales durante el enlace de parámetros para cmdlets compilados.
En este ejemplo, se crea un cmdlet y una función de script que toman un [datetime] parámetro. La referencia cultural actual se cambia para usar la configuración alemana.
Se pasa una fecha con formato alemán al parámetro .
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
Como se muestra anteriormente, los cmdlets usan el análisis que distingue la referencia cultural para convertir la cadena.
# Define an equivalent function.
function Get-Date_Func {
param(
[DateTime] $Date
)
process {
$Date
}
}
[CultureInfo]::CurrentCulture = 'de-DE'
# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'
Get-Date_Func $dateStr
Las funciones avanzadas usan el análisis invariable de referencia cultural, lo que produce el siguiente error.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
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
)
Parámetros de modificador
Los parámetros switch son parámetros que no toman ningún valor de parámetro. En su lugar, transmiten un valor booleano true-or-false a través de su presencia o ausencia, de modo que cuando un parámetro switch está presente tiene un valor true y cuando está ausente tiene un valor false .
Por ejemplo, el parámetro Recurse de Get-ChildItem 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, la función puede tener una opción para generar datos como una matriz de bytes:
param([switch]$AsByteArray)
Los parámetros switch son fáciles de usar y se prefieren sobre los parámetros booleanos, que tienen una sintaxis menos natural para PowerShell.
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 requiera un valor.
Consideraciones sobre el diseño de parámetros de modificador
Los parámetros switch no deben tener valores predeterminados. Siempre deben tener como valor predeterminado false.
Los parámetros switch se excluyen de los parámetros posicionales de forma predeterminada. Incluso cuando otros parámetros son implícitamente posicionales, los parámetros switch no lo son. Puede invalidarlo en el atributo Parameter, pero confundirá a los usuarios.
Los parámetros switch deben diseñarse para que al establecerlos muevan un comando de su comportamiento predeterminado a un modo menos común o más complicado. El comportamiento más sencillo de un comando debe ser el comportamiento predeterminado que no requiere el uso de parámetros switch.
Los parámetros switch no deben ser obligatorios. El único caso en el que es necesario hacer obligatorio un parámetro switch es cuando es necesario diferenciar un conjunto de parámetros.
Establecer explícitamente un modificador de un valor booleano se puede realizar con
-MySwitch:$boolValuey en la expansión con$params = @{ MySwitch = $boolValue }.Los parámetros switch son de tipo
SwitchParameter, que se convierte implícitamente en booleano. La variable de parámetro se puede usar directamente en una expresión condicional. Por ejemplo:if ($MySwitch) { ... }No es necesario escribir
if ($MySwitch.IsPresent) { ... }
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 de proveedor o en una ruta de acceso determinada de la unidad de 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 use otro parámetro en el comando de función o cuando otro parámetro tenga 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, usar el parámetro ArgumentList del Get-Command cmdlet o usar 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 .
En el ejemplo siguiente se muestra una función con parámetros estándar denominados Name y Path, y un parámetro dinámico opcional denominado KeyCount. El parámetro KeyCount está en el ByRegistryPath conjunto de parámetros y tiene un tipo de Int32. El parámetro KeyCount está disponible en la Get-Sample función solo cuando el valor del parámetro Path comienza por HKLM:, lo que indica que se está usando en la unidad del HKEY_LOCAL_MACHINE Registro.
function Get-Sample {
[CmdletBinding()]
param([string]$Name, [string]$Path)
dynamicparam
{
if ($Path.StartsWith("HKLM:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [Int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
Para obtener más información, consulte la documentación del tipo RuntimeDefinedParameter .
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 para 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 sintaxis siguiente 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 argumentos entre paréntesis. Use la sintaxis siguiente para declarar dos argumentos del atributo Parameter .
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
Los tipos de argumento booleano del atributo Parameter son False cuando se omiten del atributo Parameter . Establezca el valor $true del argumento en o simplemente enumere el argumento por nombre. Por ejemplo, los siguientes atributos Parameter son equivalentes.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
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)]
[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 del atributo CmdletBinding . 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 que se declaran los parámetros. Sin embargo, como procedimiento recomendado, no confíe 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 valor de parámetro sin nombre en el comando.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
Argumento ParameterSetName
El ParameterSetName argumento 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 . 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, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
Solo puede especificar un ParameterSetName valor en cada argumento y solo un ParameterSetName argumento en cada atributo Parameter . Para incluir un parámetro 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 conjuntos de Computer parámetros y User . El parámetro Summary es opcional en el Computer conjunto de parámetros y obligatorio en el conjunto de User parámetros.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]$Summary
)
Para obtener más información sobre los conjuntos de parámetros, vea Acerca de los conjuntos de parámetros.
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 que es obligatorio y acepta un objeto que se pasa a la función desde la canalización.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[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 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 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, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Considere la posibilidad de implementar una función mediante este argumento:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
A continuación, una demostración de la canalización de un objeto con la propiedad ComputerName sería:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
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 está enlazado 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 sin invocarse. Para obtener más información sobre los bloques de script de enlace retrasado, consulte about_Script_Blocks.
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.
En el ejemplo siguiente se declara un parámetro Value obligatorio y un parámetro Remaining que acepta todos los valores de parámetro restantes que se envían a la función.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$Remaining
)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
Argumento HelpMessage
El HelpMessage argumento especifica una cadena que contiene una breve descripción del parámetro o su valor. Si ejecuta el comando sin el parámetro obligatorio, PowerShell le pedirá una entrada. Para ver el mensaje de ayuda, escriba !? en el símbolo del sistema y presione Entrar.
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,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Ejemplo:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
Si no hay ayuda basada en comentarios para la función, este mensaje se muestra en la Get-Help -Full salida.
Este argumento no tiene ningún efecto en los parámetros opcionales.
Atributo alias
El atributo Alias establece un nombre alternativo para el parámetro . No hay ningún límite para 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)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Atributo de credencial
El atributo Credential se usa para indicar que el parámetro acepta credenciales. En el ejemplo siguiente se muestra una declaración de parámetros que usa el atributo Credential .
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Atributo experimental
Use el atributo Experimental para declarar código como experimental. Para obtener una descripción completa del atributo, consulte about_Experimental_Features.
Atributo PSDefaultValue
PSDefaultValue especifica el valor predeterminado de un parámetro de comando en un script. El cmdlet muestra Get-Help esta información. Para ver la información de valor predeterminada, la función debe incluir ayuda basada en comentarios. Por ejemplo:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Use Get-Help para ver la información de valor predeterminada.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Argumentos de atributo PSDefaultValue
El atributo PSDefaultValue tiene dos argumentos:
- Ayuda : cadena que describe el valor predeterminado. El cmdlet muestra
Get-Helpesta información. - Valor : valor predeterminado del parámetro.
Ambos argumentos son opcionales. Si no especifica ningún argumento, Get-Help se muestra el valor asignado al parámetro .
Atributo PSTypeName
No se pueden usar nombres de tipo extendidos en una declaración de tipo. El atributo PSTypeName* permite restringir el tipo del parámetro al tipo extendido.
En este ejemplo, el Test-Connection cmdlet devuelve un tipo extendido. Puede usar el atributo PSTypeName para restringir el tipo del parámetro al tipo extendido.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
Atributo System.Obsolete
Use el atributo System.Obsolete para marcar parámetros que ya no se admiten. Esto puede ser útil cuando desea quitar un parámetro de una función, pero no desea interrumpir los scripts existentes que usan la función.
Por ejemplo, considere una función que tiene un parámetro de modificador NoTypeInformation que controla si la información de tipo se incluye en la salida. Desea que ese comportamiento sea el predeterminado y quite el parámetro de la función. Sin embargo, no desea interrumpir los scripts existentes que usan la función . Puede marcar el parámetro como obsoleto y agregar un mensaje que explique el cambio.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
Atributo SupportsWildcards
El atributo SupportsWildcards se usa para indicar que el parámetro acepta valores comodín. En el ejemplo siguiente se muestra una declaración de parámetro para un parámetro Path obligatorio que admite valores comodín.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
El uso de este atributo no habilita automáticamente la compatibilidad con caracteres comodín. El desarrollador del cmdlet debe implementar el código para controlar la entrada comodín. Los caracteres comodín admitidos pueden variar según la API subyacente o el proveedor de PowerShell. Para obtener más información, consulte about_Wildcards.
Atributos de finalización de argumentos
Atributo ArgumentCompletions
El atributo ArgumentCompletions permite agregar valores de finalización de tabulación a un parámetro específico. Se debe definir un atributo ArgumentCompletions para cada parámetro que necesite finalización de tabulación. El atributo ArgumentCompletions es similar a ValidateSet. Ambos atributos toman una lista de valores que se van a presentar cuando el usuario presiona Tab después del nombre del parámetro. Sin embargo, a diferencia de ValidateSet, los valores no se validan.
Este atributo se introdujo en PowerShell 6.0.
Para obtener más información, consulte about_Functions_Argument_Completion.
Atributo ArgumentCompleter
El atributo ArgumentCompleter permite agregar valores de finalización de tabulación a un parámetro específico. Se debe definir un atributo ArgumentCompleter para cada parámetro que necesite finalización de tabulación. Al igual que los parámetros dinámicos, los valores disponibles se calculan en tiempo de ejecución cuando el usuario presiona Tab después del nombre del parámetro.
Para obtener más información, consulte about_Functions_Argument_Completion.
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 . La validación de parámetros solo se aplica a la entrada proporcionada y no se validan los demás valores, como los valores predeterminados.
También puede usar los atributos de validación para restringir los valores que los usuarios pueden especificar para las variables.
[AllowNull()] [int]$number = 7
Los atributos de validación se pueden aplicar a cualquier variable, no solo a parámetros. Puede definir la validación de cualquier variable dentro de un script.
Nota:
Cuando se usan atributos con una variable con tipo, se recomienda declarar el atributo antes del tipo.
Si declara un tipo con un salto de línea antes del atributo y el nombre de la variable, el tipo se trata como su propia instrucción.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Si declara un atributo de validación después de un tipo, el valor que se va a asignar se valida antes de la conversión de tipos, lo que puede provocar errores de validación inesperados.
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
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 ComputerInfo hashtable que puede tener un valor NULL.
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Nota:
El atributo AllowNull no funciona si el convertidor de tipos está establecido en cadena, ya que el tipo de cadena no aceptará un valor NULL. Puede usar el atributo AllowEmptyString para este escenario.
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)]
[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)]
[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 en el 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)]
[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 parámetro o valor de 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)]
[ValidateLength(1,10)]
[string[]]$ComputerName
)
En el ejemplo siguiente, el valor de la variable $text debe ser un mínimo de un carácter de longitud y un máximo de diez caracteres.
[ValidateLength(1,10)] [string] $text = 'valid'
Atributo de validación ValidatePattern
El atributo ValidatePattern especifica una expresión regular que se compara con el parámetro o el valor de 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)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
En el ejemplo siguiente, el valor de la variable $ticketID debe ser exactamente un número de cuatro dígitos y cada dígito debe ser un número cero a nueve.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Atributo de validación ValidateRange
El atributo ValidateRange especifica un intervalo numérico o un valor de enumeración ValidateRangeKind para cada parámetro o valor de variable. PowerShell genera un error si algún valor está fuera de ese intervalo.
La enumeración ValidateRangeKind permite los siguientes valores:
Positive- Un número mayor que cero.Negative- Un número menor que cero.NonPositive- Un número menor o igual que cero.NonNegative- Un número mayor o igual que cero.
En el ejemplo siguiente, el valor del parámetro Attempts debe estar comprendido entre cero y diez.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]$Attempts
)
En el ejemplo siguiente, el valor de la variable $number debe estar comprendido entre cero y diez.
[ValidateRange(0,10)] [int]$number = 5
En el ejemplo siguiente, el valor de la variable $number debe ser mayor que cero.
[ValidateRange("Positive")] [int]$number = 1
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 en el script.
En el ejemplo siguiente, el valor del parámetro EventDate debe ser mayor o igual que la fecha actual.
param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]$EventDate
)
En el ejemplo siguiente, el valor de la variable $date debe ser menor o igual que la fecha y hora actuales.
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
Nota:
Si usa ValidateScript, no puede pasar un $null valor al parámetro . Cuando se pasa un valor NULL ValidateScript no se puede validar el argumento.
Invalidación del mensaje de error predeterminado
A partir de PowerShell 6, puede invalidar el mensaje de error predeterminado generado cuando un valor especificado no es válido con el ErrorMessage argumento . Especifique una cadena de formato compuesto. El 0 componente de índice usa el valor de entrada.
El 1 componente de índice usa scriptBlock usado para validar el valor de entrada.
En el ejemplo siguiente, el valor del parámetro EventDate debe ser mayor o igual que la fecha y hora actuales. Si el valor no es válido, el mensaje de error notifica que la fecha y hora especificadas son demasiado antiguas.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Cuando el valor especificado es una fecha pasada, se devuelve el mensaje de error personalizado.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
Puede aplicar más formato en la cadena con componentes de cadena de formato opcionales.
En el ejemplo siguiente, el valor del parámetro EventDate debe ser mayor o igual que la fecha y hora actuales. Si el valor no es válido, el mensaje de error informa de que la fecha especificada es demasiado antigua.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Cuando el valor especificado es una fecha pasada, se devuelve el mensaje de error personalizado.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
Atributo ValidateSet
El atributo ValidateSet especifica un conjunto de valores válidos para un parámetro o variable y habilita la finalización de tabulaciones. 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)]
[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"
En este ejemplo se devuelve el siguiente error en tiempo de ejecución:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
El uso ValidateSet de también habilite la expansión de tabulación de valores para ese parámetro. Para obtener más información, consulte about_Tab_Expansion.
Valores ValidateSet dinámicos mediante clases
Puede usar una clase para generar dinámicamente los valores de ValidateSet en tiempo de ejecución. En el ejemplo siguiente, los valores válidos para la variable $Sound se generan a través de una clase denominada SoundNames que comprueba tres rutas de acceso del sistema de archivos para los archivos de sonido disponibles:
Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds','~/Library/Sounds'
$SoundNames = ForEach ($SoundPath in $SoundPaths) {
If (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
A continuación, la [SoundNames] clase se implementa como un valor ValidateSet dinámico como se indica a continuación:
param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Nota:
La IValidateSetValuesGenerator clase se introdujo en PowerShell 6.0
Atributo de validación ValidateNotNull
El atributo ValidateNotNull especifica que el valor del parámetro no puede ser $null. Cuando el valor es $null, PowerShell genera una excepción.
El atributo ValidateNotNull está diseñado para usarse cuando el parámetro es opcional y el tipo no está definido o tiene un convertidor de tipos que no puede convertir implícitamente un valor NULL como un objeto. Si especifica un tipo que convierte implícitamente un valor NULL, como una cadena, el valor NULL se convierte en una cadena vacía incluso cuando se usa el atributo ValidateNotNull . Para este escenario, use el atributo ValidateNotNullOrEmpty .
En el ejemplo siguiente, el valor del parámetro ID no puede ser $null.
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
Atributo de validación ValidateNotNullOrEmpty
El atributo ValidateNotNullOrEmpty especifica que el valor asignado no puede ser ninguno de los valores siguientes:
$null- una cadena vacía (
"") - una matriz vacía (
@())
Cuando el valor no es válido, PowerShell genera una excepción.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
Atributo de validación ValidateNotNullOrWhiteSpace
El atributo ValidateNotNullOrWhiteSpace especifica que el valor asignado no puede ser ninguno de los valores siguientes:
$null- una cadena vacía (
"") - una matriz vacía
@() - una cadena que contiene solo caracteres de espacio en blanco, como pestañas, espacios, retornos de carro y nuevas líneas
- matriz que contiene las cadenas que están vacías o contienen solo caracteres de espacio en blanco.
Cuando el valor no es válido, PowerShell genera una excepción.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[string[]]$UserName
)
Atributo de validación ValidateDrive
El atributo ValidateDrive especifica que el valor del parámetro debe representar la ruta de acceso, que hace referencia solo a unidades permitidas. PowerShell genera un error si el valor del parámetro hace referencia a unidades distintas de las permitidas. No se comprueba la existencia de la ruta de acceso, excepto la propia unidad.
Si usa la ruta de acceso relativa, la unidad actual debe estar en la lista de unidades permitidas.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Atributo de validación ValidateUserDrive
El atributo ValidateUserDrive especifica que el valor del parámetro debe representarse en la User unidad. PowerShell genera un error si la ruta de acceso hace referencia a una unidad diferente. El atributo de validación solo comprueba la existencia del prefijo de unidad de la ruta de acceso.
Si usa la ruta de acceso relativa, la unidad actual debe ser User.
function Test-UserDrivePath{
[OutputType([bool])]
param(
[Parameter(Mandatory, Position=0)]
[ValidateUserDrive()]
[string]$Path
)
$True
}
Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.
Puede definir User la unidad en configuraciones de sesión Just Enough Administration (JEA). En este ejemplo, creamos la unidad User: .
New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name Used (GB) Free (GB) Provider Root
---- --------- --------- -------- ----
User 75.76 24.24 FileSystem C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
Atributo de validación ValidateTrustedData
Este atributo se agregó en PowerShell 6.1.1.
En este momento, PowerShell usa internamente el atributo y no está pensado para el uso externo.
