about_Functions
Describe cómo crear y usar funciones en PowerShell.
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 pwsh }
Una vez definida una función, puede usarla como los cmdlets integrados. Por ejemplo, para llamar a la función Get-PowerShellProcess recién definida:
Get-PowerShellProcess
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
110 78.72 172.39 10.62 10936 1 pwsh
Una función también puede ser tan compleja como un cmdlet o una 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 palabra clave return no afecta ni suprime otra salida devuelta de la función. Sin embargo, la palabra clave return sale de la función en esa línea. Para obtener más información, vea about_Return.
La lista de instrucciones de la función puede contener distintos tipos de listas de instrucciones con las palabras clave begin, process, endy clean. Estas instrucciones enumeran la entrada del controlador de la canalización de forma diferente.
El filtro palabra clave se usa para crear 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.
Functions también puede actuar como cmdlets. Puede crear una función que funcione igual que un cmdlet sin usar C# programación. Para obtener más información, vea about_Functions_Advanced.
Importante
Dentro de los archivos de script y los módulos basados en scripts, se deben definir funciones para poder llamar a ellas.
A continuación se muestra la sintaxis de una función:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
begin {<statement list>}
process {<statement list>}
end {<statement list>}
clean {<statement list>}
}
function [<scope:>]<name>
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
clean {<statement list>}
}
Una función incluye los siguientes elementos:
- Palabra clave
function - 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 dynamicparam y los parámetros dinámicos en las funciones, vea about_Functions_Advanced_Parameters.
Los métodos descritos en esta sección se conocen como métodos de procesamiento de entrada. En el caso de las funciones, estos tres métodos se representan mediante los bloques begin, processy end de la función. PowerShell 7.3 agrega un método de proceso de bloque clean.
No es necesario usar ninguno de estos bloques en las funciones. Si no usa un bloque con nombre, PowerShell coloca el código en el bloque end de la función. Sin embargo, si usa cualquiera de estos bloques con nombre o define un bloque dynamicparam, debe colocar todo el código en un bloque con nombre.
En el ejemplo siguiente se muestra el esquema de una función que contiene un bloque de begin para el preprocesamiento único, un bloque de process para varios procesamientos de registros y un bloque de end para el procesamiento posterior de un solo uso.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
begin{}
process{}
end{}
}
Este bloque se usa para proporcionar preprocesamiento opcional de un solo uso para la función. El tiempo de ejecución de PowerShell usa el código de este bloque una vez para cada instancia de la función de la canalización.
Este bloque se usa para proporcionar procesamiento de registros por registro para la función. Puede usar un bloque process sin definir los demás bloques. El número de ejecuciones de bloques de process depende de cómo use la función y de qué entrada recibe la función.
La variable automática $_ o $PSItem contiene el objeto actual de la canalización para su uso en el bloque process. El $input variable automática contiene un enumerador que solo está disponible para funciones y bloques de script.
Para obtener más información, vea about_Automatic_Variables.
- Al llamar a la función al principio o fuera de una canalización, se ejecuta el bloque
processuna vez. - Dentro de una canalización, el bloque
processse ejecuta una vez para cada objeto de entrada que alcanza la función. - Si la entrada de canalización que alcanza la función está vacía, el bloque
processno ejecutar.- Los bloques
begin,endycleanse siguen ejecutando.
- Los bloques
Importante
Si se establece un parámetro de función para aceptar la entrada de canalización y no se define un bloque de process, se producirá un error en el procesamiento de registros por registro. En este caso, la función solo se ejecutará una vez, independientemente de la entrada.
Este bloque se usa para proporcionar el procesamiento posterior opcional de una sola vez para la función.
El bloque clean se agregó en PowerShell 7.3.
El bloque clean es una manera cómoda de limpiar los recursos que abarcan los bloques begin, processy end. Es semánticamente similar a un bloque de finally que cubre todos los demás bloques con nombre de una función de script o un cmdlet de script. La limpieza de recursos se aplica para los siguientes escenarios:
- cuando la ejecución de la canalización finaliza normalmente sin errores de terminación
- cuando se interrumpe la ejecución de la canalización debido a un error de terminación
- cuando la canalización se detiene
Select-Object -First - cuando se detiene la canalización ctrl+c o
StopProcessing()
El bloque limpio descarta cualquier salida escrita en el flujo de Correcto.
Precaución
Agregar el bloque clean es un cambio importante. Dado que clean se analiza como palabra clave, impide que los usuarios llamen directamente a un comando denominado clean como la primera instrucción de un bloque de script. Sin embargo, es probable que no sea un problema. El comando todavía se puede invocar mediante el operador de llamada (& clean).
Las funciones no tienen que ser complicadas de 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 independiente o use un ; de punto y coma para separar las instrucciones.
Por ejemplo, la siguiente función busca todos los archivos .jpg en 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.
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 funciones deben constar de un par verbo-sustantivo donde el verbo identifica la acción que realiza la función y el nombre 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 los nombres de comandos 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.
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, vea about_Functions_Advanced_Parameters.
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 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, 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([int]$one, [int]$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 parámetro $Size. La función muestra todos los archivos que son más pequeños que el valor del parámetro $Size 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 variable $Size, 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 el nombre 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 ejemplo de Get-SmallFiles:
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; para ello, agregue el atributo PSDefaultValue a la descripción del parámetro y especifique la propiedad Help de PSDefaultValue. Para proporcionar una cadena de ayuda que describa el valor predeterminado (100) del parámetro Size en la función Get-SmallFiles, agregue el atributo PSDefaultValue como se muestra en el ejemplo siguiente.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$Size = 100
)
Get-ChildItem $HOME | Where-Object {
$_.Length -lt $Size -and !$_.PSIsContainer
}
}
Para obtener más información sobre la clase de atributo PSDefaultValue, vea miembros de atributo PSDefaultValue.
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 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 siguiente función Get-Extension agrega la extensión .txt nombre de archivo a un nombre de archivo que proporcione:
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
Get-Extension myTextFile
myTextFile.txt
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 de On después del nombre de la función, la función muestra Switch on. Sin el parámetro switch, muestra Switch off.
Switch-Item -on
Switch on
Switch-Item
Switch off
También puede asignar un valor de 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
Puede usar la 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 ni enumerar los parámetros de comando ni cambiar la función cuando cambien los parámetros de comando.
La siguiente función de ejemplo llama al cmdlet Get-Command. 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 al llamar a la función Get-MyCommand. 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 característica @Args usa el parámetro automático $Args, que representa los parámetros y valores de cmdlet no declarados de los argumentos restantes.
Para obtener más información, vea about_Splatting.
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 begin, process, endy clean palabras clave. La siguiente sintaxis de ejemplo muestra estas palabras clave:
La lista de instrucciones process se ejecuta una vez para cada objeto de la canalización.
Mientras se ejecuta el bloque process, cada objeto de canalización se asigna a la variable automática $_, un objeto de canalización cada vez.
La función siguiente usa la palabra clave process. La función muestra los valores de la canalización:
function Get-Pipeline
{
process {"The value is: $_"}
}
1, 2, 4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Si desea una función que pueda tomar la entrada o entrada de canalización de un parámetro, el bloque process debe controlar ambos casos. Por ejemplo:
function Get-SumOfNumbers {
param (
[int[]]$Numbers
)
begin { $retValue = 0 }
process {
if ($null -ne $Numbers) {
foreach ($n in $Numbers) {
$retValue += $n
}
} else {
$retValue += $_
}
}
end { $retValue }
}
PS> 1, 2, 3, 4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1, 2, 3, 4
10
Cuando se usa una función en una canalización, los objetos canalizado 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 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 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, cada objeto de $input se quita de $input y se asigna a $_. En el ejemplo siguiente se incluye 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 de process. Las instrucciones process se ejecutan en cada objeto, un objeto cada vez. La variable automática $input está vacía cuando la función alcanza la palabra clave end.
1, 2, 4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Para obtener más información, consulte Using Enumerators
PowerShell 7.3 agregó el bloque clean. El bloque clean es una manera cómoda de limpiar los recursos creados y usados en los bloques begin, processy end. Es semánticamente similar a un bloque de finally que cubre todos los demás bloques con nombre de una función de script o un cmdlet de script. La limpieza de recursos se aplica para los siguientes escenarios:
- cuando la ejecución de la canalización finaliza normalmente sin errores de terminación
- cuando se interrumpe la ejecución de la canalización debido a un error de terminación
- cuando la canalización se detiene
Select-Object -First - cuando se detiene la canalización ctrl+C o
StopProcessing()
Precaución
Agregar el bloque clean es un cambio importante. Dado que clean se analiza como palabra clave, impide que los usuarios llamen directamente a un comando denominado clean como la primera instrucción de un bloque de script. Sin embargo, es probable que no sea un problema. El comando todavía se puede invocar mediante el operador de llamada (& clean).
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 { $_ }
}
Se puede usar de la siguiente manera:
Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message
Existe una función en el ámbito en el que se crea.
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 fuera de ese script.
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.
Las funciones crean un nuevo á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, vea about_Scopes.
Todas las funciones y filtros de PowerShell se almacenan automáticamente en la unidad de Function:. Esta unidad se expone mediante el proveedor de Function de PowerShell.
Al hacer referencia a la unidad de Function:, escriba dos puntos después de Función, como haría al hacer referencia a la unidad de C 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.
Al escribir una función en el símbolo del sistema de PowerShell, la función forma parte de la sesión actual. La función está disponible hasta que finaliza 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 guarde el archivo con la extensión .ps1 nombre de archivo.
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 función Get-MyDisks, escriba:
Get-Help Get-MyDisks
Puede escribir ayuda para una función mediante cualquiera de los dos métodos siguientes:
ayuda de Comment-Based para funciones
Cree un tema de ayuda con 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 de XML-Based 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-Helpno puede encontrar el tema de ayuda de la función y las llamadas aGet-Helppara la función solo devuelven ayuda generada automáticamente.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, consulte Ayuda de cómo escribir cmdlets.
- about_Automatic_Variables
- about_Comment_Based_Help
- about_Function_Provider
- 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
Comentarios de PowerShell
PowerShell es un proyecto de código abierto. Seleccione un vínculo para proporcionar comentarios: