TEMA about_FunctionsDESCRIPCIN BREVE Describe cmo crear y utilizar las funciones en Windows PowerShell. DESCRIPCIN DETALLADA Una funcin es una lista de instrucciones que tiene el nombre que se le asigna. Cuando se ejecuta una funcin, se escribe su nombre. Las instrucciones de la lista se ejecutan como si las hubiera escrito en el smbolo del sistema. Al igual que los cmdlets, las funciones pueden tener parmetros. Los parmetros pueden ser con nombre, posicionales, de modificador o dinmicos. Los parmetros de funcin se pueden leer desde la lnea de comandos o desde la canalizacin. Las funciones pueden devolver valores que se pueden mostrar, asignar a variables o pasar a otras funciones o a cmdlets. La lista de instrucciones de la funcin puede contener tipos diferentes de listas de instrucciones con las palabras clave Begin, Process y End. Estas listas de instrucciones controlan de manera diferente las entradas procedentes de la canalizacin. Un filtro es un tipo especial de funcin que utiliza la palabra clave Filter. Las funciones tambin pueden comportarse como cmdlets. Se puede crear una funcin que funcione exactamente igual que un cmdlet sin utilizar la programacin en C#. Para obtener ms informacin, vea about_Functions_Advanced. Sintaxis A continuacin se muestra la sintaxis de una funcin: function [] [([tipo]$parmetro1[,[tipo]$par metro2])] { param([tipo]$parmetro1 [,[tipo]$parmetro2]) dynamicparam {} begin {} process {} end {} } Una funcin incluye los elementos siguientes: - Una palabra clave Function - Un mbito (opcional) - Un nombre que se selecciona - Cualquier cantidad de parmetros con nombre (opcionales) - Uno o ms comandos de Windows PowerShell agregados entre llaves ({}) Para obtener ms informacin sobre la palabra clave Dynamicparam y los parmetros dinmicos en las funciones, vea about_Functions_Advanced_Parameters. Funciones simples Las funciones no tienen que ser complicadas para resultar tiles. La funcin siguiente obtiene las variables de entorno que no pertenecen a la cuenta System del sistema actual: function other_env { get-wmiObject win32_environment | where {$_.nombreusuario -ne ""} } Para ejecutar la funcin, escriba "other_env". Se puede crear un cuadro de herramientas de funciones sencillas que resulten tiles. En about_Profiles y ms adelante en este tema se describe cmo agregar estas funciones al perfil de Windows PowerShell. Funciones con parmetros Se pueden utilizar parmetros con las funciones, incluidos los parmetros con nombre, posicionales, de modificador y dinmicos. Para obtener ms informacin sobre los parmetros dinmicos en las funciones, vea about_Functions_Advanced_Parameters. Parmetros con nombre Es posible definir cualquier cantidad de parmetros con nombre. Para los parmetros con nombre se puede incluir un valor predeterminado, tal y como se describe ms adelante en este tema. Los parmetros se pueden definir entre llaves mediante la palabra clave Param, como se muestra en la sintaxis de ejemplo siguiente: function { param ([tipo]$parmetro1[,[tipo]$parmetro2]) } Tambin es posible definir los parmetros fuera de las llaves sin utilizar la palabra clave Param, como se muestra en la sintaxis de ejemplo siguiente: function [([tipo]$parmetro1[,[tipo]$parmetro2])] { } No hay ninguna diferencia entre estos dos mtodos. Puede utilizarse el que se prefiera. Al ejecutar la funcin, el valor que se proporciona a un parmetro se asigna a una variable que contiene el nombre del parmetro. El valor de esa variable se puede utilizar en la funcin. El ejemplo siguiente es una funcin denominada Small_files. Esta funcin tiene un parmetro $size. La funcin muestra todos los archivos de tamao inferior al valor del parmetro de $size y excluye los directorios: function small_files { param ($size) Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } En la funcin es posible utilizar la variable $size, que es el nombre definido para el parmetro. Para utilizar esta funcin, se escribe el comando siguiente: C:\PS> function small_files -size 50 Tambin se puede especificar un valor para un parmetro con nombre sin el nombre del parmetro. Por ejemplo, el comando siguiente proporciona el mismo resultado que un comando que incluye el nombre del parmetro Size: C:\PS> function small_files 50 Para definir un valor predeterminado para un parmetro, se escribe un signo igual y el valor despus del nombre del parmetro, como se muestra en la variacin siguiente del ejemplo de Small_files: function small_files ($size = 100) { Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } Si se escribe "small_files" sin un valor, la funcin asigna 100 a $size. Si se proporciona un valor, la funcin utiliza ese valor. Parmetros posicionales Un parmetro posicional es un parmetro sin nombre de parmetro. Windows PowerShell utiliza el orden de los valores del parmetro para asociar cada uno de esos valores a un parmetro de la funcin. Cuando se utilizan parmetros posicionales, deben escribirse uno o ms valores despus del nombre de la funcin. Los valores de los parmetros posicionales se asignan a la variable de matriz $args. El valor que sigue al nombre de la funcin se asigna a la primera posicin de la matriz $args, $args[0]. La funcin Extension siguiente agrega la extensin .txt a un nombre de archivo proporcionado por el usuario: function extension { $name = $args[0] + ".txt" $name } C:\PS> extension miArchivoDeTexto miArchivoDeTexto.txt Las funciones pueden tomar ms de un parmetro posicional. En el ejemplo siguiente se muestran todos los valores especificados con el nombre de la funcin. function repeat { foreach ($arg in $args) { "La entrada es $arg" } } C:\PS>repeat uno La entrada es uno C:\PS> repeat uno dos tres La entrada es uno La entrada es dos La entrada es tres Esta funcin se puede utilizar con cualquier nmero de valores. La funcin asigna cada valor a una posicin de la matriz $args. Parmetros de modificador Un modificador es un parmetro que no requiere un valor. En su lugar, se escribe el nombre de la funcin seguido por el nombre del parmetro de modificador. Para definir un parmetro de modificador, se especifica el tipo [switch] antes del nombre del parmetro, como se muestra en el ejemplo siguiente: function switchExample { param ([switch]$on) if ($on) { "Modificador s" } else { "Modificador no" } } Si se escribe el parmetro de modificador On despus del nombre de la funcin, la funcin muestra "Modificador s". Sin el parmetro de modificador, muestra "Modificador no" C:\PS> SwitchExample -on Modificador s C:\PS> SwitchExample Modificador no Tambin se puede asignar un valor booleano a un modificador cuando se ejecuta la funcin, como se muestra en el ejemplo siguiente: C:\PS> SwitchExample -on:$true Modificador s C:\PS> SwitchExample -on:$false Modificador no Canalizar objetos a las funciones Cualquier funcin puede aceptar entradas procedentes de la canalizacin. Puede controlar cmo procesa una funcin las entradas procedentes de la canalizacin mediante las palabras clave Begin, Process y End. En la sintaxis de ejemplo siguiente se muestran las tres palabras clave: function { begin {} process {} end {} } La lista de instrucciones Begin se ejecuta una sola vez al principio de la funcin. La lista de instrucciones Process se ejecuta una vez por cada objeto de la canalizacin. Mientras se est ejecutando el bloque Process, los objetos de la canalizacin se van asignando de uno en uno a la variable automtica $_. Una vez que la funcin ha recibido todos los objetos de la canalizacin, se ejecuta una vez la lista de instrucciones End. Si no se utiliza ninguna de las palabras clave Begin, Process o End, todas las instrucciones se tratan como si fueran una lista de instrucciones End. En la funcin siguiente se utiliza la palabra clave Process. La funcin muestra los ejemplos de la canalizacin: function pipelineFunction { process {"El valor es: $_"} } Para demostrar cmo funciona esta funcin, se especifica una matriz de nmeros creada con comas, como se muestra en el ejemplo siguiente: C:\PS> 1,2,4 | pipelineFunction El valor es: 1 El valor es: 2 El valor es: 4 Cuando se utiliza una funcin en una canalizacin, los objetos canalizados a la funcin se asignan a la variable automtica $input. La funcin ejecuta las instrucciones con la palabra clave Begin antes de que entre ningn objeto procedente de la canalizacin. La funcin ejecuta las instrucciones con la palabra clave End despus de haber recibido todos los objetos desde la canalizacin. En el ejemplo siguiente se muestra la variable automtica $input con las palabras clave Begin y End. function PipelineBeginEnd { begin {"Inicio: La entrada es $input"} end {"Fin: La entrada es $input" } } Si esta funcin se ejecuta mediante la canalizacin, muestra los resultados siguientes: C:\PS> 1,2,4 | PipelineBeginEnd Inicio: La entrada es Fin: La entrada es 1 2 4 Cuando se ejecuta la instruccin Begin, la funcin no tiene todava la entrada de la canalizacin. La instruccin End se ejecuta despus de que la funcin haya recibido los valores. Si la funcin tiene una palabra clave Process, lee los datos que hay en $input. En el ejemplo siguiente hay una lista de instrucciones de Process: function PipelineInput { process {"Procesando: $_ " } end {"Fin: La entrada es: $input" } } En este ejemplo, cada objeto que se canaliza a la funcin se enva a la lista de instrucciones de Process. Las instrucciones de Process se ejecutan para cada objeto de uno en uno. La variable automtica $input est vaca cuando la funcin llega a la palabra clave End. C:\PS> 1,2,4 | PipelineInput Procesando: 1 Procesando: 2 Procesando: 4 Fin: La entrada es: Filtros Un filtro es un tipo de funcin que se ejecuta en cada objeto de la canalizacin. Un filtro se parece una funcin con todas sus instrucciones en un bloque Process. La sintaxis de un filtro es la siguiente: filter [] {} El filtro siguiente toma las entradas de registro de la canalizacin y, a continuacin, muestra la entrada entera o bien nicamente la parte de ella correspondiente al mensaje: filter ErrorLog ([switch]$message) { if ($message) { out-host -inputobject $_.Message } else { $_ } } mbito de una funcin Una funcin existe en el mbito en el que se cre. Si una funcin forma parte de un script, la funcin est disponible para todas las instrucciones contenidas en ese script. De forma predeterminada, una funcin de un script no est disponible en el smbolo del sistema. El mbito de una funcin se puede especificar. Por ejemplo, en el ejemplo siguiente la funcin se agrega al mbito global: function global:get-dependentsvs { get-service | where {$_.dependentservices} } Cuando una funcin pertenece al mbito global, puede utilizarla en scripts, en funciones y en la lnea de comandos. Las funciones suelen crear un mbito. Los elementos creados en una funcin, tales como las variables, existen solamente en el mbito de la funcin. Para obtener ms informacin sobre el mbito en Windows PowerShell, vea about_Scope. Buscar y administrar funciones mediante la unidad Function: Todas las funciones y los filtros de Windows PowerShell se almacenan automticamente en la unidad Function:. El proveedor Function de Windows PowerShell expone esta unidad. Al hacer referencia a la unidad Function:, es preciso escribir un signo de dos puntos despus del trmino Function, tal y como se hara para referirse a la unidad C o D de un equipo. En el comando siguiente se muestran todas las funciones de la sesin actual de Windows PowerShell: C:\PS> dir function: Los comandos de la funcin se almacenan como un bloque de script en la propiedad de definicin de la funcin. Por ejemplo, para mostrar los comandos de la funcin Help que se suministra con Windows PowerShell, se escribe: (dir function:help).definition Para obtener ms informacin sobre la unidad Function:, vea Function. Reutilizar funciones en sesiones nuevas Cuando se escribe una funcin en el smbolo del sistema de Windows PowerShell, la funcin pasa a formar parte de la sesin actual. Est disponible hasta que finaliza esta sesin. Para utilizar la funcin en todas las sesiones de Windows PowerShell, deber agregarse la funcin al perfil de Windows PowerShell del usuario. Para obtener ms informacin sobre los perfiles, vea about_Profiles. Tambin se puede guardar la funcin en un archivo de script de Windows PowerShell. Para ello, se escribe la funcin en un archivo de texto y, a continuacin, este archivo se guarda con la extensin de nombre de archivo .ps1. Escribir ayuda para las funciones El cmdlet Get-Help permite ver la ayuda de las funciones, as como de los cmdlets, proveedores y scripts. Para ver la ayuda de una funcin, se escribe Get-Help y, a continuacin, el nombre de la funcin. Por ejemplo, para ver la ayuda de la funcin MisDiscos, se debe escribir: get-help MisDiscos Puede escribir la ayuda de una funcin mediante cualquiera de los dos mtodos siguientes: -- Ayuda basada en comentario para funciones Es posible crear un tema de ayuda mediante el uso de palabras clave especiales en los comentarios. Para crear ayuda basada en comentario para una funcin, los comentarios se deben colocar al principio o al final del cuerpo de la funcin o en las lneas que preceden a la palabra clave function. Para obtener ms informacin sobre la ayuda basada en comentario, vea about_Comment_Based_Help. -- Ayuda basada en XML para funciones Se crea un tema de ayuda basada en XML, del tipo de los que suelen crearse para los cmdlets. La ayuda basada en XML es necesaria cuando se van a traducir los temas de ayuda a varios idiomas. Para asociar la funcin al tema de ayuda basada en XML, se utiliza la palabra clave de comentario de ayuda .ExternalHelp. Para obtener ms informacin sobre la palabra clave ExternalHelp, vea about_Comment_Based_Help. Para obtener ms informacin sobre la ayuda basada en XML, vea el tema acerca de cmo se escribe la ayuda de los cmdlets en MSDN.VEA TAMBIN about_Automatic_Variables about_Comment_Based_Help about_Functions_Advanced about_Functions_CmdletBindingAttribute about_Parameters about_Profiles about_Scopes about_Script_Blocks Function (proveedor)