Funciones avanzadas

1. Param

El bloque Param se utiliza para definir todos los parámetros de una función. Los parámetros pueden definirse de dos maneras:

#Primer Método:  
Function <Nombre_de_la_función> (<Bloque de_parámetros>) {  
...  
}  
#Segundo Método:  
Function <Nombre_de_la_función> {  
    Param (  
         <Bloque_de parámetros>  
    )  
    ...  
} 

En el caso de una función avanzada, solo se puede utilizar el primer método. Basta con rellenar el bloque Param, aunque esté vacío, con [CmdletBinding()].

Se pueden indicar varios elementos para un parámetro:

Para los dos primeros, la sintaxis es bastante común. He aquí un ejemplo con un parámetro de tipo cadena de caracteres ([string]) y ’localhost’ como valor por defecto:

Param (  
    [string]$ComputerName = 'localhost'  
)  

Veremos...

1. Conjuntos de parámetros

Al diseñar una función, resulta útil trabajar con asociaciones de parámetros. Para cada grupo de parámetros, la función tiene diferentes acciones. Esta es una característica común de los cmdlets nativos de PowerShell.

Ejemplo con Get-Process

PS > get-help get-process 
 
NOMBRE   
   Get-Process   
 
RESUMEN  
   Gets the processes that are running on the local computer or  
a remote computer.  
 
 
SINTAXIS  
  Get-Process [[-Name] <String[]>] [-ComputerName <String[]>]  
[-FileVersionInfo] [-Module] [<CommonParameters>]  
  
   Get-Process [-ComputerName <String[]>] [-FileVersionInfo] -Id  
<Int32[]> [-Module] [<CommonParameters>]  
  
 
  Get-Process [-ComputerName <String[]>] [-FileVersionInfo]  
-InputObject <Process[]> [-Module] [<CommonParameters>]  
  
   Get-Process -Id <Int32[]> -IncludeUserName [<CommonParameters>]  
  
   Get-Process [[-Name] <String[]>] -IncludeUserName  
[<CommonParameters>]  
  
   Get-Process -IncludeUserName -InputObject <Process[]>  
[<CommonParameters>] 

Se requiere un poco de trabajo de análisis. Los tres parámetros Id, Name e InputObject no pueden utilizarse juntos. En segundo lugar, IncludeUserName no puede utilizarse con el conjunto ComputerName/Module/FileVersionInfo. Sin embargo, cada uno de los tres primeros parámetros puede utilizarse en los dos conjuntos de parámetros. Este es un caso elaborado de conjuntos de parámetros. Es posible alcanzar este nivel de complejidad utilizando funciones avanzadas. Para ello, es necesario utilizar el argumento ParameterSetName y asignarlo a un parámetro. Como recordatorio, un parámetro...

1. Declaración

Los parámetros dinámicos se declaran mediante la instrucción DynamicParam{}, que se coloca después del bloque Param():

Param()  
DynamicParam{  
  ...  
} 

Observe que DynamicParam{} se define utilizando llaves en lugar de paréntesis, a diferencia de Param(). De hecho, se trata de un bloque de script que se ejecutará de forma periódica, para generar sobre la marcha los parámetros dinámicos de la función.

Un bloque de script permite utilizar todas las funciones disponibles: comandos, funciones, estructura, comparación, etc.

Sin embargo, antes de presentar un ejemplo complejo, concentrémonos en lo mínimo necesario para crear un parámetro dinámico.

Todos los comandos que veremos en las siguientes secciones deben colocarse, por supuesto, en el bloque de script DynamicParam{...}. La sección Resumen ofrece un resumen de las tres secciones anteriores.

2. Nueva colección de atributos

El uso de atributos se explica en la sección Param de este capítulo, en la que vimos que un parámetro puede tener varios atributos ([Parameter[]], [Alias()], etc.). En el caso de los parámetros dinámicos, utilizamos una colección de atributos para agruparlos. Esto se crea con el siguiente comando:

    $attributeCollection = New-Object ` System.Collections. 
ObjectModel.Collection[System.Attribute] 

El siguiente paso consiste en crear el equivalente del atributo [Parameter()] utilizando la función:

    $parameterAttribut = New-Object ` System.Management.  
Automation.ParameterAttribute 

Es posible cambiar las opciones de este atributo. Encontrará entonces los mismos elementos que antes:

1. ArgumentCompletions

ArgumentCompletion es similar a ValidateSet, excepto en que no comprueba el valor pasado al parámetro. Los valores que se le pasan solo se utilizan como sugerencias al autocompletar mediante la tecla [Tab].

La sintaxis sigue siendo similar:

Ejemplo

Param (   
   [Parameter(Mandatory=$true)]   
   [ArgumentCompletions('Info','Warning','Error')]   
   [String]$Type   
) 

Aquí el usuario ve aparecer las sugerencias Info, Warning y Error cuando utiliza la tecla [Tab] (autocompletado) en el parámetro -Type. Sin embargo, es perfectamente posible introducir otro valor, como Información o Advertencia. 

2. ArgumentCompleter

El atributo ArgumentCompleter es más complejo de manejar que los atributos anteriores. Al igual que ValidateScript, requiere el uso de un bloque de script (scriptblock), pero le diferencia que debe devolver uno o más valores enumerados. Estos valores se utilizarán como sugerencias para el usuario cuando se llame a autocompletar, con la ventaja de que parte de la entrada del usuario puede tenerse en cuenta cuando se llama a autocompletar.

También es posible utilizar una clase PowerShell en lugar de un bloque de script. Para obtener más información, consulte el capítulo Clases - Uso de clases para la validación de parámetros.

[ArgumentCompleter(  
 {  
  param (   
       $commandName,  
       $parameterName,  ...