Acerca de Funciones

• 2/27/2019
• 12 minutos para leer
• • S
  • s

Breve descripción

se Describe cómo crear y utilizar las funciones de PowerShell.

Descripción larga

una función es una lista de instrucciones de PowerShell que tiene un nombre que usted asigna. Cuando se ejecuta una función, se escribe el nombre de la función. Los estados en la lista se ejecutan como si los hubiera escrito 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 pueden ser nombrados,posicionales, conmutadores o parámetros dinámicos. Los parámetros de la función se pueden leer desde la línea de comandos o desde la canalización.las funciones

pueden devolver valores que pueden mostrarse, asignarse a variables o pasarse a otras funciones o cmdlets. También puede especificar un valor devuelto usando la palabra clave return., La palabra clave return no afecta ni suprime otros resultados devueltos por su función. Sin embargo, la palabra clave return sale de thefunction en esa línea. Para obtener más información, consulte about_Return.

la lista de instrucciones de la función puede contener diferentes tipos de listas de instrucciones con las palabras clave Begin, Process, y End. Estas instrucciones listshandle 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 como un cmdlet sin usar la programación C#. Para obtener más información,consulte about_Functions_Advanced.,

sintaxis

la siguiente es la sintaxis de una función:

una función incluye los siguientes elementos:

• a Function palabra clave
• un ámbito (opcional)
• un nombre que seleccione
• Cualquier número de parámetros con nombre (opcional)
• Uno o más comandos de PowerShell {}

para obtener más información sobre la palabra clave Dynamicparam y las infunciones de parámetros dinámicos, consulte about_functions_advanced_parameters.,

funciones simples

Las funciones no tienen que ser complicadas para ser útiles. Las funciones más simples 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 Encuentra todos los archivos .jpg en los directorios del usuario actual que se cambiaron después de la fecha de inicio.

Puede crear una caja de herramientas de pequeñas funciones útiles. Agregue estas funciones a su perfil de PowerShell, como se describe en about_Profiles y más adelante en este tema.

nombres de funciones

puede asignar cualquier nombre a una función, pero las funciones que comparta con otras deben seguir las reglas de nomenclatura establecidas para los comandos allPowerShell.,

Los nombres de funciones deben consistir en 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 que han sido aprobados para los comandos allPowerShell. Estos verbos nos ayudan a mantener nuestro nombre de comando simple, consistente y fácil de entender para los usuarios.

para obtener más información acerca de los verbos estándar de PowerShell, consulte verbos aprobados en los documentos de Microsoft.,

funciones con parámetros

puede usar parámetros con funciones, incluidos parámetros con nombre, parámetros de posición, parámetros de conmutación y parámetros dinámicos. Para obtener más información sobre parámetros dinámicos en funciones, consulteabout_functions_advanced_parameters.

Parámetros con Nombre

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

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

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

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

function <name> $parameter1$parameter2])] { <statement list>}

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

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

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

Cuando ejecuta la función, el valor que proporciona 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 siguiente ejemplo es una función llamada 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 utilizar esta función, escriba el siguiente comando:

Get-SmallFiles -Size 50

también puede introducir un valor para un parámetro con nombre sin el nombre del parámetro.,Por ejemplo, el siguiente comando da el mismo resultado que un comando que nombra el parámetro de tamaño:

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 delGet-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 utiliza ese valor.,

opcionalmente, puede proporcionar una breve cadena de ayuda que describa el valor predeterminado de su parámetro, agregando el atributo PSDefaultValue a la descripción de su parámetro y especificando la propiedad de ayuda ofPSDefaultValue. 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 siguiente ejemplo.

function Get-SmallFiles { param ( $Size = 100 )}

para obtener más información sobre la clase de atributo PSDefaultValue, consulte miembros de atributo psdefaultvalue.,

parámetros posicionales

un parámetro posicional es un parámetro sin un nombre de parámetro. PowerShell utiliza el orden del valor de parámetro para asociar cada valor de parámetro con un parámetro de la función.

Cuando utilice parámetros posicionales, escriba uno o más valores después de functionname. Los valores de los parámetros posicionales se asignan a la variable array $args.El valor que sigue al nombre de la función se asigna a la primera posición en el $args array, $args.,

El siguiente Get-Extension función añade la etiqueta .txt extensión de nombre de archivo para afile nombre de la oferta:

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

Get-Extension myTextFile

myTextFile.txt

Conmutador de Parámetros

Un interruptor es un parámetro que no se 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 antes del parametername, como se muestra en el siguiente ejemplo:

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

Cuando escriba el parámetro On switch 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 Booleano a un interruptor cuando se ejecuta la función, asshown en el siguiente ejemplo:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

el Uso de Splatting para Representar los Parámetros de Comando

puede utilizar splatting para representar los parámetros de un comando. Esta característica se introdujo en Windows PowerShell 3.0.

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

la siguiente función de ejemplo llama al cmdlet Get-Command. Usa el comando@Args para representar los parámetros de Get-Command.

function Get-MyCommand { Get-Command @Args }

Usted puede utilizar todos los parámetros de Get-Command cuando usted llame a la etiquetaGet-MyCommand función. Los parámetros y los valores de los parámetros se pasan a thecommand usando @Args.,

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 y valores del cmdlet declarado de los argumentos restantes.

para obtener más información sobre las salpicaduras, consulte about_Splatting.

canalizar objetos a funciones

cualquier función puede tomar entrada de la canalización. Puede controlar cómo una función procesa la entrada de la canalización utilizando las palabras clave Begin, Process y End., La siguiente sintaxis muestra las tres palabras clave:

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

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 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 a la vez.

después de que la función recibe todos los objetos en la canalización, la lista de instrucciones Endse ejecuta una vez. Si no Begin, Process o End keywordsare usada, de todas las declaraciones que son tratados como un End declaración de la lista.

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

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

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

1,2,4 | Get-Pipeline

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

Cuando usa una función en una canalización, los objetos canalizado a la función areassigned a la variable automática $input. La función ejecuta sentencias con la palabra clave Begin antes de que cualquier objeto provenga de la canalización., La función ejecuta statements con la palabra clave End después de que todos los objetos se hayan recibido de la canalización.

el siguiente ejemplo muestra la variable automática $input con las palabras clave Begin yEnd.

function Get-PipelineBeginEnd{ begin {"Begin: The input is $input"} end {"End: The input is $input" }}

Si esta función se ejecuta mediante el uso de la tubería, se muestra el followingresults:

1,2,4 | Get-PipelineBeginEnd

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

el Begin instrucción se ejecuta, la función no tiene la entrada de thepipeline., 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 en $input se elimina de $input y se asigna a $_. El siguiente ejemplo tiene un Processdeclaración de la lista:

function Get-PipelineInput{ process {"Processing: $_ " } end {"End: The input is: $input" }}

En este ejemplo, cada objeto que se transfiere a la función es enviada aProcess declaración de la lista. Las instrucciones Process se ejecutan en cada objeto, un objeto a la vez., La variable automática $input está vacía cuando la función alcanza la palabra clave End.

1,2,4 | Get-PipelineInput

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

para obtener más información, consulte Uso de enumeradores

filtros

un filtro es un tipo de función que se ejecuta en cada objeto de la canalización. Afilter se asemeja a una función con todas sus sentencias en un bloque Process.,

la sintaxis de un filtro es la siguiente:

filter <name> {<statement list>}

el siguiente filtro toma entradas de registro de la canalización y luego muestra toda la entrada o solo la porción de mensaje de la entrada:

filter Get-ErrorLog ($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 es parte de un script, la función está disponible para los estados dentro de ese script. Por defecto, una función en un script no está disponible en el prompt comando.

Puede especificar el alcance de una función., Por ejemplo, la función se agrega al ámbito global en el siguiente ejemplo:

function global:Get-DependentSvs { Get-Service | Where-Object {$_.DependentServices}}

Cuando una función está en el ámbito global,puede usarla en scripts, en funciones y en la línea de comandos.

Las funciones normalmente 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, consulteabout_scopes.,

buscar y administrar funciones mediante la unidad Function:

todas las funciones y filtros de PowerShell se almacenan automáticamente en la unidad Function:. Esta unidad es expuesta por el proveedor PowerShellFunction.

al hacer referencia a la unidad Function:, escriba dos puntos después de la función, como haría al hacer referencia a la unidad 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 en la función de ayuda que viene con PowerShell, escriba:

(Get-ChildItem function:help).Definition

También puede usar la siguiente sintaxis.

$function:help

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

reutilización de funciones en sesiones nuevas

cuando se escribe una función en el símbolo del sistema de PowerShell, la función se convierte en 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 a su perfil de PowerShell. Para obtener más información acerca de los perfiles,consulte about_Profiles.

También puede guardar la función en un archivo de script de PowerShell. Escriba su función en un archivo de texto y luego guarde el archivo con la extensión .ps1 file nameextension.,

escribir Ayuda para funciones

el cmdletGet-Help obtiene ayuda para funciones, así como para cmdlets,proveedores y scripts. Para obtener ayuda para una función, escriba Get-Help seguido por el 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 utilizando cualquiera de los dos métodos siguientes:

• ayuda basada en comentarios para funciones

  observaciones., Para crear ayuda basada en comment para una función, los comentarios deben colocarse al principio o al final del cuerpo de la función o en las líneas que preceden a functionkeyword. 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 normalmente se crea para 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, utilice 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 llama a Get-Help para la función devolver solo la ayuda generada automáticamente.

  para obtener más información sobre la palabra clave ExternalHelp, consulte about_comment_based_help. Para obtener más información sobre la ayuda basada en XML, consulte cómo escribir la ayuda de Cmdlet.

Véase también

about_Automatic_Variables