PowerShell
Funciones de PowerShell

Introducción

Función simple sin parámetros

Este es un ejemplo de una función que devuelve una cadena. En el ejemplo, la función se llama en una declaración asignando un valor a una variable. El valor en este caso es el valor de retorno de la función.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function declara que el siguiente código es una función.

Get-Greeting es el nombre de la función. En cualquier momento en que esa función deba utilizarse en el script, se puede llamar a la función invocándola por su nombre.

{ ... } es el bloque de script que ejecuta la función.

Si el código anterior se ejecuta en el ISE, los resultados serían algo así como:

Hello World
Hello World

Parametros basicos

Una función se puede definir con parámetros usando el bloque param:

function Write-Greeting {
    param(
        [Parameter(Mandatory,Position=0)]
        [String]$name,
        [Parameter(Mandatory,Position=1)]
        [Int]$age
    )
    "Hello $name, you are $age years old."
}

O usando la sintaxis de la función simple:

function Write-Greeting ($name, $age) {
    "Hello $name, you are $age years old."
}

Nota: los parámetros de conversión no son necesarios en ninguno de los tipos de definición de parámetros.

La sintaxis de función simple (SFS) tiene capacidades muy limitadas en comparación con el bloque param.
Aunque puede definir los parámetros que se expondrán dentro de la función, no puede especificar atributos de parámetros , utilizar la validación de parámetros , incluir [CmdletBinding()] , con SFS (y esta es una lista no exhaustiva).

Las funciones pueden ser invocadas con parámetros ordenados o nombrados.

El orden de los parámetros en la invocación coincide con el orden de la declaración en el encabezado de la función (por defecto), o se puede especificar usando el atributo de parámetro de Position (como se muestra en el ejemplo de la función avanzada, más arriba).

$greeting = Write-Greeting "Jim" 82

Alternativamente, esta función puede ser invocada con parámetros nombrados.

$greeting = Write-Greeting -name "Bob" -age 82

Parámetros obligatorios

Los parámetros de una función se pueden marcar como obligatorios.

function Get-Greeting{
    param
    (
        [Parameter(Mandatory=$true)]$name
    )
    "Hello World $name"
}

Si la función se invoca sin un valor, la línea de comando solicitará el valor:

$greeting = Get-Greeting 

cmdlet Get-Greeting at command pipeline position 1
Supply values for the following parameters:
name: 

Función avanzada

Esta es una copia del fragmento de función avanzada del ISE de Powershell. Básicamente, esta es una plantilla para muchas de las cosas que puede usar con funciones avanzadas en Powershell. Puntos clave a tener en cuenta:

• Integración get-help: el principio de la función contiene un bloque de comentarios que está configurado para ser leído por el cmdlet get-help. El bloque de funciones se puede ubicar al final, si se desea.
• cmdletbinding - la función se comportará como un cmdlet
• parámetros
• conjuntos de parámetros

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   General notes
.COMPONENT
   The component this cmdlet belongs to
.ROLE
   The role this cmdlet belongs to
.FUNCTIONALITY
   The functionality that best describes this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # Param2 help description
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # Param3 help description
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

Validación de parámetros

Hay varias formas de validar la entrada de parámetros, en PowerShell.

En lugar de escribir código dentro de funciones o scripts para validar los valores de los parámetros, estos atributos de parámetro se lanzarán si se pasan valores no válidos.

ValidateSet

A veces necesitamos restringir los valores posibles que un parámetro puede aceptar. Digamos que queremos permitir solo rojo, verde y azul para el parámetro $Color en un script o función.

Podemos usar el atributo de parámetro ValidateSet para restringir esto. Tiene la ventaja adicional de permitir que se complete la pestaña al configurar este argumento (en algunos entornos).

param(
    [ValidateSet('red','green','blue',IgnoreCase)]
    [string]$Color
)

También puede especificar IgnoreCase para desactivar la sensibilidad a las mayúsculas.

Validar Rango

Este método de validación de parámetros toma un valor Int32 mínimo y máximo, y requiere que el parámetro esté dentro de ese rango.

param(
    [ValidateRange(0,120)]
    [Int]$Age
)

ValidatePattern

Este método de validación de parámetros acepta parámetros que coinciden con el patrón de expresiones regulares especificado.

param(
    [ValidatePattern("\w{4-6}\d{2}")]
    [string]$UserName
)

ValidateLength

Este método de validación de parámetros prueba la longitud de la cadena pasada.

param(
    [ValidateLength(0,15)]
    [String]$PhoneNumber
)

ValidateCount

Este método de validación de parámetros prueba la cantidad de argumentos pasados, por ejemplo, una matriz de cadenas.

param(
    [ValidateCount(1,5)]
    [String[]]$ComputerName
)

ValidateScript

Finalmente, el método ValidateScript es extraordinariamente flexible, tomando un bloque de script y evaluándolo usando $ _ para representar el argumento pasado. Luego pasa el argumento si el resultado es $ verdadero (incluyendo cualquier resultado como válido).

Esto puede ser usado para probar que un archivo existe:

param(
    [ValidateScript({Test-Path $_})]
    [IO.FileInfo]$Path 
)

Para comprobar que un usuario existe en AD:

param(
    [ValidateScript({Get-ADUser $_})]
    [String]$UserName
)

Y casi cualquier otra cosa que puedas escribir (ya que no está restringida a oneliners):

param(
    [ValidateScript({
        $AnHourAgo = (Get-Date).AddHours(-1)
        if ($_ -lt $AnHourAgo.AddMinutes(5) -and $_ -gt $AnHourAgo.AddMinutes(-5)) {
            $true
        } else {
            throw "That's not within five minutes. Try again."
        }
    })]
    [String]$TimeAboutAnHourAgo
)