PowerShell
Funzioni di PowerShell

introduzione

Funzione semplice senza parametri

Questo è un esempio di una funzione che restituisce una stringa. Nell'esempio, la funzione viene chiamata in un'istruzione che assegna un valore a una variabile. Il valore in questo caso è il valore di ritorno della funzione.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function dichiara che il seguente codice è una funzione.

Get-Greeting è il nome della funzione. Ogni volta che la funzione deve essere utilizzata nello script, la funzione può essere richiamata invocandola per nome.

{ ... } è il blocco di script che viene eseguito dalla funzione.

Se il codice sopra è eseguito nell'ISE, i risultati sarebbero qualcosa di simile:

Hello World
Hello World

Parametri di base

Una funzione può essere definita con parametri usando il blocco 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 sintassi della funzione semplice:

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

Nota: i parametri di trasmissione non sono richiesti in entrambi i tipi di definizione dei parametri.

La sintassi della funzione semplice (SFS) ha funzionalità molto limitate rispetto al blocco param.
Sebbene sia possibile definire i parametri da esporre all'interno della funzione, non è possibile specificare Attributi parametro , utilizzare Parameter Validation , includere [CmdletBinding()] , con SFS (e questo è un elenco non esaustivo).

Le funzioni possono essere richiamate con parametri ordinati o con nome.

L'ordine dei parametri sull'invocazione corrisponde all'ordine della dichiarazione nell'intestazione della funzione (per impostazione predefinita) oppure può essere specificato utilizzando l'Attributo parametro Position (come mostrato nell'esempio di funzione avanzato, sopra).

$greeting = Write-Greeting "Jim" 82

In alternativa, questa funzione può essere invocata con parametri denominati

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

Parametri obbligatori

I parametri di una funzione possono essere contrassegnati come obbligatori

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

Se la funzione viene invocata senza un valore, la riga di comando chiederà il valore:

$greeting = Get-Greeting 

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

Funzione avanzata

Questa è una copia dello snippet di funzione avanzato del Powershell ISE. Fondamentalmente questo è un modello per molte delle cose che puoi usare con le funzioni avanzate in PowerShell. Punti chiave da notare:

• integrazione get-help - l'inizio della funzione contiene un blocco di commenti che viene impostato per essere letto dal cmdlet get-help. Il blocco funzione può essere posizionato alla fine, se lo si desidera.
• cmdletbinding - la funzione si comporterà come un cmdlet
• parametri
• set di parametri

<#
.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
    {
    }
}

Validazione dei parametri

Esistono diversi modi per convalidare l'immissione dei parametri, in PowerShell.

Invece di scrivere codice all'interno di funzioni o script per convalidare i valori dei parametri, questi ParameterAttributes generano se vengono passati valori non validi.

ValidateSet

A volte è necessario limitare i possibili valori che un parametro può accettare. Diciamo che vogliamo consentire solo il rosso, il verde e il blu per il parametro $Color in uno script o una funzione.

Possiamo usare l'attributo del parametro ValidateSet per limitare questo. Ha l'ulteriore vantaggio di consentire il completamento della tabulazione quando si imposta questo argomento (in alcuni ambienti).

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

È inoltre possibile specificare IgnoreCase per disabilitare la distinzione tra maiuscole e minuscole.

ValidateRange

Questo metodo di validazione dei parametri richiede un valore Int32 minimo e massimo e richiede che il parametro sia compreso in tale intervallo.

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

ValidatePattern

Questo metodo di validazione dei parametri accetta parametri che corrispondono al modello regex specificato.

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

ValidateLength

Questo metodo di validazione dei parametri verifica la lunghezza della stringa passata.

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

ValidateCount

Questo metodo di validazione dei parametri verifica la quantità di argomenti passati, ad esempio, una serie di stringhe.

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

ValidateScript

Infine, il metodo ValidateScript è straordinariamente flessibile, prende un blocco di script e lo valuta usando $ _ per rappresentare l'argomento passato. Passa quindi l'argomento se il risultato è $ true (incluso qualsiasi output valido).

Questo può essere usato per verificare che esista un file:

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

Per verificare che un utente esista in AD:

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

E praticamente qualsiasi altra cosa tu possa scrivere (dato che non si limita ai oneliner):

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
)