Acerca de las funciones

Descripción breve

Describe cómo crear y usar funciones en PowerShell.

Descripción larga

Una función es una lista de instrucciones de PowerShell que tiene un nombre que se asigna. Al ejecutar una función, escriba el nombre de la función. Las instrucciones de la lista se ejecutan como si hubiera escritolas en el símbolo del sistema.

Las funciones pueden ser tan simples como:

function Get-PowerShellProcess { Get-Process PowerShell }

Una función también puede ser tan compleja como un cmdlet o un programa de aplicación.

Al igual que los cmdlets, las funciones pueden tener parámetros. Los parámetros se pueden denominar, posicional, modificador o parámetros 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 o cmdlets. También puede especificar un valor devuelto mediante la palabra clave return. La return palabra clave no afecta ni suprime otros resultados devueltos por la función. Sin embargo, la return palabra clave sale de la función en esa línea. Para obtener más información, consulte about_Return.

La lista de instrucciones de la función puede contener distintos tipos de listas de instrucciones con las palabras clave Begin, Processy End. Estas instrucciones enumeran la entrada del controlador de la canalización de forma diferente.

Un filtro es un tipo especial de función que utiliza la Filter palabra clave.

Functions también puede actuar como cmdlets. Puede crear una función que funcione igual que un cmdlet sin usar C# la programación. Para obtener más información, consulte about_Functions_Advanced.

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:

Palabra Function clave
Un ámbito (opcional)
Un nombre que seleccione.
Cualquier número de parámetros con nombre (opcional)
Uno o varios comandos de PowerShell entre llaves {}

Para obtener más información sobre la palabra clave y los Dynamicparam parámetros dinámicos en las funciones, consulte about_Functions_Advanced_Parameters.

Funciones sencillas

Las funciones no tienen que ser complicadas para ser útiles. Las funciones más sencillas tienen el siguiente formato:

function <function-name> {statements}

Por ejemplo, la siguiente función inicia 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, escriba cada instrucción en una línea separada o use un punto y coma ; para separar las instrucciones.

Por ejemplo, la siguiente función busca todos los .jpg archivos de los directorios del usuario actual que se cambiaron 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-Object {$_.LastWriteTime -gt $Start}
}

Puede crear un cuadro de herramientas de funciones pequeñas útiles. Agregue estas funciones al perfil de PowerShell, como se describe en about_Profiles y versiones posteriores en este tema.

Nombres de función

Puede asignar cualquier nombre a una función, pero las funciones que comparta con otros usuarios deben seguir las reglas de nomenclatura que se han establecido para todos los comandos de PowerShell.

Los nombres de las funciones deben constar de un par verbo-sustantivo en el que el verbo identifica la acción que realiza la función y el sustantivo identifica el elemento en el que el cmdlet realiza su acción.

Las funciones deben usar los verbos estándar aprobados para todos los comandos de PowerShell. Estos verbos nos ayudan a mantener nuestros nombres de comando simples, coherentes y fáciles de entender para los usuarios.

Para obtener más información sobre los verbos estándar de PowerShell, consulte Verbos aprobados en Microsoft Docs.

Funciones con parámetros

Puede usar parámetros con funciones, incluidos los parámetros con nombre, los parámetros posicionales, los parámetros switch y los parámetros dinámicos. Para obtener más información sobre los parámetros dinámicos en las funciones, consulte about_Functions_Advanced_Parameters.

Parámetros con nombre

Puede definir cualquier número de parámetros con nombre. Puede incluir un valor predeterminado para los parámetros con nombre, como se describe más adelante en este tema.

Puede definir parámetros dentro de las llaves mediante la palabra clave Param , como se muestra en la siguiente sintaxis de ejemplo:

function <name> {
  param ([type]$parameter1[,[type]$parameter2])
  <statement list>
}

También puede definir parámetros fuera de las llaves sin la Param palabra clave , como se muestra en la sintaxis de ejemplo siguiente:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

A continuación se muestra un ejemplo de esta sintaxis alternativa.

Function Add-Numbers($one, $two) {
    $one + $two
}

Aunque se prefiere el primer método, no hay ninguna diferencia entre estos dos métodos.

Al ejecutar la función, el valor proporcionado para un parámetro se asigna a una variable que contiene el nombre del parámetro. El valor de esa variable se puede usar en la función .

El ejemplo siguiente es una función denominada Get-SmallFiles. Esta función tiene un $size parámetro . La función muestra todos los archivos que son más pequeños que el valor del $size parámetro y excluye los directorios:

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

En la función , puede usar la $size variable , que es el nombre definido para el parámetro .

Para usar esta función, escriba el siguiente comando:

Get-SmallFiles -Size 50

También puede escribir un valor para un parámetro con nombre sin el nombre del parámetro. Por ejemplo, el siguiente comando proporciona el mismo resultado que un comando que asigna un nombre al parámetro Size :

Get-SmallFiles 50

Para definir un valor predeterminado para un parámetro, escriba un signo igual y el valor después del nombre del parámetro, como se muestra en la siguiente variación del Get-SmallFiles ejemplo:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.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 ese valor.

Opcionalmente, puede proporcionar una breve cadena de ayuda 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 proporcionar una cadena de ayuda que describa el valor predeterminado (100) del parámetro Size en la Get-SmallFiles función, agregue el atributo PSDefaultValue como se muestra en el ejemplo siguiente.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $size = 100
  )
}

Para obtener más información sobre la clase de atributo PSDefaultValue , vea Miembros de atributo PSDefaultValue.

Parámetros posicionales

Un parámetro posicional es un parámetro sin un nombre de parámetro. PowerShell usa el orden de valor de parámetro para asociar cada valor de parámetro a un parámetro de la función .

Cuando se usan parámetros posicionales, escriba uno o varios valores después del nombre de la función. Los valores de parámetro posicional se asignan a la $args variable de matriz. El valor que sigue al nombre de la función se asigna a la primera posición de la $args matriz, $args[0].

La siguiente Get-Extension función agrega la extensión de nombre de .txt archivo a un nombre de archivo que proporcione:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Cambiar parámetros

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 switch.

Para definir un parámetro switch, especifique el tipo [switch] antes del nombre del parámetro, como se muestra en el ejemplo siguiente:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

Al escribir el parámetro switch On después del nombre de la función, la función muestra "Switch" (Activar). Sin el parámetro de interruptor, muestra "Apagar".

Switch-Item -on

Switch on

Switch-Item

Switch off

También puede asignar un valor booleano a un modificador al ejecutar la función, como se muestra en el ejemplo siguiente:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Uso de la expansión para representar parámetros de comando

Puede utilizar expansión para representar los parámetros de un comando. Esta característica se presenta en Windows PowerShell 3.0.

Use esta técnica en funciones que llaman a comandos en la sesión. No es necesario declarar o enumerar los parámetros del comando, ni cambiar la función cuando cambian los parámetros del comando.

La siguiente función de ejemplo llama al Get-Command cmdlet . El comando usa @Args para representar los parámetros de Get-Command.

function Get-MyCommand { Get-Command @Args }

Puede usar todos los parámetros de Get-Command cuando llama a la Get-MyCommand función. Los parámetros y los valores de parámetro se pasan al comando mediante @Args.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

La @Args característica usa el $Args parámetro automático, que representa los parámetros y valores de cmdlet no declarados de los argumentos restantes.

Para obtener más información sobre el salpicado, consulte about_Splatting.

Canalización de objetos a funciones

Cualquier función puede tomar la entrada de la canalización. Puede controlar cómo una función procesa la entrada desde la canalización mediante Beginlas palabras clave , Processy End . En la siguiente sintaxis de ejemplo se muestran las tres palabras clave:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

La Begin lista de instrucciones se ejecuta una sola vez, al principio de la función.

Importante

Si la función define un Beginbloque , ProcessEnd o , todo el código debe residir dentro de uno de los bloques.

La lista de Process instrucciones se ejecuta una vez para cada objeto de la canalización. Mientras se ejecuta el Process bloque, cada objeto de canalización se asigna a la $_ variable automática, un objeto de canalización cada vez.

Una vez que la función recibe todos los objetos de la canalización, la lista de End instrucciones se ejecuta una vez. Si no Beginse utilizan palabras clave , Process, o , todas End las instrucciones se tratan como una lista de End instrucciones.

La función siguiente usa la Process palabra clave . La función muestra ejemplos de la canalización:

function Get-Pipeline
{
  process {"The value is: $_"}
}

Para demostrar esta función, escriba una lista de números separados por comas, como se muestra en el siguiente ejemplo:

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Cuando se usa una función en una canalización, los objetos canalizado a la función se asignan a la $input variable automática. La función ejecuta instrucciones con la palabra clave Begin antes de que los objetos provengan de la canalización. La función ejecuta instrucciones con la palabra clave End después de recibir todos los objetos de la canalización.

En el ejemplo siguiente se muestra el $input variable automática con Begin y palabras clave de 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 los siguientes resultados:

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Cuando se ejecuta la Begin instrucción, la función no tiene la entrada de la canalización. La End instrucción se ejecuta después de que la función tenga los valores .

Si la función tiene una Process palabra clave , cada objeto de $input se quita de $input y se asigna a $_. En el ejemplo siguiente se incluye una Process lista de instrucciones:

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 Process instrucciones. Las Process instrucciones se ejecutan en cada objeto, un objeto cada vez. La $input variable automática está vacía cuando la función alcanza la End palabra clave .

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Para obtener más información, consulte Using Enumerators (Usar enumeradores).

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 siguiente filtro toma entradas de registro de la canalización y, a continuación, muestra toda la entrada o solo la parte del mensaje de la entrada:

filter Get-ErrorLog ([switch]$message)
{
  if ($message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Ámbito de la 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 las instrucciones de ese 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-Object {$_.DependentServices}
}

Cuando una función está en el ámbito global, puede usar la función 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 variables, solo existen en el ámbito de la función.

Para obtener más información sobre el ámbito en PowerShell, consulte about_Scopes.

Búsqueda y administración de funciones mediante la función : unidad

Todas las funciones y filtros de PowerShell se almacenan automáticamente en la Function: unidad. El proveedor de funciones de PowerShell expone esta unidad.

Al hacer referencia a la Function: unidad, escriba dos puntos después de Function, como haría al hacer referencia a la C unidad o D de un equipo.

El siguiente comando muestra todas las funciones de la sesión actual de 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 de Ayuda que viene con PowerShell, escriba:

(Get-ChildItem function:help).Definition

También puede usar la sintaxis siguiente.

$function:help

Para obtener más información sobre la unidad de Function:, consulte el tema de ayuda del proveedor Function. Escriba Get-Help Function.

Reutilización de funciones en nuevas sesiones

Al escribir una función en el símbolo del sistema de PowerShell, la función forma parte de la sesión actual. Está disponible hasta que finalice la sesión.

Para usar la función en todas las sesiones de PowerShell, agregue la función al perfil de PowerShell. Para obtener más información sobre los perfiles, vea about_Profiles.

También puede guardar la función en un archivo de script de PowerShell. Escriba la función en un archivo de texto y, a continuación, guarde el archivo con la extensión de nombre de .ps1 archivo.

Escribir ayuda para funciones

El cmdlet Get-Help obtiene ayuda para funciones, así como para cmdlets, proveedores y scripts. Para obtener ayuda para una función, escriba Get-Help seguido del nombre de la función.

Por ejemplo, para obtener ayuda para la Get-MyDisks función, escriba:

Get-Help Get-MyDisks

Puede escribir ayuda para una función mediante cualquiera de los dos métodos siguientes:

Ayuda basada en comentarios para funciones

Cree un tema de ayuda utilizando 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 obtener más información sobre 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 el tipo que se crea normalmente para los cmdlets. Se requiere ayuda basada en XML si está localizando temas de ayuda en varios idiomas.

Para asociar la función con el tema de ayuda basado en XML, use la palabra clave de ayuda basada en comentarios .ExternalHelp. Sin esta palabra clave, Get-Help no se puede encontrar el tema de ayuda de la función y las llamadas a Get-Help para que la función devuelva solo la ayuda generada automáticamente.

Para obtener más información sobre la ExternalHelp palabra clave , consulte about_Comment_Based_Help. Para obtener más información acerca de la ayuda basada en XML, vea Cómo escribir la ayuda de cmdlets en MSDN Library.