• 2/27/2019
  • 12 minuti a leggere

Breve descrizione

viene Descritto come creare e utilizzare le funzioni in PowerShell.

Descrizione lunga

Una funzione è un elenco di istruzioni PowerShell con un nome che tuassign. Quando si esegue una funzione, si digita il nome della funzione. Le dichiarazioni nell’elenco vengono eseguite come se le avessi digitate al prompt dei comandi.,

Le funzioni possono essere semplici come: 

function Get-PowerShellProcess { Get-Process PowerShell }

Una funzione può anche essere complessa come un cmdlet o un programma applicativo.

Come i cmdlet, le funzioni possono avere parametri. I parametri possono essere denominati, posizionali, switch o parametri dinamici. I parametri della funzione possono essere leggutidalla 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. È inoltre possibile specificare un valore di ritorno utilizzando la parola chiavereturn., La parola chiave return non influisce o sopprime otheroutput restituito dalla funzione. Tuttavia, la parola chiave return esce dalla funzione in quella riga. Per ulteriori informazioni, vedere about_Return.

L’elenco delle istruzioni della funzione può contenere diversi tipi di elenchi di istruzioni con le parole chiaveBegin,ProcesseEnd. Queste istruzioni listshandle input dalla pipeline in modo diverso.

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

Le funzioni possono anche agire come cmdlet. È possibile creare una funzione che funzionasolo come un cmdlet senza utilizzare la programmazione C#. Per ulteriori informazioni, vedere about_Functions_Advanced.,

la Sintassi

La seguente è la sintassi per la funzione:

Una funzione comprende i seguenti elementi:

  • Un Function chiave
  • Un ambito (facoltativo)
  • Un nome che si seleziona
  • numero di parametri per nome (opzionale)
  • Uno o più comandi di PowerShell racchiuso tra parentesi graffe {}

Per ulteriori informazioni sui Dynamicparam parola chiave e parametri dinamici infunctions, seeabout_Functions_Advanced_Parameters.,

Funzioni semplici

Le funzioni non devono essere complicate per essere utili. Le funzioni più sempliciavere il seguente formato:

function <function-name> {statements}

Ad esempio, la seguente funzione avvia PowerShell con l’opzione Esegui asAdministrator.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Per utilizzare la funzione, digitare:Start-PSAdmin

Per aggiungere istruzioni alla funzione, digitare ciascuna istruzione su una riga separata, oppure utilizzare un punto e virgola; per separare le istruzioni.,

Ad esempio, la seguente funzione trova tutti i file .jpg nelle directory dell’utente corrente che sono stati modificati dopo la data di inizio.

È possibile creare una cassetta degli strumenti di piccole funzioni utili. Aggiungi queste funzioni al tuo profilo PowerShell, come descritto in about_Profiles e più avanti in questo argomento.

Nomi di funzioni

È possibile assegnare qualsiasi nome a una funzione, ma le funzioni condivise con altre devono seguire le regole di denominazione stabilite per tutti i comandi PowerShell.,

I nomi delle funzioni devono essere costituiti da una coppia verbo-nome in cui il verbo identifica l’azione eseguita dalla funzione e il nome identifica l’oggetto su cui il cmdlet esegue la sua azione.le funzioni

devono utilizzare i verbi standard approvati per i comandi allPowerShell. Questi verbi ci aiutano a mantenere i nostri nomi di comandosemplice, coerente e facile da capire per gli utenti.

Per ulteriori informazioni sui verbi PowerShell standard, vedere Verbi approvati nei documenti Microsoft.,

Funzioni con parametri

È possibile utilizzare parametri con funzioni, inclusi parametri denominati, parametri posizionali, parametri di commutazione e parametri dinamici. Per ulteriori informazioni sui parametri dinamici nelle funzioni, vedere about_functions_advanced_parameters.

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 all’interno di parentesi graffe utilizzando il Param parola chiave, come illustrato nell’esempio seguente sintassi:

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

È inoltre possibile definire i parametri al di fuori di parentesi graffe senza il Param parola chiave,come illustrato nell’esempio seguente sintassi:

function <name> $parameter1$parameter2])] { <statement list>}

di Seguito è un esempio di questa sintassi alternativa.

Function Add-Numbers($one, $two) { $one + $two}

Mentre il primo metodo è preferito, non c’è differenza tra questi duemetodi.,

Quando si esegue la funzione, il valore fornito per un parametro viene assegnato auna variabile che contiene il nome del parametro. Il valore di quella variabile può essereusato nella funzione.

Il seguente esempio è una funzione chiamata Get-SmallFiles. Questa funzioneha un$Size parametro., La funzione visualizza tutti i file che sono più piccoli del valore del parametro $Size ed esclude le directory:

function Get-SmallFiles { Param($Size) Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

Nella funzione, è possibile utilizzare la variabile $Size, che è il nome definito peril parametro.

Per utilizzare questa funzione, digitare il seguente comando: 

Get-SmallFiles -Size 50

È anche possibile immettere un valore per un parametro denominato senza il nome del parametro.,Per esempio, il seguente comando dà lo stesso risultato di un comando thatnames il parametro Dimensioni:

Get-SmallFiles 50

Per impostare un valore predefinito per il parametro, digitare un segno di uguale e il valueafter il nome del parametro, come mostrato nella seguente variazione diGet-SmallFiles esempio:

function Get-SmallFiles ($Size = 100) { Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

Se si digita Get-SmallFiles senza un valore, la funzione assegna 100$size. Se si fornisce un valore, la funzione utilizza tale valore.,

Facoltativamente, è possibile fornire una breve stringa di aiuto 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 di aiuto che descrive il valore predefinito (100) del parametro Size nella funzione Get-SmallFiles, aggiungere l’attributo Psdefaultvalue come mostrato nell’esempio seguente.

function Get-SmallFiles { param ( $Size = 100 )}

Per ulteriori informazioni sulla classe di attributo PSDefaultValue, i membri dell’attributo psdefaultvalue.,

Parametri posizionali

Un parametro posizionale è un parametro senza un nome di parametro. PowerShell utilizza l’ordine del valore del parametro per associare ciascun valore del parametro a un parametro nella funzione.

Quando si utilizzano i parametri posizionali, digitare uno o più valori dopo il nome funzione. I valori dei parametri posizionali vengono assegnati alla variabile array$args.Il valore che segue il nome della funzione viene assegnato alla prima posizione nell’array $args, $args.,

Il seguente Get-Extension funzione aggiunge il .txt l’estensione del nome file afile nome di alimentazione:

function Get-Extension { $name = $args + ".txt" $name}
Get-Extension myTextFile
myTextFile.txt

Interruttore Parametri

Un interruttore è un parametro che non necessitano di un valore. Invece, si digita il nome della funzione seguito dal nome del parametro switch.,

Per definire un parametro di opzione, specificare il tipo prima parametername, come mostrato nel seguente esempio:

function Switch-Item { param ($on) if ($on) { "Switch on" } else { "Switch off" }}

Quando si digita il On passare il parametro dopo il nome della funzione, il functiondisplays “Switch on”. Senza il parametro switch, viene visualizzato “Switch off”.,

Switch-Item -on
Switch on
Switch-Item
Switch off

È anche possibile assegnare un valore Booleano ad un interruttore quando si esegue la funzione, come riportato nel seguente esempio:

Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off

Utilizzo di Splatting per Rappresentare i Parametri di Comando

È possibile utilizzare splatting per rappresentare i parametri di un comando. Questa caratteristica è introdotta in Windows PowerShell 3.0.

Utilizzare questa tecnica in funzioni che chiamano comandi nella sessione., Non è necessario dichiarare o enumerare i parametri del comando o modificare la funzionequando i parametri del comando cambiano.

La seguente funzione di esempio chiama il cmdletGet-Command. Il comando utilizza @Argsper rappresentare i parametri di Get-Command.

function Get-MyCommand { Get-Command @Args }

È possibile utilizzare tutti i parametri diGet-Commandquando si chiama la funzioneGet-MyCommand. I parametri e i valori dei parametri vengono passati al comando utilizzando @Args.,

Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName----------- ---- ----------Cmdlet Get-ChildItem Microsoft.PowerShell.Management

La funzionalità@Argsutilizza il parametro automatico$Args, che rappresenta i parametri e i valori del cmdlet non dichiarati dagli argomenti rimanenti.

Per ulteriori informazioni sullo splatting, vedere about_Splatting.

Piping Oggetti alle funzioni

Qualsiasi funzione può prendere input dalla pipeline. È possibile controllare come una funzioneprocessa l’input dalla pipeline utilizzando le parole chiave Begin, Process e End., La seguente sintassi di esempio mostra le tre parole chiave:

function <name> { begin {<statement list>} process {<statement list>} end {<statement list>}}

L’elenco delle istruzioni Begin viene eseguito una sola volta, all’inizio della funzione.

Importante

Se la funzione definisce un blocco Begin, Processo End, tutto il codice deve risiedere all’interno di tali blocchi. Nessun codice verrà riconosciuto al di fuori dei bloccise uno qualsiasi dei blocchi è definito.

L’elenco di istruzioni Process viene eseguito una volta per ogni oggetto nella pipeline.,Mentre il bloccoProcess è in esecuzione, ogni oggetto pipeline viene assegnato alla variabile automatica$_, un oggetto pipeline alla volta.

Dopo che la funzione riceve tutti gli oggetti nella pipeline, l’elenco delle istruzioniEndviene eseguito una volta. Se non vengono utilizzate parole chiave Begin, Process o End, tutte le istruzioni vengono trattate come un elenco di istruzioni End.

La seguente funzione utilizza la parola chiave Process., La funzione displaysexamples dalla pipeline:

function Get-Pipeline{ process {"The value is: $_"}}

Per dimostrare questa funzione, è necessario immettere un elenco di numeri separati da virgole, come riportato nel seguente esempio:

1,2,4 | Get-Pipeline
The value is: 1The value is: 2The value is: 4

Quando si utilizza una funzione in una pipeline, gli oggetti di sottofondo per la funzione areassigned per il $input variabile automatica. La funzione esegue le istruzioni con la parola chiaveBegin prima che qualsiasi oggetto provenga dalla pipeline., La funzione esegue dichiarazioni con la parola chiave End dopo che tutti gli oggetti sono stati ricevuti dalla pipeline.

L’esempio seguente mostra la variabile automatica $input con le parole chiave Begin eEnd.

function Get-PipelineBeginEnd{ begin {"Begin: The input is $input"} end {"End: The input is $input" }}

Se questa funzione viene eseguita utilizzando la pipeline, visualizza il followingresults:

1,2,4 | Get-PipelineBeginEnd
Begin: The input isEnd: The input is 1 2 4

Quando Begin istruzione viene eseguita, la funzione non ha l’ingresso da thepipeline., L’istruzioneEnd viene eseguita dopo che la funzione ha i valori.

Se la funzione ha una parola chiave Process, ogni oggetto in $input viene rimosso da $input e assegnato a $_. Nell’esempio seguente è presente un elenco di istruzioniProcess: 

function Get-PipelineInput{ process {"Processing: $_ " } end {"End: The input is: $input" }}

In questo esempio, ogni oggetto inviato alla funzione viene inviato all’elenco di istruzioniProcess. Le istruzioni Process vengono eseguite su ciascun oggetto, un oggetto alla volta., La variabile automatica$input è vuota quando la funzioneraggiunge la parola chiaveEnd.

1,2,4 | Get-PipelineInput
Processing: 1Processing: 2Processing: 4End: The input is:

Per ulteriori informazioni, vedere Utilizzo degli enumeratori

Filtri

Un filtro è un tipo di funzione che viene eseguita su ciascun oggetto nella pipeline. Afilter assomiglia a una funzione con tutte le sue istruzioni in un blocco Process.,

La sintassi di un filtro è come indicato di seguito:

filter <name> {<statement list>}

Il seguente filtro prende voci di registro dalla pipeline e quindi displayseither la voce intera o solo la parte di messaggio di voce:

filter Get-ErrorLog ($message){ if ($message) { Out-Host -InputObject $_.Message } else { $_ }}

Ambito della Funzione

Una funzione che esiste nell’ambito in cui è stato creato.

Se una funzione fa parte di uno script, la funzione è disponibile per statementswithin tale script. Per impostazione predefinita, una funzione in uno script non è disponibile al prompt dei comandi.

È possibile specificare l’ambito di una funzione., Ad esempio, la funzione viene aggiunta al’ambito globale nel seguente esempio:

function global:Get-DependentSvs { Get-Service | Where-Object {$_.DependentServices}}

Quando una funzione si trova nell’ambito globale,è possibile utilizzare la funzione negli script, nelle funzioni e nella riga di comando.le funzioni

normalmente creano un ambito. Gli elementi creati in una funzione, ad esempiovariabili, esistono solo nell’ambito della funzione.

Per ulteriori informazioni sull’ambito in PowerShell, vedere About_scopes.,

Ricerca e gestione delle funzioni Utilizzando la funzione: Drive

Tutte le funzioni e i filtri di PowerShell vengono memorizzati automaticamente nell’unitàFunction:. Questa unità è esposta dal provider PowerShellFunction.

Quando si fa riferimento all’unitàFunction:, digitare i due punti dopo la funzione, proprio come si farebbe quando si fa riferimento all’unitàC oD di un computer.,

Il seguente comando visualizza tutte le funzioni nella sessione corrente di PowerShell:

Get-ChildItem function:

I comandi nella funzione sono memorizzati come un blocco di script nella proprietà di definizione della funzione. Ad esempio, per visualizzare i comandi nella Helpfunction fornita con PowerShell, digitare:

(Get-ChildItem function:help).Definition

È anche possibile utilizzare la seguente sintassi.

$function:help

Per ulteriori informazioni sull’unitàFunction:, consultare l’argomento della guida per il provider di funzioni. Digitare Get-Help Function.,

Riutilizzo delle funzioni nelle nuove sessioni

Quando si digita una funzione al prompt dei comandi di PowerShell, la funzione diventa parte della sessione corrente. È disponibile fino alla fine della sessione.

Per utilizzare la funzione in tutte le sessioni di PowerShell, aggiungere la funzione al proprio profilo PowerShell. Per ulteriori informazioni sui profili, vedere about_Profiles.

È anche possibile salvare la funzione in un file di script PowerShell. Digitare yourfunction in un file di testo, quindi salvare il file con il.ps1 file nameextension.,

Scrivere la guida per le funzioni

Il cmdletGet-Help ottiene la guida per le funzioni, così come per i cmdlet,i provider e gli script. Per ottenere aiuto per una funzione, digitare Get-Help seguitodal nome della funzione.

Per esempio, per ottenere aiuto per il Get-MyDisks funzione, tipo:

Get-Help Get-MyDisks

È possibile scrivere la guida per una funzione utilizzando uno dei due followingmethods:

  • Commento di Base di Aiuto per le Funzioni

    Creare un argomento della guida utilizzando parole chiave speciali nei commenti., Per creare la guida basata su comment per una funzione, i commenti devono essere posizionati all’inizio o alla fine del corpo della funzione o sulle righe che precedono la functionkeyword. Per ulteriori informazioni sulla guida basata sui commenti, vedere about_comment_based_help.

  • Guida basata su XML per le funzioni

    Crea un argomento della guida basato su XML, ad esempio il tipo che viene in genere 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 basato su XML, utilizzare la parola chiave.ExternalHelp aiuto basato su commenti., Senza questa parola chiave,Get-Helpnon riesce a trovare l’argomento della guida della funzione e chiama aGet-Help per la funzione solo la guida generata automaticamente.

    Per ulteriori informazioni sulla parola chiave ExternalHelp, vedere about_comment_based_help. Per ulteriori informazioni sulla guida basata su XML, vederecome scrivere la guida del Cmdlet.

Vedere anche

about_Automatic_Variables