About Functions Advanced Parameters (Español)

• 10/27/2020
• 20 minutes to read
• • S
  • s
  • s
  • c
  • g

Short description

Explains how to add parameters to advanced functions.,

Descripción larga

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

los parámetros que agregue a su 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 acerca de los parámetros comunes de PowerShell, consulte about_CommonParameters.

a partir de PowerShell 3.,0, puede usar splatting con @Args para representar los parámetros en un comando. Splatting es válido en funciones simples y avanzadas. Para obtener más información, consulte about_Functions y about_splatting.

conversión de tipo de valores de parámetro

Cuando se suministran cadenas como argumentos a parámetros que esperan un tipo diferente, PowerShell convierte implícitamente las cadenas al tipo de destino del parámetro.Las funciones avanzadas realizan el análisis invariante de cultura de los valores de los parámetros.

por el contrario, se realiza una conversión sensible a la cultura durante la vinculación de parámetros para cmdlets compilados.,

en este ejemplo, creamos un cmdlet y una función de script que toman un parámetro. La cultura actual se cambia para usar configuraciones alemanas.Se pasa una fecha con formato alemán al parámetro.

Dienstag, 19. Juni 2018 00:00:00

como se muestra arriba, los cmdlets usan análisis sensibles a la cultura para convertir la cadena.

Las funciones avanzadas utilizan el análisis invariante de la cultura, lo que resulta en el siguiente error.

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.

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

• Es obligatorio (obligatorio).
• Toma entrada de la canalización.
• toma una matriz de cadenas como entrada.

Param( ] $ComputerName)

atributos de parámetros

Esta sección describe los atributos que puede agregar a los parámetros de la función.

Todos los atributos son opcionales., Sin embargo, si omite el CmdletBindingattribute, entonces para ser reconocido 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 límite para el número de atributos que puede agregar a una declaración de parámetros.

atributo de parámetro

el atributo de parámetro se utiliza para declarar los atributos de functionparameters.

el atributo Parameter es opcional, y puede omitirlo si ninguno de los parámetros de sus funciones necesita atributos., Pero, para ser reconocida 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 u 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 el parámetro sin espacio intermedio.,

Param( $ParameterName)

Use comas para separar argumentos dentro de los paréntesis. Utilice el siguiente parámetro syntax para declarar dos argumentos del atributo Parameter.

Param( )

los tipos de argumentos booleanos del atributo Parameter default to Falsewhen omitted from the Parameter attribute. Establezca el valor del argumento en$true o simplemente enumere el argumento por nombre. Por ejemplo, los siguientes atributos de parámetros son equivalentes.,

Si utiliza el atributo Parameter sin argumentos, como alternativa al atributo CmdletBinding, los paréntesis que siguen al nombre del atributo siguen siendo necesarios.

Param( $ParameterName)

argumento Obligatorio

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

El siguiente ejemplo declara el parámetro ComputerName. Utiliza el argumentoMandatory para hacer que el parámetro sea obligatorio.,

Param( ] $ComputerName)

argumento de posición

el argumento Position determina si el nombre del parámetro es necesario cuando se utiliza el parámetro en un comando. Cuando una declaración de parámetro incluye el argumentoPosition, el nombre del parámetro se puede omitir y Powershellidentifica el valor del parámetro sin nombre por su posición u orden en la lista de valores de parámetro sin nombre en el comando.,

si no se especifica el argumento Position, el nombre del parámetro, o un alias o abreviatura de parametername, debe preceder al valor del parámetro siempre que se utilice el parámetro en un comando.

por defecto, todos los parámetros de la función son posicionales. PowerShell asigna números de posición a los parámetros en el orden en que se declaran los parámetros en la función. Para deshabilitar esta característica, establezca el valor del argumento PositionalBindingdel atributo CmdletBinding en $False., El argumento Positiontiene prioridad sobre el valor del argumento PositionalBinding del atributo CmdletBinding. Para obtener más información, consulte 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 parámetros de posición, PowerShell asigna posiciones a cada parámetro en función del orden en que se declaran los parámetros.Sin embargo, como mejor práctica, no confíe en esta tarea. Cuando quiera que los parámetros sean posicionales, utilice el argumento Position.

El siguiente ejemplo declara el parámetro ComputerName. Utiliza el argumentoPosition con un valor de 0. Como resultado, cuando -ComputerName se envía desde el comando, su valor debe ser el primero o el único parametervalue sin nombre en el comando.,

Param( ] $ComputerName)

ParameterSetName argumento

El ParameterSetName argumento especifica el conjunto de parámetros a los que aparameter pertenece. 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.

el siguiente ejemplo 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 aSummary en ambos conjuntos de parámetros.

Puede especificar solo un valor ParameterSetNameen cada argumento y solo un argumentoParameterSetName en cada atributo de parámetro. Para indicar que aparameter aparece en más de un conjunto de parámetros, agregue Parameterattributes adicionales.,

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

para obtener más información acerca de los conjuntos de parámetros, consulte Acerca de los conjuntos de parámetros.

argumento ValueFromPipeline

el argumento ValueFromPipeline indica que el parámetro acepta inputfrom un objeto de canalización., Especifica este argumento, si la función acepta eltotal de objeto, no sólo una propiedad del objeto.

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

Param( ] $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 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 pipedobject tiene una propiedad ComputerName, el valor de ComputerNameproperty se asigna al parámetro ComputerName de la función.

el siguiente ejemplo declara un parámetro ComputerName que es mandatoryand acepta entrada de la propiedad ComputerName del objeto que se pasa a la función a través de la canalización.,

Param( ] $ComputerName)

valuefromremainingarguments argumento

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.

el siguiente ejemplo declara un parámetro de valor que es obligatorio y un parámetro de mantenimiento que acepta todos los valores de parámetro restantes que se envían a la función.

Found 2 elements0: one1: two

argumento HelpMessage

el argumentoHelpMessage especifica una cadena que contiene una breve descripción del parámetro o su valor. PowerShell muestra este mensaje en el prompt que aparece cuando falta un valor de parámetro obligatorio en un comando. Este argumento no tiene ningún efecto sobre los parámetros opcionales.

el siguiente ejemplo declara un parámetro ComputerName obligatorio y un mensaje ahelp que explica el valor esperado del parámetro.,

si no hay otra sintaxis de ayuda basada en comentarios para la función (por ejemplo, .SYNOPSIS), este mensaje también se muestra en la salidaGet-Help.

Param( ] $ComputerName)

Alias attribute

El atributo Alias establece un nombre alternativo para el parámetro.No hay límite para el número de alias que puede asignar a un parámetro.

el siguiente ejemplo muestra una declaración de parámetro que añade los alias CN ymachinename al parámetro ComputerName obligatorio.,

Param( ] $ComputerName)

atributo SupportsWildcards

El atributo SupportsWildcards se utiliza para indicar que el parámetro acepta valores comodín. En el siguiente ejemplo se muestra una declaración de parámetro para un parámetro de Ruta obligatorio que admite valores comodín.

Param( ] $Path)

el Uso de este atributo no habilita automáticamente la compatibilidad con comodines. El cmdletdeveloper debe implementar el código para manejar la entrada de comodín. Los wildcardssupported pueden variar según la API subyacente o el proveedor de PowerShell. Para obtener más información, consulte about_Wildcards.,

atributos de validación de parámetros y variables

los atributos de validación dirigen a PowerShell para probar los valores de parámetros que los usuarios envían cuando llaman a la función avanzada. Si los valores de los parámetros fallan 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 cualquier otro valor, como los valores predeterminados, no se valida.

también puede usar los atributos de validación para restringir los valores que los usuarios pueden especificar para las variables., Cuando se utiliza un convertidor de tipos junto con el atributo avalidation, el convertidor de tipos debe definirse antes del atributo.

 $number = 7

atributo de validación AllowNull

El atributo AllowNull permite que el valor de un parámetro obligatorio sea$null. El siguiente ejemplo declara un parámetro computerinfo de tabla hash que puede tener un valor null.

Param( $ComputerInfo)

atributo de validación AllowEmptyString

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

Param( $ComputerName)

atributo de validación AllowEmptyCollection

El atributo AllowEmptyCollection permite que el valor de un mandatoryparameter sea una colección vacía @()., El siguiente ejemplo declara un parámetro de nombre de usuario que puede tener un valor de colección vacío.

Param( ] $ComputerName)

ValidateCount validation attribute

El atributo ValidateCount especifica el número mínimo y máximo de valores de parámetros 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 rango.

la siguiente declaración de parámetros crea un parámetro ComputerName que toma de uno a cinco valores de parámetro.,

Param( ] $ComputerName)

atributo de validación Validatenength

El atributo Validatenength 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 rango.

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

Param( ] $ComputerName)

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

$number = '01'

atributo de validación ValidatePattern

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

en el siguiente ejemplo, el valor del parámetro debe contener un número de cuatro dígitos, y cada dígito debe ser un número de cero a nueve.

Param( ")] ] $ComputerName)

en el siguiente ejemplo, 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 de cero a nueve.

$")]$number = 1111

atributo de validación ValidateRange

El atributo ValidateRange especifica un rango numérico o valor de enumeración aValidateRangeKind para cada parámetro o valor de variable.PowerShell genera un error si algún valor está fuera de ese rango.,

la enumeración ValidateRangeKind permite los siguientes valores:

• positivo-un número mayor que cero.
• negativo – un número menor que cero.
• No positivo – un número menor o igual a cero.
• No negativo – un número mayor o igual a cero.

en el siguiente ejemplo, el valor del parámetro Attempts debe estar entre cero y diez.

Param( $Attempts)

en el siguiente ejemplo, el valor de la variable $number debe estar entre ten.,

$number = 5

En el ejemplo siguiente, el valor de la variable $number debe ser mayorque cero.

$number = 1

ValidateScript validation attribute

El atributo ValidateScript especifica un script que se utiliza para validar el valor de un parámetro o variable. PowerShell canaliza el valor al script y genera un error si el script devuelve $false o si el script lanza una excepción.,

cuando se utiliza el atributo ValidateScript, el valor que se está validando se asigna a la variable $_. Puede usar la variable $_ para referirse al valor en el script.

en el ejemplo siguiente, el valor del parámetro EventDate debe ser superior o igual a la fecha actual.

Param( $EventDate)

En el ejemplo siguiente, el valor de la variable $date debe ser mayorque o igual a la fecha actual y la hora.,

$date = (Get-Date)

atributo ValidateSet

El atributo ValidateSet especifica un conjunto de valores válidos para una variable de parámetro y habilita la finalización de tabulaciones. PowerShell genera un error si el valor del aparameter o de la 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( ] $Detail)

en el siguiente ejemplo, el valor de la variable $flavor debe ser eitherChocolate, Strawberry o Vanilla.

$flavor = "Strawberry"

la validación se produce cuando esa variable se asigna incluso dentro de thescript. Por ejemplo, el siguiente resultado es un error en tiempo de ejecución:

Param( $Message)$Message = "bye"

valores dinámicos de validateSet

puede usar una clase para generar dinámicamente los valores para el tiempo de ejecución de ValidateSetat., En el siguiente ejemplo, los valores válidos para la variable$Sound se generan a través de una clase llamada SoundNames que comprueba las rutas de tres filesystem para los archivos de sonido disponibles:

la clase se implementa como un valor de ValidateSet dinámico como sigue:

Param( )] $Sound)

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 ser utilizado cuando el parámetro isoptional y el tipo no está definido o tiene un convertidor de tipos que puede convertir de forma implícita un valor nulo como object. Si especifica un tipo thatthat convertirá implícitamente un valor null, como una cadena, el valor null se convierte en una cadena vacía incluso cuando se utiliza ValidateNotNullattribute. Para este escenario use el ValidateNotNullOrEmpty

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

Param( $ID)

ValidateNotNullOrEmpty validation attribute

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

Param( ] $UserName)

atributo de validación ValidateDrive

El atributo ValidateDrive especifica que el valor del parámetro debe representar la ruta de acceso, que se refiere solo a las unidades permitidas. PowerShell genera un error si el valor del parámetro se refiere a unidades distintas de las permitidas. La existencia del camino, a excepción de la unidad en sí, no se verifica.

Si utiliza la ruta relativa, la unidad actual debe estar en la lista de unidades permitidas.,

Param( $Path)

atributo de validación ValidateUserDrive

El atributo ValidateUserDrive especifica que el valor del parámetro debe representar la ruta de acceso, que se refiere a la unidad User. PowerShell genera unerror si la ruta de acceso se refiere a una unidad diferente. El atributo validation solo comprueba la existencia de la porción de unidad de la ruta.

Si utiliza una ruta relativa, la unidad actual debe ser User.,

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument 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'. Cannotfind drive. A drive with the name 'User' does not exist.

Se puede definir User unidad Suficientes Administración (JEA) sessionconfigurations. Para este ejemplo, creamos la unidad User:.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH

True

ValidateTrustedData validación atributo

Este atributo se agregó en PowerShell 6.1.1.

en este momento, PowerShell utiliza internamente el atributo y no está destinado al uso externo.,

parámetros dinámicos

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

por ejemplo, varios cmdlets de Proveedor tienen parámetros que solo están disponibles cuando el cmdlet se usa en la unidad de Proveedor o en una ruta de acceso particular de la unidad de Proveedor. Por ejemplo, el parámetro Encoding está disponible en los cmdletsAdd-Content, Get-Content y Set-Content solo cuando se utiliza la unidad de sistema de archivos ina.,

también puede crear un parámetro que aparezca solo cuando se utilice otro parámetro en el comando function o cuando otro parámetro tenga un valor determinado.

Los parámetros dinámicos pueden ser útiles, pero úsalos solo cuando sea necesario, porque pueden ser difíciles de descubrir para los usuarios. Para encontrar un parámetro dinámico, el Usuario debe estar en la ruta de acceso del proveedor, utilice el parámetro ArgumentList del cmdletGet-Command o utilice el parámetro Path de Get-Help.

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

la sintaxis es La siguiente:

DynamicParam {<statement-list>}

En la declaración de la lista, utilice un If declaración de especificar las condiciones underwhich el parámetro está disponible en la función.

utilice el cmdlet New-Object para crear un aSystem.Gestión.Automatización.Objeto RuntimeDefinedParameter para representar el parámetro y especificar su nombre.

Puede utilizar un comando New-Object para crear un sistema.Gestión.Automatización.,ParameterAttribute objeto para representar atributos del parámetro, como Mandatory, Position, orValueFromPipeline o su conjunto de parámetros.

el siguiente ejemplo muestra una función de ejemplo con parámetros estándar namedName y Path, y un parámetro dinámico opcional llamado DP1. El parámetro DP1 está en el conjunto de parámetros PSet1 y tiene un tipo de Int32.,El parámetro DP1 está disponible en la función Get-Sample solo cuando el valor del parámetro Path comienza con HKLM:, indicando que se está utilizando en la unidad de registro HKEY_LOCAL_MACHINE.

para más información, veruntimedefinedparameter.

parámetros de conmutación

Los parámetros de conmutación 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 conmutación.,

para crear un parámetro switch en una función, especifique el tipo Switch en la definición del parámetro.

por ejemplo:

Param(<ParameterName>)

o, puede usar otro método:

Param( $<ParameterName>)

Los parámetros del interruptor son fáciles de usar y se prefieren a 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 thecommand.

-IncludeAll

el uso De un parámetro Booleano, el usuario escribe el parámetro y un valor Booleano.,

-IncludeAll:$true

al crear parámetros de conmutación, elija el nombre del parámetro cuidadosamente. Asegúrese de que el nombre del parámetro comunica el efecto del parámetro al usuario.Evite términos ambiguos, como filtro o máximo que puedan implicar que se requiere avalue.

atributo ArgumentCompleter

El atributo ArgumentCompleter le 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 completar tabulador., Al igual que DynamicParameters, los valores disponibles se calculan en tiempo de ejecución cuando el usuario presiona Tabdespué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 siguientes parámetros en el orden especificado a continuación. Los nombres de los parámetros no importan ya que los valores se proporcionan posicionalmente.,

la sintaxis es la siguiente:

ArgumentCompleter script block

los parámetros del bloque de script se establecen en los siguientes valores:

• $commandName (posición 0) – este parámetro se establece en el nombre del comando para el que el bloque de script proporciona la finalización de la pestaña.
• $parameterName(posición 1) – Este parámetro se establece en el parámetro whosevalue requiere la finalización de la pestaña.
• $wordToComplete (posición 2) – Este parámetro se establece en el valor que el Usuario ha proporcionado antes de presionar Tab., Su 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 Abstract SyntaxTree (AST) para la línea de entrada actual. Para obtener más información, consulte la última clase.
• $fakeBoundParameters(posición 4) – Este parámetro se establece en una hashtablecontaining el $PSBoundParameters para el cmdlet, antes de que el usuario pulse Tab. Para obtener más información, consulte about_automatic_variables.,

El bloque de script ArgumentCompleter debe desenrollar los valores usando thepipeline, como ForEach-Object, Where-Object, u otro método adecuado.Devolver una matriz de valores hace que PowerShell trate toda la matriz como un valor de finalización de pestaña.

el siguiente ejemplo añade la terminación de tabulación al parámetro Value. Si solo se especifica el parámetro Value, se muestran todos los valores o argumentos posibles para value. Cuando se especifica el parámetro Type, el parámetro theValue solo muestra los valores posibles para ese tipo.,

Además, el operador -like garantiza que si el usuario escribe el siguiente comando y usa la terminación de pestañas, solo se devuelve Apple.

Test-ArgumentCompleter -Type Fruits -Value A

Véase también

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute