ARGOMENTO

about_Functions

DESCRIZIONE BREVE
Descrive come creare e utilizzare le funzioni in Windows PowerShell.

DESCRIZIONE DETTAGLIATA
Per funzione si intende un elenco di istruzioni a cui è stato
assegnato un nome. Quando si esegue una funzione, se ne digita il
nome. Le istruzioni incluse nell'elenco vengono eseguite come se
fossero state digitate al prompt dei comandi.

Analogamente ai cmdlet, le funzioni possono disporre di

parametri. I parametri possono essere denominati, posizionali,
opzionali o dinamici. I parametri delle funzioni possono essere
letti dalla riga di comando o dalla pipeline.

Le funzioni possono restituire valori che è possibile

visualizzare, assegnare a variabili o passare ad altre funzioni o
cmdlet.

L'elenco di istruzioni delle funzioni può contenere tipi diversi

di elenchi di istruzioni con le parole chiave Begin, Process ed
End. Questi elenchi di istruzioni gestiscono l'input da pipeline
in modo diverso.

Un filtro è un tipo speciale di funzione che utilizza la parola

chiave Filter.

Le funzioni possono anche essere utilizzate come cmdlet. È

possibile creare una funzione utilizzabile come cmdlet senza
utilizzare la programmazione C#. Per ulteriori informazioni, vedere
about_Functions_Advanced.

Sintassi
Di seguito è riportata la sintassi di una funzione:

function [<ambito:>]<nome> [([type]$parameter1[,[type]$parameter2])]

{
param([type]$parameter1 [,[type]$parameter2])

dynamicparam {<elenco istruzioni>}

begin {<elenco istruzioni>}

process {<elenco istruzioni>}
end {<elenco istruzioni>}
}

Una funzione include gli elementi seguenti:

- Una parola chiave Function

- Un ambito (facoltativo)
- Un nome selezionato dall'utente
- Un numero qualsiasi di parametri denominati (facoltativo)
- Uno o più comandi di Windows PowerShell racchiusi tra
parentesi graffe ({})
 Per ulteriori informazioni sulla parola chiave Dynamicparam e
sui parametri dinamici nelle funzioni, vedere
about_Functions_Advanced_Parameters.

Funzioni semplici
L'utilità di una funzione non dipende dalla sua complessità. La
funzione seguente ottiene le variabili di ambiente che non
appartengono all'account System del sistema corrente:

function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<Sistema>"}
}

Per eseguire la funzione, digitare "other_env".

È possibile creare una casella degli strumenti di brevi

funzioni utili. Aggiungere queste funzioni al proprio profilo
di Windows PowerShell, come illustrato in about_Profiles e più
avanti in questo argomento.

Funzioni con parametri

Le funzioni possono essere utilizzate con parametri, inclusi
quelli denominati, posizionali, opzionali e dinamici. Per ulteriori
informazioni sui parametri dinamici nelle funzioni, vedere
about_Functions_Advanced_Parameters.

Parametri denominati
È possibile definire un numero qualsiasi di parametri
denominati, nonché includere un valore predefinito per i
parametri denominati, come illustrato più avanti in questo
argomento.

È possibile definire parametri all'interno di parentesi graffe

utilizzando la parola chiave Param, come illustrato nella
sintassi di esempio seguente:

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

È inoltre possibile definire parametri all'esterno di parentesi

graffe senza utilizzare la parola chiave Param, come illustrato
nella sintassi di esempio seguente:

function <nome> [([type]$parameter1[,[type]$parameter2])] {

<elenco istruzioni>
}

Non esiste alcuna differenza tra questi due metodi, utilizzare

 quello preferito.

Quando si esegue la funzione, il valore fornito per un

parametro viene assegnato a una variabile che contiene il nome
del parametro. Il valore di quella variabile può essere
utilizzato nella funzione.

Di seguito è riportato l'esempio di una funzione denominata

Small_files. Questa funzione, che dispone di un parametro
$size, visualizza tutti i file le cui dimensioni sono inferiori
al valore del parametro $size ed esclude le directory:

function small_files {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}

Nella funzione è possibile utilizzare la variabile $size,

ovvero il nome definito per il parametro.

Per utilizzare questa funzione, digitare il comando seguente:

C:\PS> function small_files -size 50

È inoltre possibile immettere un valore per un parametro

denominato senza il nome del parametro. Ad esempio, il comando
seguente fornisce lo stesso risultato di un comando che assegna
un nome al parametro Size:

C:\PS> function small_files 50

Per definire un valore predefinito per un parametro, digitare

un segno di uguale e il valore dopo il nome del parametro, come
illustrato nella variazione dell'esempio Small_files riportata
di seguito:

function small_files ($size = 100) {

Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}

Se si digita "small_files" senza un valore, la funzione assegna

100 a $Size. Se si fornisce un valore, la funzione lo utilizza.

Parametri posizionali
Per parametro posizionale si intende un parametro senza un
nome. In Windows PowerShell viene utilizzato l'ordine dei
valori dei parametri per associare ogni valore a un parametro
della funzione.

Quando si utilizzano i parametri posizionali, digitare uno o

più valori dopo il nome della funzione. I valori dei parametri
posizionali vengono assegnati alla variabile di tipo matrice
 $arg. Il valore che segue il nome della funzione viene
assegnato alla prima posizione nella matrice $args, $args[0].

La funzione Extension seguente aggiunge l'estensione di file

txt a un nome file fornito:

function extension {
$name = $args[0] + ".txt"
$name
}

C:\PS> extension myTextFile

myTextFile.txt

Le funzioni possono accettare più di un parametro posizionale.

Nell'esempio seguente vengono visualizzati i valori immessi con
il nome della funzione.

function repeat { foreach ($arg in $args) { "L'input è $arg" } }

C:\PS>repeat one
L'input è one

C:\PS> repeat one two three

L'input è one
L'input è two
L'input è three

Questa funzione può essere utilizzata con qualsiasi numero di

valori. La funzione assegna ogni valore a una posizione nella
matrice $args.

Parametri opzionali
Un'opzione è un parametro che non richiede un valore. Pertanto,
digitare il nome della funzione seguito dal nome del parametro
opzionale.

Per definire un parametro opzionale, specificare il tipo

[opzione] prima del nome del parametro, come illustrato
nell'esempio seguente:

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

Quando si digita il parametro opzionale On dopo il nome della

funzione, la funzione visualizza "Switch On". Senza il
parametro opzionale, visualizza "Switch off".

C:\PS> SwitchExample -on

Switch on

C:\PS> SwitchExample
Switch off
 È inoltre possibile assegnare un valore booleano a un'opzione
quando si esegue la funzione, come illustrato nell'esempio seguente:

C:\PS> SwitchExample -on:$true

Switch on

C:\PS> SwitchExample -on:$false

Switch off

Reindirizzamento di oggetti alle funzioni

Qualsiasi funzione può accettare l'input da pipeline. È
possibile controllare il modo in cui una funzione elabora
l'input da pipeline utilizzando le parole chiave Begin, Process
ed End. Nella sintassi di esempio seguente vengono illustrate
le tre parole chiave:

function <nome> {
begin {<elenco istruzioni>}
process {<elenco istruzioni>}
end {<elenco istruzioni>}
}

L'elenco di istruzioni Begin viene eseguito una sola volta

all'inizio della funzione.

L'elenco di istruzioni Process viene eseguito una volta per

ogni oggetto nella pipeline.
Mentre è in corso l'esecuzione del blocco Process, ogni oggetto
della pipeline viene assegnato alla variabile automatica $_, un
oggetto alla volta.

Dopo che la funzione ha ricevuto tutti gli oggetti nella

pipeline, l'elenco di istruzioni End viene eseguito una volta.
Se non si utilizza la parola chiave Begin, Process o End, tutte
le istruzioni vengono considerate come un elenco di istruzioni End.

La funzione seguente utilizza la parola chiave Process. La

funzione visualizza esempi dalla pipeline:

function pipelineFunction
{
process {"Il valore è: $_"}
}

Per dimostrare l'utilizzo di questa funzione, immettere una

matrice di numeri creata con virgole, come illustrato
nell'esempio seguente:

C:\PS> 1,2,4 | pipelineFunction

Il valore è: 1
Il valore è: 2
Il valore è: 4

Quando si utilizza una funzione in una pipeline, gli oggetti

reindirizzati alla funzione vengono assegnati alla variabile
 automatica $input. La funzione esegue le istruzioni con la
parola chiave Begin prima che qualsiasi oggetto venga ricevuto
dalla pipeline. La funzione esegue le istruzioni con la parola
chiave End dopo che tutti gli oggetti sono stati ricevuti dalla
pipeline.

Nell'esempio seguente viene illustrata la variabile automatica

$input con le parole chiave Begin ed End.

function PipelineBeginEnd
{
begin {"Begin: L'input è $input"}
end {"End: L'input è $input" }
}

Se questa funzione viene eseguita utilizzando la pipeline,

ottiene i risultati seguenti:

C:\PS> 1,2,4 | PipelineBeginEnd

Begin: L'input è
End: L'input è 1 2 4

Quando viene eseguita l'istruzione Begin, la funzione non

ottiene l'input da pipeline. L'istruzione End viene eseguita
dopo che la funzione ottiene dei valori.

Se la funzione dispone di una parola chiave Process, la

funzione legge i dati in $input. Nell'esempio seguente viene
illustrato un elenco di istruzioni Process:

function PipelineInput
{
process {"Elaborazione: $_ " }
end {"End: L'input è: $input" }
}

In questo esempio ogni oggetto reindirizzato alla funzione

viene inviato all'elenco di istruzioni Process. Le istruzioni
Process vengono eseguite su ogni oggetto, un oggetto alla
volta. Quando la funzione raggiunge la parola chiave End, la
variabile automatica $input è vuota.

C:\PS> 1,2,4 | PipelineInput

Elaborazione: 1
Elaborazione: 2
Elaborazione: 4
End: L'input è:

Filtri
Per filtro si intende un tipo di funzione che viene eseguito su
ogni oggetto nella pipeline. Con tutte le istruzioni incluse in
un blocco Process, un filtro è simile a una funzione.

Di seguito è illustrata la sintassi di un filtro:

filter [<ambito:>]<nome> {<elenco istruzioni>}

 Il filtro seguente accetta voci di registro dalla pipeline,
quindi visualizza l'intera voce o solo la parte del messaggio
relativa:

filter ErrorLog ([switch]$message)

{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}

Ambito della funzione

Una funzione esiste nell'ambito in cui è stata creata.

Se una funzione fa parte di uno script, è disponibile per le

istruzioni all'interno di tale script. Per impostazione
predefinita, una funzione inclusa in uno script non è
disponibile al prompt dei comandi.

È possibile specificare l'ambito di una funzione. Nell'esempio

seguente, la funzione viene aggiunta all'ambito globale:

function global:get-dependentsvs { get-service |

where {$_.dependentservices} }

Quando una funzione si trova nell'ambito globale, è possibile

utilizzare la funzione negli script, nelle funzioni e alla riga
di comando.

Le funzioni creano in genere un ambito. Gli elementi creati in

una funzione, ad esempio le variabili, esistono solo
nell'ambito della funzione.

Per ulteriori informazioni sull'ambito in Windows PowerShell, vedere

about_Scope.

Individuazione e gestione di funzioni mediante l'unità Function:

Tutte le funzioni e i filtri di Windows PowerShell vengono
automaticamente archiviati nell'unità Function:. Questa unità è
esposta dal provider Function di Windows PowerShell.

Quando si fa riferimento all'unità Function:, digitare il

carattere due punti dopo Function, proprio come se si trattasse
dell'unità C o D di un computer.

Il comando seguente visualizza tutte le funzioni nella sessione

corrente di Windows PowerShell:

C:\PS> dir function:

I comandi della funzione vengono archiviati come blocco di

script nella proprietà Definition della funzione. Ad esempio,
per visualizzare i comandi della funzione Help fornita con
Windows PowerShell, digitare:
 (dir function:help).definition

Per ulteriori informazioni sull'unità Function:, vedere Function.

Riutilizzo di funzioni in nuove sessioni

Quando si digita una funzione al prompt dei comandi di Windows
PowerShell, la funzione diventa parte della sessione corrente e
rimane disponibile fino al termine della sessione.

Per utilizzare la funzione in tutte le sessioni di Windows

PowerShell, aggiungerla al profilo di Windows PowerShell. Per
ulteriori informazioni sui profili, vedere about_Profiles.

È inoltre possibile salvare la funzione in un file di script di

Windows PowerShell. Digitare la funzione in un file di testo,
quindi salvare il file con l'estensione ps1.

Scrittura della Guida relativa alle funzioni

Il cmdlet Get-Help ottiene la Guida relativa a funzioni, cmdlet,
provider e script. Per ottenere la Guida per una funzione,
digitare Get-Help seguito dal nome della funzione.

Ad esempio, per ottenere la Guida relativa alla funzione MyDisks,

digitare:

get-help MyDisks

È possibile scrivere la Guida per una funzione mediante uno dei

due metodi seguenti:

-- Guida basata su commenti relativa alle funzioni

Creare un argomento della Guida mediante parole chiave

speciali nei commenti. Per creare una Guida basata su
commenti relativa a una funzione, è necessario posizionare i
commenti all'inizio o alla fine del corpo della funzione
oppure sulle righe che precedono la parola chiave della
funzione. Per ulteriori informazioni sulla Guida basata su
commenti, vedere about_Comment_Based_Help.

-- Guida basata su XML relativa alle funzioni

Creare un argomento della Guida basato su XML, ad esempio il

tipo di guida che viene in genere creato per i cmdlet. Creare
una Guida basata su XML quando si preveda di localizzarla in
più lingue.

Per associare la funzione all'argomento della Guida basato su XML,

utilizzare la parola chiave di commento della Guida .ExternalHelp.
Per ulteriori informazioni sulla parola chiave ExternalHelp, vedere
about_Comment_Based_Help. Per ulteriori informazioni sulla Guida
basata su XML, vedere l'argomento relativo alla scrittura della Guida
relativa ai cmdlet in MSDN.
VEDERE ANCHE
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (provider)