about_Functions
Aggiornamento: maggio 2014
Si applica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
ARGOMENTO
about_Functions
DESCRIZIONE BREVE
Descrive come creare e usare le funzioni in Windows PowerShell®.
DESCRIZIONE LUNGA
Una funzione è un elenco di istruzioni di Windows PowerShell con un nome assegnato dall'utente. Quando si esegue una funzione, è necessario digitarne il nome. Le istruzioni nell'elenco vengono eseguite come se venissero digitate al prompt dei comandi.
Le funzioni possono essere semplici, ad esempio:
function Get-PowerShellProcess {Get-Process PowerShell}
o complesse come un cmdlet o un'applicazione.
Anche le funzioni, come i cmdlet, possono avere dei parametri. I parametri possono essere denominati, posizionali, opzionali o dinamici. I parametri della funzione possono essere leggi dalla riga di comando o dalla pipeline.
Le funzioni possono restituire valori che possono essere visualizzati, assegnati a variabili o passati ad altre funzioni o cmdlet.
Questo elenco di istruzioni della funzione può contenere diversi tipi di elenchi di istruzioni con le parole chiave Begin, Process ed End. Questi elenchi di istruzioni gestiscono l'input dalla pipeline in modo diverso.
Un filtro è un tipo speciale di funzione che usa la parola chiave Filter.
Le funzioni possono anche essere usate come cmdlet. È possibile creare una funzione da usare come cmdlet senza la programmazione C#. Per altre informazioni, vedere about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511).
Sintassi
Di seguito è illustrata la sintassi per una funzione:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Una funzione include i seguenti elementi:
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
Per altre informazioni sulla parola chiave Dynamicparam e sui parametri dinamici nelle funzioni, vedere about_Functions_Advanced_Parameters.
Funzioni semplici
Per essere utile, una funzione non deve essere necessariamente complessa. Le funzioni più semplici hanno il formato seguente:
function <function-name> {statements}
Ad esempio, la funzione seguente avvia Windows PowerShell con l'opzione Esegui come amministratore.
function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}
Per usare la funzione, digitare: Start-PSAdmin
Per aggiungere le istruzioni alla funzione, usare un punto e virgola (;) per separare le istruzioni oppure digitare ogni istruzione su una riga separata.
Ad esempio, la funzione seguente consente di trovare tutti i file JPG nelle directory dell'utente corrente modificate dopo la data di inizio.
function Get-NewPix
{
$start = Get-Date -Month 1 -Day 1 -Year 2010
$allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
$allpix | where {$_.LastWriteTime -gt $Start}
}
È possibile creare una casella degli strumenti contenente alcune funzioni semplici e utili. Aggiungere queste funzioni al profilo di Windows PowerShell, come descritto in about_Profiles e più avanti in questo argomento.
Nomi delle funzioni
È possibile assegnare qualsiasi nome a una funzione, ma le funzioni condivise con altri utenti devono seguire le regole di denominazione stabilite per tutti i comandi di Windows PowerShell.
I nomi delle i funzioni devono essere costituiti da una coppia verbo-sostantivo in cui il verbo identifica l'azione che esegue la funzione e il sostantivo identifica l'elemento in cui il cmdlet esegue l'azione.
Le funzioni devono usare i verbi standard approvati per tutti i comandi di Windows PowerShell. Questi verbi consentono di mantenere i nomi dei comandi semplici, coerenti e facili da comprendere.
Per altre informazioni sui verbi standard di Windows PowerShell, vedere "Verbi dei cmdlet" su MSDN all'indirizzo https://go.microsoft.com/fwlink/?LinkID=160773.
FUNZIONI CON PARAMETRI
Le funzioni possono essere usate con i parametri, inclusi i parametri denominati, posizionali, opzionali e dinamici. Per altre informazioni sui parametri dinamici nelle funzioni, vedere about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).
Parametri denominati
È possibile definire un numero qualsiasi di parametri denominati. È possibile includere un valore predefinito per i parametri denominati, come descritto più avanti in questo argomento.
È possibile definire i parametri tra parentesi graffe usando la parola chiave Param, come illustrato nella sintassi di esempio seguente:
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
È anche possibile definire i parametri fuori dalle parentesi graffe senza la parola chiave Param, come illustrato nella sintassi di esempio seguente:
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
Non esiste alcuna differenza tra questi due metodi. Usare il metodo 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 della variabile può essere usato nella funzione.
L'esempio seguente è una funzione denominata Get-SmallFiles. Questa funzione ha un parametro $size. La funzione visualizza tutti i file con dimensioni inferiori rispetto al valore del parametro $size ed esclude le directory:
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Nella funzione è possibile usare la variabile $size, ovvero il nome definito per il parametro.
Per usare la funzione, digitare il comando seguente:
C:\PS> function Get-SmallFiles –Size 50
È anche possibile immettere un valore per un parametro denominato senza il nome del parametro. Ad esempio, il comando seguente restituisce lo stesso risultato di un comando che denomina il parametro Size:
C:\PS> function Get-SmallFiles 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 variante seguente dell'esempio Get-SmallFiles:
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Se si digita "Get-SmallFiles" senza un valore, la funzione assegna 100 a $size. Se si fornisce un valore, la funzione usa il valore specificato.
È possibile fornire, facoltativamente, una breve stringa della Guida che descrive il valore predefinito del parametro, aggiungendo l'attributo PSDefaultValue alla descrizione del parametro e specificando la proprietà Help di PSDefaultValue. Per fornire una stringa della Guida che descrive il valore predefinito (100) del parametro Size nella funzione Get-SmallFiles, aggiungere l'attributo PSDefaultValue come illustrato nell'esempio seguente.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
Per altre informazioni sulla classe PSDefaultValueAttribute, vedere l'articolo relativo ai membri di PSDefaultValueAttribute in MSDN. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx
Parametri posizionali
Un parametro posizionale è un parametro senza un nome di parametro. Windows PowerShell usa l'ordine del valore del parametro per associare ogni valore del parametro a un parametro nella funzione.
Quando si usano i parametri posizionali, digitare uno o più valori dopo il nome della funzione. I valori del parametro posizionale vengono assegnati alla variabile di matrice $args. Il valore che segue il nome della funzione viene assegnato alla prima posizione nella matrice $args, $args [0].
La funzione Get-Extension seguente aggiunge l'estensione di file TXT a un nome file fornito dall'utente:
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
PARAMETRI OPZIONALI
Un'opzione è un parametro che non richiede un valore. Viene invece digitato il nome della funzione seguito dal nome del parametro opzionale.
Per definire un parametro opzionale, specificare il tipo [opzionale] prima del nome del parametro, come illustrato nell'esempio seguente:
function Switch-Item {
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 viene visualizzato "Switch off".
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
È anche possibile assegnare un valore booleano a un'opzione quando si esegue la funzione, come illustrato nell'esempio seguente:
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
Uso dello splatting per rappresentare i parametri Command
È possibile usare lo splatting per rappresentare i parametri di un comando. Questa funzionalità è stata introdotta in Windows PowerShell 3.0.
Usare questa tecnica nelle funzioni che chiamano i comandi nella sessione. Non è necessario dichiarare o enumerare i parametri Command o modificare la funzione quando si modificano tali parametri.
La funzione di esempio seguente chiama il cmdlet Get-Command. Il comando usa @Args per rappresentare i parametri di Get-Command.
function Get-MyCommand { Get-Command @Args }
Quando si chiama la funzione Get-Command, è possibile usare tutti i parametri Get-Command. I parametri e i valori dei parametri vengono passati al comando tramite @Args.
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
La funzionalità @Args usa il parametro $Args automatico, che rappresenta i parametri del cmdlet non dichiarati e i valori degli argomenti rimanenti.
Per altre informazioni sullo splatting, vedere about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720).
Invio di oggetti alle funzioni tramite pipe
Qualsiasi funzione può acquisire l'input dalla pipeline. È possibile controllare in che modo la funzione elabora l'input dalla pipeline usando le parole chiave Begin, Process ed End. La sintassi di esempio seguente illustra tre parole chiave:
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
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. Durante l'esecuzione del blocco Process, ogni oggetto pipeline viene assegnato alla variabile automatica $_, un oggetto pipeline alla volta.
Dopo che la funzione ha ricevuto tutti gli oggetti nella pipeline, l'elenco di istruzioni End viene eseguito una volta. Se vengono usate le parole chiave Begin, Process o End, tutte le istruzioni vengono considerate come un elenco di istruzioni End.
L'esempio seguente usa la parola chiave Process. La funzione visualizza gli esempi dalla pipeline:
function Get-Pipeline
{
process {"The value is: $_"}
}
Per esaminare questa funzione, immettere un elenco di numeri separati da virgole, come illustrato nell'esempio seguente:
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Quando si usa una funzione in una pipeline, gli oggetti inviati alla funzione tramite pipe vengono assegnati alla variabile automatica $input. La funzione esegue le istruzioni con la parola chiave Begin prima di qualsiasi altro oggetto proveniente dalla pipeline. La funzione esegue le istruzioni con la parola chiave End dopo aver ricevuto tutti gli oggetti dalla pipeline.
L'esempio seguente illustra la variabile automatica $input con le parole chiave Begin ed End.
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
Se questa funzione viene eseguita usando la pipeline, vengono visualizzati i risultati seguenti:
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Quando viene eseguita l'istruzione Begin, la funzione non riceve l'input dalla pipeline. L'istruzione End viene eseguita dopo che la funzione acquisisce i valori.
Se la funzione ha una parola chiave Process, la funzione legge i dati in $input. L'esempio seguente contiene un elenco di istruzioni Process:
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
In questo esempio ogni oggetto inviato tramite pipe alla funzione viene inviato all'elenco di istruzioni Process. Le istruzioni Process vengono eseguite in ogni oggetto, un oggetto alla volta. La variabile automatica $input è vuota quando la funzione raggiunge la parola chiave End.
C:\PS> 1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Filtri
Un filtro è un tipo di funzione eseguito su ogni oggetto nella pipeline. Un filtro è simile a una funzione con tutte le istruzioni in un blocco Process.
La sintassi di un filtro è la seguente:
filter [<scope:>]<name> {<statement list>}
Il filtro seguente accetta voci di log dalla pipeline, quindi visualizza la voce intera o solo la parte del messaggio della voce:
filter Get-ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Ambito della funzione
Una funzione esiste all'interno dell'ambito in cui è stata creata.
Se una funzione fa parte di uno script, la funzione è disponibile per le istruzioni all'interno di tale script. Per impostazione predefinita, una funzione in uno script non è disponibile al prompt dei comandi.
L'ambito di una funzione può essere specificato. Ad esempio, la funzione viene aggiunta all'ambito globale nell'esempio seguente:
function global:Get-DependentSvs { Get-Service |
where {$_.DependentServices} }
Quando una funzione si trova nell'ambito globale, è possibile usarla negli script, nelle funzioni e nella riga di comando.
In genere le funzioni creano un ambito. Gli elementi creati in una funzione, ad esempio le variabili, esistono solo nell'ambito della funzione.
Per altre informazioni sull'ambito in Windows PowerShell, vedere about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260).
Ricerca e gestione delle funzioni usando l'unità Function:
Tutte le funzioni e filtri in Windows PowerShell vengono archiviati automaticamente nell'unità Function:, che viene esposta dal provider Function di Windows PowerShell.
Quando si fa riferimento all'unità Function:, digitare i due punti dopo Function, come si farebbe nel caso delle unità C e D di un computer.
Il comando seguente visualizza tutte le funzioni nella sessione corrente di Windows PowerShell:
Get-ChildItem function:
I comandi nella funzione vengono archiviati come un blocco di script nella proprietà Definition della funzione. Ad esempio, per visualizzare i comandi nella funzione Help fornita con Windows PowerShell, digitare:
(Get-ChildItem function:help).Definition
Per altre informazioni sull'unità Function:, vedere l'argomento della Guida per il provider Function. Digitare "Get-Help Function" o visualizzarlo nella libreria di TechNet all'indirizzo https://go.microsoft.com/fwlink/?LinkID=113436.
Riutilizzo delle funzioni in nuove sessioni
Quando si digita una funzione al prompt dei comandi di Windows PowerShell, la funzione diventa parte della sessione corrente. Resta disponibile finché non termina la sessione.
Per usare la funzione in tutte le sessioni di Windows PowerShell, aggiungerla al profilo di Windows PowerShell. Per altre informazioni sui profili, vedere about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729).
È anche possibile salvare la funzione in un file di script di Windows PowerShell. Digitare la funzione in un file di testo, quindi salvarlo con l'estensione di file PS1.
Guida alla scrittura per le funzioni
Il cmdlet Get-Help visualizza le informazioni della Guida per funzioni, cmdlet, provider e script. Per visualizzare la Guida per una funzione, digitare Get-Help seguito dal nome della funzione.
Ad esempio, per visualizzare la Guida per la funzione Get-MyDisks, digitare:
Get-Help Get-MyDisks
È possibile scrivere la Guida per una funzione usando uno dei metodi seguenti:
Guida per le funzioni basata su commenti
Creare un argomento della Guida usando parole chiave speciali nei commenti. Per creare una Guida per una funzione basata su commenti, i commenti devono essere inseriti all'inizio o alla fine del corpo della funzione o nelle righe che precedono la parola chiave della funzione. Per altre informazioni sulla Guida basata su commenti, vedere about_Comment_Based_Help.
Guida per le funzioni basata su XML
Creare un argomento della Guida basata su XML, ad esempio il tipo che in genere viene creato per i cmdlet. La Guida basata su XML è necessaria se si localizzano gli argomenti della Guida in più lingue.
Per associare la funzione all'argomento della Guida basata su XML, usare la parola chiave della Guida basata su commenti ExternalHelp. Senza questa parola chiave, Get-Help non riesce a trovare l'argomento della Guida relativa alle funzioni e le chiamate a Get-Help per la funzione restituiscono solo una Guida generata automaticamente.
Per altre informazioni sulla parola chiave ExternalHelp, vedere about_Comment_Based_Help. Per altre informazioni sulla Guida basata su XML, vedere "Come scrivere una Guida del cmdlet" in MSDN.
VEDERE ANCHE
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Funzione (provider)