about_Functions

Breve descrizione

Descrive come creare e usare funzioni in PowerShell.

Descrizione lunga

Una funzione è un elenco di istruzioni di PowerShell con un nome assegnato. Quando si esegue una funzione, si digita il nome della funzione. Le istruzioni nell'elenco vengono eseguite come se fossero state 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 dell'applicazione.

Analogamente ai cmdlet, le funzioni possono avere parametri. I parametri possono essere denominati, posizionali, switch o parametri dinamici. I parametri della funzione possono essere letti 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. È anche possibile specificare un valore restituito usando la return parola chiave . La return parola chiave non influisce o elimina altri output restituiti dalla funzione. Tuttavia, la return parola chiave esce dalla funzione in corrispondenza di tale riga. Per altre informazioni, vedere about_Return.

L'elenco di istruzioni della funzione può contenere diversi tipi di elenchi di istruzioni con le Beginparole chiave , Processe End. Questi elenchi di istruzioni gestiscono l'input dalla pipeline in modo diverso.

Un filtro è un tipo speciale di funzione che usa la Filter parola chiave .

Le funzioni possono anche fungere da cmdlet. È possibile creare una funzione che funziona esattamente come un cmdlet senza usare C# la programmazione. Per altre informazioni, vedere about_Functions_Advanced.

Importante

All'interno di file di script e moduli basati su script, le funzioni devono essere definite prima di poter essere chiamate.

Sintassi

Di seguito è riportata la sintassi per una funzione:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Una funzione include gli elementi seguenti:

• Parola Function chiave
• Ambito (facoltativo)
• Nome selezionato
• Qualsiasi numero di parametri denominati (facoltativo)
• Uno o più comandi di PowerShell racchiusi tra parentesi graffe {}

Per altre informazioni sulla Dynamicparam parola chiave e sui parametri dinamici nelle funzioni, vedere about_Functions_Advanced_Parameters.

Funzioni semplici

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

function <function-name> {statements}

Ad esempio, la funzione seguente avvia PowerShell con l'opzione Esegui come amministratore.

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

Per usare la funzione, digitare: Start-PSAdmin

Per aggiungere istruzioni alla funzione, digitare ogni istruzione in una riga separata oppure usare un punto ; e virgola per separare le istruzioni.

Ad esempio, la funzione seguente trova tutti i .jpg file 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-Object {$_.LastWriteTime -gt $Start}
}

È possibile creare una casella degli strumenti di funzioni di piccole dimensioni utili. Aggiungere queste funzioni al profilo di PowerShell, come descritto in about_Profiles e versioni successive in questo argomento.

Nomi di funzione

È 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 PowerShell.

I nomi delle funzioni devono essere costituiti da una coppia verbo-sostantivo in cui il verbo identifica l'azione eseguita dalla 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 PowerShell. Questi verbi consentono di mantenere i nomi dei comandi semplici, coerenti e facili da comprendere agli utenti.

Per altre informazioni sui verbi di PowerShell standard, vedere Verbi approvati nel Microsoft Docs.

Funzioni con parametri

È possibile usare parametri con funzioni, inclusi parametri denominati, parametri posizionali, parametri switch e parametri dinamici. Per altre informazioni sui parametri dinamici nelle funzioni, vedere about_Functions_Advanced_Parameters.

parametri denominati

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

È possibile definire parametri all'interno delle parentesi graffe usando la param parola chiave , come illustrato nella sintassi di esempio seguente:

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

È anche possibile definire parametri esterni alle parentesi graffe senza la Param parola chiave , come illustrato nella sintassi di esempio seguente:

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

Di seguito è riportato un esempio di questa sintassi alternativa.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

Anche se il primo metodo è preferibile, non esiste alcuna differenza tra questi due metodi.

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 tale variabile può essere usato nella funzione .

L'esempio seguente è una funzione denominata Get-SmallFiles. Questa funzione ha un $Size parametro. La funzione visualizza tutti i file più piccoli del valore del $Size parametro ed esclude le directory:

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

Nella funzione è possibile usare la $Size variabile , ovvero il nome definito per il parametro .

Per usare questa funzione, digitare il comando seguente:

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 assegna un nome al parametro Size :

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 $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Se si digita Get-SmallFiles senza un valore, la funzione assegna 100 a $size. Se si specifica un valore, la funzione usa tale valore.

Facoltativamente, è possibile fornire 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 Get-SmallFiles funzione, aggiungere l'attributo PSDefaultValue come illustrato nell'esempio seguente.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

Per altre informazioni sulla classe di attributo PSDefaultValue , vedere Membri dell'attributo PSDefaultValue.

Parametri posizionali

Un parametro posizionale è un parametro senza un nome di parametro. PowerShell usa l'ordine del valore del parametro per associare ogni valore di parametro a un parametro nella funzione .

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

La funzione seguente Get-Extension aggiunge l'estensione .txt del nome file a un nome file specificato:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Parametri switch

Un'opzione è un parametro che non richiede un valore. Si digita invece il nome della funzione seguito dal nome del parametro switch.

Per definire un parametro switch, specificare il tipo [switch] 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 On parametro switch dopo il nome della funzione, la funzione visualizza "Switch on". Senza il parametro switch, viene visualizzato "Disattiva".

Switch-Item -on

Switch on

Switch-Item

Switch off

È anche possibile assegnare un valore booleano a un'opzione quando si esegue la funzione, come illustrato nell'esempio seguente:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Uso dello splatting per rappresentare i parametri dei comandi

È 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 del comando o modificare la funzione quando i parametri di comando cambiano.

La funzione di esempio seguente chiama il Get-Command cmdlet . Il comando usa @Args per rappresentare i parametri di Get-Command.

function Get-MyCommand { Get-Command @Args }

È possibile usare tutti i parametri di Get-Command quando si chiama la Get-MyCommand funzione . I parametri e i valori dei parametri vengono passati al comando usando @Args.

Get-MyCommand -Name Get-ChildItem

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

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

Per altre informazioni sulla splatting, vedere about_Splatting.

Piping di oggetti in funzioni

Qualsiasi funzione può accettare l'input dalla pipeline. È possibile controllare come una funzione elabora l'input dalla pipeline usando Begin, Processe End parole chiave. La sintassi di esempio seguente mostra le tre parole chiave:

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

L'elenco Begin di istruzioni viene eseguito una sola volta all'inizio della funzione.

Importante

Se la funzione definisce un Beginblocco o End , Process tutto il codice deve risiedere all'interno di tali blocchi. Nessun codice verrà riconosciuto all'esterno dei blocchi se sono definiti uno dei blocchi.

L'elenco Process delle istruzioni viene eseguito una sola volta per ogni oggetto nella pipeline. Mentre il Process blocco è 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 End di istruzioni viene eseguito una sola volta. Se non Beginvengono usate parole chiave , o End , Processtutte le istruzioni vengono considerate come un End elenco di istruzioni.

La funzione seguente usa la Process parola chiave. La funzione visualizza esempi dalla pipeline:

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

Per illustrare questa funzione, immettere un elenco di numeri separati da virgole, come illustrato nell'esempio seguente:

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 inoltrati alla funzione vengono assegnati alla $input variabile automatica. La funzione esegue istruzioni con la Begin parola chiave prima che tutti gli oggetti provengono dalla pipeline. La funzione esegue istruzioni con la End parola chiave dopo che tutti gli oggetti sono stati ricevuti dalla pipeline.

Nell'esempio seguente viene illustrata la $input variabile automatica con Begin e End le parole chiave.

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

Se questa funzione viene eseguita usando la pipeline, visualizza i risultati seguenti:

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Quando l'istruzione viene eseguita, la Begin funzione non ha l'input dalla pipeline. L'istruzione End viene eseguita dopo che la funzione ha i valori.

Se la funzione ha una Process parola chiave, ogni oggetto in $input viene rimosso da $input e assegnato a $_. L'esempio seguente include un Process elenco di istruzioni:

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

In questo esempio ogni oggetto inviato alla funzione viene inviato all'elenco Process di istruzioni. Le Process istruzioni vengono eseguite in ogni oggetto, un oggetto alla volta. La $input variabile automatica è vuota quando la funzione raggiunge la End parola chiave.

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Per altre informazioni, vedere Uso di enumeratori

Filtri

Un filtro è un tipo di funzione in esecuzione su ogni oggetto nella pipeline. Un filtro è simile a una funzione con tutte le relative istruzioni in un Process blocco.

La sintassi di un filtro è la seguente:

filter [<scope:>]<name> {<statement list>}

Il filtro seguente accetta voci di log dalla pipeline e quindi visualizza l'intera voce o solo la parte del messaggio della voce:

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

Ambito funzione

Una funzione esiste nell'ambito in cui è stato creato.

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.

È possibile specificare l'ambito di una funzione. Ad esempio, la funzione viene aggiunta all'ambito globale nell'esempio seguente:

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

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

Le funzioni creano normalmente un ambito. Gli elementi creati in una funzione, ad esempio le variabili, esistono solo nell'ambito della funzione.

Per altre informazioni sull'ambito in PowerShell, vedere about_Scopes.

Ricerca e gestione di funzioni tramite la funzione: Unità

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

Quando si fa riferimento all'unità, digitare un punto dopo funzione, come si farebbe quando si fa riferimento all'unità CFunction: o D a un computer.

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

Get-ChildItem function:

I comandi nella funzione vengono archiviati come blocco di script nella proprietà di definizione della funzione. Ad esempio, per visualizzare i comandi nella funzione Della Guida fornita con PowerShell, digitare:

(Get-ChildItem function:help).Definition

È anche possibile usare la sintassi seguente.

$function:help

Per altre informazioni sull'unità, vedere l'argomento Function: della Guida per il provider di funzioni . Digitare Get-Help Function.

Riutilizzo di 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 usare la funzione in tutte le sessioni di PowerShell, aggiungere la funzione al profilo di PowerShell. Per altre informazioni sui profili, vedere about_Profiles.

È anche possibile salvare la funzione in un file di script di PowerShell. Digitare la funzione in un file di testo e quindi salvare il file con l'estensione del .ps1 nome file.

Scrittura della Guida per funzioni

Il Get-Help cmdlet ottiene assistenza per le funzioni, nonché per cmdlet, provider e script. Per ottenere assistenza per una funzione, digitare Get-Help seguito dal nome della funzione.

Ad esempio, per ottenere assistenza per la Get-MyDisks funzione, digitare:

Get-Help Get-MyDisks

È possibile scrivere una guida per una funzione usando uno dei due metodi seguenti:

• Guida Comment-Based per le funzioni

  Create un argomento della Guida usando parole chiave speciali nei commenti. Per creare una Guida basata su commenti per una funzione, i commenti devono essere posizionati all'inizio o alla fine del corpo della funzione o sulle righe che precedono la parola chiave della funzione. Per altre informazioni sulla Guida basata sui commenti, vedere about_Comment_Based_Help.

• Guida XML-Based per le funzioni

  Create un argomento della Guida basato su XML, ad esempio il tipo in genere creato per i cmdlet. La Guida basata su XML è necessaria se si stanno localizzati gli argomenti della Guida in più lingue.

  Per associare la funzione all'argomento della Guida basata su XML, usare la .ExternalHelp parola chiave della Guida basata su commenti. Senza questa parola chiave, Get-Help non è possibile trovare l'argomento della Guida della funzione e le chiamate a Get-Help per la funzione restituiscono solo la Guida generata automaticamente.

  Per altre informazioni sulla ExternalHelp parola chiave, vedere about_Comment_Based_Help. Per altre informazioni sulla Guida basata su XML, vedere How to Write Cmdlet Help (Procedura per la scrittura del cmdlet).

Vedi anche

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• 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