TEMA
about_Functions
DESCRIPCIÓN BREVE
Describe cómo crear y utilizar las funciones en Windows PowerShell.
DESCRIPCIÓN DETALLADA
Una función es una lista de instrucciones que tiene el nombre que
se le asigna. Cuando se ejecuta una función, se escribe su nombre. Las
instrucciones de la lista se ejecutan como si las hubiera escrito en
el símbolo del sistema.
Al igual que los cmdlets, las funciones pueden tener parámetros.
Los parámetros pueden ser con nombre, posicionales, de
modificador o dinámicos. Los parámetros de función se pueden leer
desde la línea de comandos o desde la canalización.
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 función 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 canalización.
Un filtro es un tipo especial de función que utiliza la palabra
clave Filter.
Las funciones también pueden comportarse como cmdlets. Se puede
crear una función que funcione exactamente igual que un cmdlet
sin utilizar la programación en C#. Para obtener más información, vea
about_Functions_Advanced.
Sintaxis
A continuación se muestra la sintaxis de una función:
function [<ámbito:>]<nombre> [([tipo]$parámetro1[,[tipo]$par
ámetro2])]
{
param([tipo]$parámetro1 [,[tipo]$parámetro2])
dynamicparam {<lista de instrucciones>}
begin {<lista de instrucciones>}
process {<lista de instrucciones>}
end {<lista de instrucciones>}
}
Una función incluye los elementos siguientes:
- Una palabra clave Function
- Un ámbito (opcional)
- Un nombre que se selecciona
- Cualquier cantidad de parámetros con nombre (opcionales)
- Uno o más comandos de Windows PowerShell agregados entre
llaves ({})
Para obtener más información sobre la palabra clave
Dynamicparam y los parámetros dinámicos en las funciones, vea
about_Functions_Advanced_Parameters.
Funciones simples
Las funciones no tienen que ser complicadas para resultar
útiles. La función 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 "<System>"}
}
Para ejecutar la función, escriba "other_env".
Se puede crear un cuadro de herramientas de funciones sencillas
que resulten útiles. En about_Profiles y más adelante en este
tema se describe cómo agregar estas funciones al perfil de
Windows PowerShell.
Funciones con parámetros
Se pueden utilizar parámetros con las funciones, incluidos los
parámetros con nombre, posicionales, de modificador y
dinámicos. Para obtener más información sobre los parámetros
dinámicos en las funciones, vea about_Functions_Advanced_Parameters.
Parámetros con nombre
Es posible definir cualquier cantidad de parámetros con nombre.
Para los parámetros con nombre se puede incluir un valor
predeterminado, tal y como se describe más adelante en este tema.
Los parámetros se pueden definir entre llaves mediante la
palabra clave Param, como se muestra en la sintaxis de ejemplo
siguiente:
function <nombre> {
param ([tipo]$parámetro1[,[tipo]$parámetro2])
<lista de instrucciones>
}
También es posible definir los parámetros fuera de las llaves
sin utilizar la palabra clave Param, como se muestra en la
sintaxis de ejemplo siguiente:
function <nombre> [([tipo]$parámetro1[,[tipo]$parámetro2])] {
<lista de instrucciones>
}
No hay ninguna diferencia entre estos dos métodos. Puede
utilizarse el que se prefiera.
Al ejecutar la función, el valor que se proporciona a un
parámetro se asigna a una variable que contiene el nombre del
parámetro. El valor de esa variable se puede utilizar en la
función.
El ejemplo siguiente es una función denominada Small_files.
Esta función tiene un parámetro $size. La función muestra todos
los archivos de tamaño inferior al valor del parámetro de $size
y excluye los directorios:
function small_files {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
En la función es posible utilizar la variable $size, que es el
nombre definido para el parámetro.
Para utilizar esta función, se escribe el comando siguiente:
C:\PS> function small_files -size 50
También se puede especificar un valor para un parámetro con
nombre sin el nombre del parámetro. Por ejemplo, el comando
siguiente proporciona el mismo resultado que un comando que
incluye el nombre del parámetro Size:
C:\PS> function small_files 50
Para definir un valor predeterminado para un parámetro, se
escribe un signo igual y el valor después del nombre del
parámetro, como se muestra en la variación 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 función asigna 100
a $size. Si se proporciona un valor, la función utiliza ese valor.
Parámetros posicionales
Un parámetro posicional es un parámetro sin nombre de
parámetro. Windows PowerShell utiliza el orden de los valores
del parámetro para asociar cada uno de esos valores a un
parámetro de la función.
Cuando se utilizan parámetros posicionales, deben escribirse
uno o más valores después del nombre de la función. Los valores
de los parámetros posicionales se asignan a la variable de
matriz $args. El valor que sigue al nombre de la función se
asigna a la primera posición de la matriz $args, $args[0].
La función Extension siguiente agrega la extensión .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 más de un parámetro posicional.
En el ejemplo siguiente se muestran todos los valores
especificados con el nombre de la función.
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 función se puede utilizar con cualquier número de valores.
La función asigna cada valor a una posición de la matriz $args.
Parámetros de modificador
Un modificador es un parámetro que no requiere un valor. En su
lugar, se escribe el nombre de la función seguido por el nombre
del parámetro de modificador.
Para definir un parámetro de modificador, se especifica el tipo
[switch] antes del nombre del parámetro, como se muestra en el
ejemplo siguiente:
function switchExample {
param ([switch]$on)
if ($on) { "Modificador sí" }
else { "Modificador no" }
}
Si se escribe el parámetro de modificador On después del nombre
de la función, la función muestra "Modificador sí". Sin el
parámetro de modificador, muestra "Modificador no"
C:\PS> SwitchExample -on
Modificador sí
C:\PS> SwitchExample
Modificador no
También se puede asignar un valor booleano a un modificador
cuando se ejecuta la función, 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 función puede aceptar entradas procedentes de la
canalización. Puede controlar cómo procesa una función las entradas
procedentes de la canalización mediante las palabras clave Begin,
Process y End. En la sintaxis de ejemplo siguiente se muestran las
tres palabras clave:
function <nombre> {
begin {<lista de instrucciones>}
process {<lista de instrucciones>}
end {<lista de instrucciones>}
}
La lista de instrucciones Begin se ejecuta una sola vez al
principio de la función.
La lista de instrucciones Process se ejecuta una vez por cada
objeto de la canalización.
Mientras se está ejecutando el bloque Process, los objetos de
la canalización se van asignando de uno en uno a la variable
automática $_.
Una vez que la función ha recibido todos los objetos de la
canalización, 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 función siguiente se utiliza la palabra clave Process. La
función muestra los ejemplos de la canalización:
function pipelineFunction
{
process {"El valor es: $_"}
}
Para demostrar cómo funciona esta función, se especifica una
matriz de números 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 función en una canalización, los objetos
canalizados a la función se asignan a la variable automática
$input. La función ejecuta las instrucciones con la palabra
clave Begin antes de que entre ningún objeto procedente de la
canalización. La función ejecuta las instrucciones con la
palabra clave End después de haber recibido todos los objetos
desde la canalización.
En el ejemplo siguiente se muestra la variable automática
$input con las palabras clave Begin y End.
function PipelineBeginEnd
{
begin {"Inicio: La entrada es $input"} end {"Fin: La
entrada es $input" }
}
Si esta función se ejecuta mediante la canalización, 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 instrucción Begin, la función no tiene
todavía la entrada de la canalización. La instrucción End se
ejecuta después de que la función haya recibido los valores.
Si la función 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 función se
envía a la lista de instrucciones de Process. Las instrucciones
de Process se ejecutan para cada objeto de uno en uno. La
variable automática $input está vacía cuando la función 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 función que se ejecuta en cada objeto de la
canalización. Un filtro se parece una función con todas sus
instrucciones en un bloque Process.
La sintaxis de un filtro es la siguiente:
filter [<ámbito:>]<nombre> {<lista de instrucciones>}
El filtro siguiente toma las entradas de registro de la
canalización y, a continuación, 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 función
Una función existe en el ámbito en el que se creó.
Si una función forma parte de un script, la función está
disponible para todas las instrucciones contenidas en ese
script. De forma predeterminada, una función de un script no
está disponible en el símbolo del sistema.
El ámbito de una función se puede especificar. Por ejemplo, en
el ejemplo siguiente la función se agrega al ámbito global:
function global:get-dependentsvs { get-service | where
{$_.dependentservices} }
Cuando una función pertenece al ámbito global, puede utilizarla
en scripts, en funciones y en la línea de comandos.
Las funciones suelen crear un ámbito. Los elementos creados en
una función, tales como las variables, existen solamente en el
ámbito de la función.
Para obtener más información 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
automáticamente 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 después del término Function, tal y como
se haría para referirse a la unidad C o D de un equipo.
En el comando siguiente se muestran todas las funciones de la
sesión actual de Windows PowerShell:
C:\PS> dir function:
Los comandos de la función se almacenan como un bloque de
script en la propiedad de definición de la función. Por
ejemplo, para mostrar los comandos de la función Help que se
suministra con Windows PowerShell, se escribe:
(dir function:help).definition
Para obtener más información sobre la unidad Function:, vea
Function.
Reutilizar funciones en sesiones nuevas
Cuando se escribe una función en el símbolo del sistema de
Windows PowerShell, la función pasa a formar parte de la sesión
actual. Está disponible hasta que finaliza esta sesión.
Para utilizar la función en todas las sesiones de Windows
PowerShell, deberá agregarse la función al perfil de Windows
PowerShell del usuario. Para obtener más información sobre los
perfiles, vea about_Profiles.
También se puede guardar la función en un archivo de script de
Windows PowerShell. Para ello, se escribe la función en un
archivo de texto y, a continuación, este archivo se guarda con
la extensión 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 función, se escribe Get-Help y, a continuación, el nombre de
la función.
Por ejemplo, para ver la ayuda de la función MisDiscos, se debe
escribir:
get-help MisDiscos
Puede escribir la ayuda de una función mediante cualquiera de los
dos métodos 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 función, los comentarios se deben
colocar al principio o al final del cuerpo de la función o en
las líneas que preceden a la palabra clave function. Para
obtener más información 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 función al tema de ayuda basada en XML, se
utiliza la palabra clave de comentario de ayuda
.ExternalHelp. Para obtener más información sobre la palabra clave
ExternalHelp, vea about_Comment_Based_Help. Para obtener más
información sobre la ayuda basada en XML, vea el tema acerca de cómo
se escribe la ayuda de los cmdlets en MSDN.
VEA TAMBIÉN
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (proveedor)