about_Functions
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0
TEMA
about_Functions
DESCRIPCIÓN BREVE
Describe cómo crear y utilizar funciones en Windows PowerShell®.
DESCRIPCIÓN LARGA
Una función es una lista de instrucciones de Windows PowerShell que tiene un nombre que le asigna. Cuando ejecuta una función, escribe el nombre de la función. Las instrucciones de la lista se ejecutan como si las hubiera escrito en el símbolo del sistema.
Las funciones pueden ser tan simples como:
function Get-PowerShellProcess {Get-Process PowerShell}
o tan complejas como un cmdlet o un programa de aplicación.
Al igual que los cmdlets, las funciones pueden tener parámetros. Los parámetros pueden ser con nombre, de posición, 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 pasarse a otras funciones u otros cmdlets.
La lista de instrucciones de la función puede contener distintos tipos de listas de instrucciones con las palabras clave Begin, Process y End. Estas listas de instrucciones controlan la entrada de la canalización de manera diferente.
Un filtro es un tipo especial de función que utiliza la palabra clave Filter.
Las funciones también pueden actuar como cmdlets. Puede crear una función que funcione igual que un cmdlet sin utilizar programación en C#. Para más información, consulte about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511).
Sintaxis
A continuación se muestra la sintaxis de una función:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Una función incluye los siguientes elementos:
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
Para más información sobre la palabra clave Dynamicparam y los parámetros dinámicos en funciones, consulte about_Functions_Advanced_Parameters.
Funciones simples
Las funciones no tienen que ser complicadas para resultar útiles. Las funciones más sencillas tienen el formato siguiente:
function <function-name> {statements}
Por ejemplo, la siguiente función inicia Windows PowerShell con la opción Ejecutar como administrador.
function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}
Para usar la función, escriba: Start-PSAdmin
Para agregar instrucciones a la función, utilice un punto y coma (;) para separar las instrucciones o escriba cada instrucción en una línea independiente.
Por ejemplo, la función siguiente busca todos los archivos .jpg en los directorios del usuario actual que se han cambiado después de la fecha de inicio.
function Get-NewPix
{
$start = Get-Date -Month 1 -Day 1 -Year 2010
$allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
$allpix | where {$_.LastWriteTime -gt $Start}
}
Puede crear un cuadro de herramientas de funciones pequeñas útiles. Agregue estas funciones a su perfil de Windows PowerShell, tal y como se describe en about_Profiles y más adelante en este tema.
Nombres de funciones
Puede asignar el nombre que quiera a una función, pero las funciones que se comparten con otros usuarios deberían seguir las reglas de nomenclatura que se establecieron para todos los comandos de Windows PowerShell.
Los nombres de funciones deberían constar de un par de verbo y sustantivo, donde el verbo identifica la acción que realiza la función y el sustantivo identifica el elemento sobre el que el cmdlet realiza su acción.
Las funciones deberían usar los verbos estándares que se han aprobado para todos los comandos de Windows PowerShell. Estos verbos ayudan a mantener los nombres de comandos simples, coherentes y fáciles de entender para los usuarios.
Para más información sobre los verbos estándares de Windows PowerShell, consulte "Verbos de Cmdlets" en MSDN, en el vínculo https://go.microsoft.com/fwlink/?LinkID=160773.
FUNCIONES CON PARÁMETROS
Puede utilizar parámetros con las funciones, incluidos los parámetros con nombre, parámetros posicionales, parámetros de modificador y parámetros dinámicos. Para más información sobre los parámetros dinámicos en las funciones, consulte about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).
Parámetros con nombre
Puede definir un número cualquiera de parámetros con nombre. Puede incluir un valor predeterminado para los parámetros con nombre, tal y como se describe más adelante en este tema.
Puede definir parámetros entre llaves con la palabra clave Param, tal y como se muestra en la sintaxis de ejemplo siguiente:
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
También puede definir parámetros fuera de las llaves sin la palabra clave Param, tal y como se muestra en la sintaxis de ejemplo siguiente:
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
No hay ninguna diferencia entre estos dos métodos. Utilice el método que prefiera.
Cuando ejecuta la función, el valor que facilita para 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 llamada Get-SmallFiles. Esta función tiene un parámetro $size. La función muestra todos los archivos que son menores que el valor del parámetro $size y excluye los directorios:
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
En la función, puede utilizar la variable $size, que es el nombre definido para el parámetro.
Para utilizar esta función, escriba el siguiente comando:
C:\PS> function Get-SmallFiles –Size 50
También puede especificar un valor para un parámetro con nombre sin el nombre del parámetro. Por ejemplo, el comando siguiente da el mismo resultado que un comando que nombra el parámetro Size:
C:\PS> function Get-SmallFiles 50
Para definir un valor predeterminado de un parámetro, escriba un signo igual y el valor después del nombre del parámetro, tal y como se muestra en la siguiente variante del ejemplo de Get-SmallFiles:
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Si escribe "Get-SmallFiles" sin un valor, la función asigna 100 a $size. Si proporciona un valor, la función usa dicho valor.
Si lo desea, puede proporcionar una cadena de ayuda breve que describa el valor predeterminado del parámetro, agregando el atributo PSDefaultValue a la descripción del parámetro y especificando la propiedad Help de PSDefaultValue. Para ofrecer una cadena de ayuda que describa el valor predeterminado (100) del parámetro Size de la función Get-SmallFiles, agregue el atributo PSDefaultValue tal y como se muestra en el ejemplo siguiente.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
Para más información sobre la clase del atributo PSDefaultValue, vea Miembros del atributo PSDefaultValue en MSDN. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx
Parámetros posicionales
Un parámetro posicional es un parámetro sin un nombre de parámetro. Windows PowerShell usa el orden del valor de parámetro para asociar cada valor de parámetro a un parámetro de la función.
Cuando utilice parámetros posicionales, escriba uno o varios valores después del nombre de la función. Los valores del parámetro posicional se asignan a la variable de matriz $args. El valor que se indica a continuación del nombre de la función se asigna a la primera posición de la matriz de $args, $args[0].
La siguiente función Get-extensión agrega la extensión de nombre de archivo .txt a un nombre de archivo que facilite:
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
PARÁMETROS DE MODIFICADOR
Un modificador es un parámetro que no requiere un valor. En su lugar, escriba el nombre de la función seguido del nombre del parámetro de modificador.
Para definir un parámetro de modificador, especifique el tipo [switch] delante del nombre del parámetro, tal y como se muestra en el ejemplo siguiente:
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
Cuando escriba el parámetro de modificador On después del nombre de la función, la función muestra "Switch on". Sin el parámetro de modificador, muestra "Switch off".
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
También puede asignar un valor booleano a un modificador cuando se ejecuta la función, tal y como se muestra en el ejemplo siguiente:
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
Uso de empaquetamiento para representar parámetros de comando
Puede usar el empaquetamiento para representar los parámetros de un comando. Esta característica se introdujo en Windows PowerShell 3.0.
Utilice esta técnica en las funciones que llaman a comandos en la sesión. No necesita declarar ni enumerar los parámetros del comando, ni cambiar la función cuando cambien los parámetros del comando.
La siguiente función de ejemplo llama al cmdlet Get-Command. El comando utiliza @Args para representar los parámetros de Get-Command.
function Get-MyCommand { Get-Command @Args }
Puede utilizar todos los parámetros de Get-Command cuando llama a la función Get-MyCommand. Los parámetros y los valores de los parámetros se pasan al comando con @Args.
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
La característica @Args utiliza el parámetro automático $Args, que representa los parámetros de cmdlet no declarados y los valores de los argumentos restantes.
Para más información sobre el empaquetamiento, consulte about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720).
Canalización de objetos a funciones
Cualquier función puede tomar entradas desde la canalización. Puede controlar la forma en que una función procesa la entrada desde la canalización con las palabras clave Begin, Process y End. La sintaxis de ejemplo siguiente muestra las tres palabras clave:
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
La lista de instrucciones Begin se ejecuta solo una 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 ejecuta el bloque Process, cada objeto de la canalización se asigna a la variable automática $_, un objeto de canalización detrás de otro.
Cuando la función recibe todos los objetos de la canalización, la lista de la instrucción End se ejecuta una vez. Si no se utilizan las palabras clave Begin, Process o End, todas las instrucciones se tratan como una lista de instrucciones End.
La función siguiente utiliza la palabra clave Process. La función muestra ejemplos desde la canalización:
function Get-Pipeline
{
process {"The value is: $_"}
}
Para mostrar esta función, escriba una lista de números separados por comas, como se muestra en el ejemplo siguiente:
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Cuando se utiliza una función en una canalización, los objetos que se canalizan a la función se asignan a la variable automática $input. La función ejecuta instrucciones con la palabra clave Begin antes de que ningún objeto proceda de la canalización. La función ejecuta instrucciones con la palabra clave End después de que se hayan recibido todos los objetos de la canalización.
En el ejemplo siguiente se muestra la variable automática $input con las palabras clave Begin y End.
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
Si esta función se ejecuta mediante la canalización, muestra el siguiente resultado:
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Cuando se ejecuta la instrucción Begin, la función no tiene la entrada de la canalización. La instrucción End se ejecuta después de que la función tenga los valores.
Si la función tiene una palabra clave Process, la función lee los datos de $input. En el ejemplo siguiente se tiene una lista de instrucciones Process:
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
En este ejemplo, cada objeto que se canaliza a la función se envía a la lista de instrucciones Process. Las instrucciones Process se ejecutan en cada objeto, un objeto detrás de otro. La variable automática $input está vacía cuando la función llega a la palabra clave End.
C:\PS> 1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Filtros
Un filtro es un tipo de función que se ejecuta en cada objeto de la canalización. Un filtro es similar a una función con todas sus instrucciones en un bloque Process.
La sintaxis de un filtro es la siguiente:
filter [<scope:>]<name> {<statement list>}
El filtro siguiente toma las entradas del registro de la canalización y, después, muestra la entrada completa o solamente la parte del mensaje de la entrada:
filter Get-ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Ámbito de la función
Existe una función en el ámbito en el que se creó.
Si una función es parte de un script, la función está disponible para las instrucciones dentro de este script. De forma predeterminada, una función de un script no está disponible en el símbolo del sistema.
Puede especificar el ámbito de una función. Por ejemplo, la función se agrega al ámbito global en el ejemplo siguiente:
function global:Get-DependentSvs { Get-Service |
where {$_.DependentServices} }
Si una función está en el ámbito global, puede utilizarla en scripts, en funciones y en la línea de comandos.
Normalmente, las funciones crean un ámbito. Los elementos creados en una función, como las variables, solo existen en el ámbito de la función.
Para más información sobre los ámbitos en Windows PowerShell, consulte about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260).
Búsqueda y administración de funciones con 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.
Cuando haga referencia a la unidad Function:, escriba dos puntos después de Function, como lo haría para hacer referencia a las unidades C o D de un equipo.
El siguiente comando muestra todas las funciones de la sesión actual de Windows PowerShell:
Get-ChildItem 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 incluye con Windows PowerShell, escriba:
(Get-ChildItem function:help).Definition
Para más información sobre la unidad Function:, vea el tema de ayuda del proveedor Function. Escriba "Get-Help Function" o consúltelo en la Biblioteca de TechNet, en el vínculo https://go.microsoft.com/fwlink/?LinkID=113436.
Reutilización de funciones en nuevas sesiones
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 la sesión.
Para usar la función en todas las sesiones de Windows PowerShell, agregue la función al perfil de Windows PowerShell. Para más información sobre los perfiles, consulte about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729).
También puede guardar su función en un archivo de script de Windows PowerShell. Escriba su función en un archivo de texto y, después, guarde el archivo con la extensión de nombre de archivo .ps1.
Redacción de ayuda de funciones
El cmdlet Get-Help obtiene ayuda para las funciones, así como para los cmdlets, proveedores y scripts. Para obtener ayuda sobre una función, escriba Get-Help seguido del nombre de la función.
Por ejemplo, para obtener ayuda sobre la función Get-MyDisks, escriba:
Get-Help Get-MyDisks
Puede escribir ayuda para una función con cualquiera de los dos métodos siguientes:
Ayuda basada en comentarios para funciones
Cree un tema de ayuda mediante el uso de palabras clave especiales en los comentarios. Para crear ayuda basada en comentarios para una función, los comentarios deben colocarse al principio o al final del cuerpo de la función o en las líneas anteriores a la palabra clave function. Para más información sobre de la ayuda basada en comentarios, consulte about_Comment_Based_Help.
Ayuda basada en XML para funciones
Cree un tema de ayuda basado en XML, como por ejemplo el tipo que suele crearse para cmdlets. La ayuda basada en XML es necesaria si los temas de ayuda se localizan a varios idiomas.
Para asociar la función al tema de ayuda basado en XML, use la palabra clave de ayuda basada en comentarios ExternalHelp. Sin esta palabra clave, Get-Help no encuentra el tema de ayuda de la función y las llamadas a Get-Help para la función devuelven solamente ayuda generada automáticamente.
Para obtener más información acerca de la palabra clave ExternalHelp, consulte about_Comment_Based_Help. Para más información sobre la ayuda basada en XML, consulte "Cómo escribir ayuda de cmdlets" en MSDN.
VEA TAMBIÉN
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Función (proveedor)