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)