Condividi tramite

informazioni_sulle_Funzioni

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'applicazione.

Come i 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 parola chiave return. La parola chiave return non influisce o elimina altri output restituiti dalla funzione. Tuttavia, la parola chiave return 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 parole chiave begin, process, ende clean. Queste istruzioni elencano l'handle di input dalla pipeline in modo diverso.

La parola chiave filtro viene usata per creare un tipo di funzione in esecuzione su ogni oggetto nella pipeline. Un filtro è simile a una funzione con tutte le relative istruzioni in un blocco process.

Le funzioni possono anche agire come cmdlet. È possibile creare una funzione che funziona esattamente come un cmdlet senza usare C# 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>}
  clean {<statement list>}
}

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

Una funzione include gli elementi seguenti:

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

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

Metodi di elaborazione dell'input

I metodi descritti in questa sezione sono detti metodi di elaborazione dell'input. Per le funzioni, questi tre metodi sono rappresentati dai blocchi begin, processe end della funzione. PowerShell 7.3 aggiunge un clean metodo di processo a blocchi.

Non è necessario usare uno di questi blocchi nelle funzioni. Se non si usa un blocco denominato, PowerShell inserisce il codice nel blocco end della funzione. Tuttavia, se si usa uno di questi blocchi denominati o si definisce un blocco dynamicparam, è necessario inserire tutto il codice in un blocco denominato.

Nell'esempio seguente viene illustrata la struttura di una funzione che contiene un blocco di begin per la pre-elaborazione monouso, un blocco process per l'elaborazione di più record e un blocco di end per la post-elaborazione una tantum.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

begin

Questo blocco viene usato per fornire la pre-elaborazione occasionale facoltativa per la funzione. Il runtime di PowerShell usa il codice in questo blocco una volta per ogni istanza della funzione nella pipeline.

process

Questo blocco viene usato per fornire l'elaborazione record per record per la funzione. È possibile usare un blocco process senza definire gli altri blocchi. Il numero di esecuzioni di blocchi di process dipende dalla modalità di utilizzo della funzione e dall'input ricevuto dalla funzione.

La variabile automatica $_ o $PSItem contiene l'oggetto corrente nella pipeline da usare nel blocco process. La variabile automatica $input contiene un enumeratore disponibile solo per le funzioni e i blocchi di script. Per altre informazioni, vedere about_Automatic_Variables.

  • La chiamata alla funzione all'inizio o all'esterno di una pipeline esegue il blocco process una volta.
  • All'interno di una pipeline, il blocco process viene eseguito una volta per ogni oggetto di input che raggiunge la funzione.
  • Se l'input della pipeline che raggiunge la funzione è vuoto, il blocco di processnon eseguito.
    • I blocchi begin, ende clean vengono ancora eseguiti.

Importante

Se un parametro di funzione è impostato per accettare l'input della pipeline e un blocco di process non è definito, l'elaborazione dei record per record avrà esito negativo. In questo caso, la funzione verrà eseguita una sola volta, indipendentemente dall'input.

end

Questo blocco viene usato per fornire una sola volta post-elaborazione facoltativa per la funzione.

clean

Il clean blocco è stato aggiunto in PowerShell 7.3.

Il clean blocco è un modo pratico per consentire agli utenti di pulire le risorse che si estendono tra i beginblocchi , processe end . È semanticamente simile a un finally blocco che copre tutti gli altri blocchi denominati di una funzione script o un cmdlet di script. La pulizia delle risorse viene applicata per gli scenari seguenti:

  1. quando l'esecuzione della pipeline viene completata normalmente senza errori irreversibili
  2. quando l'esecuzione della pipeline viene interrotta a causa di un errore irreversibile
  3. quando la pipeline viene interrotta da Select-Object -First
  4. quando la pipeline viene arrestata da ctrl+c o StopProcessing()

Attenzione

L'aggiunta del clean blocco è una modifica che causa un'interruzione. Poiché clean viene analizzato come parola chiave, impedisce agli utenti di chiamare direttamente un comando denominato clean come prima istruzione in un blocco di script. Tuttavia, non è probabile che si tratti di un problema. Il comando può comunque essere richiamato usando l'operatore di chiamata (& clean).

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 o usare un punto e virgola ; per separare le istruzioni.

Ad esempio, la funzione seguente trova 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-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 coerenti e facili da comprendere agli utenti.

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

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 i parametri all'interno delle 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 parametri esterni alle parentesi graffe senza la parola chiave Param, 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 contenente 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 parametro $Size. La funzione visualizza tutti i file inferiori al 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 usare la variabile $Size, 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 denomina il 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 di 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 specificare una breve stringa della Guida che descrive il valore predefinito del parametro aggiungendo l'attributo PSDefaultValue alla descrizione del parametro e specificando la proprietà della Guida 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 di attributi PSDefaultValue , vedere PSDefaultValue Attribute Members.

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 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 del nome file .txt 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. Digitare 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 parametro switch On dopo il nome della funzione, la funzione visualizza 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 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 cmdlet Get-Command. 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 funzione Get-MyCommand. 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 funzionalità @Args usa il parametro automatico $Args, che rappresenta i parametri e i valori dei cmdlet non dichiarati dagli argomenti rimanenti.

Per ulteriori informazioni, vedere about_Splatting.

Piping di oggetti in funzioni

Qualsiasi funzione può accettare input dalla pipeline. È possibile controllare il modo in cui una funzione elabora l'input dalla pipeline usando beginparole chiave , processend, e clean . La sintassi di esempio seguente illustra queste parole chiave:

L'elenco di istruzioni process viene eseguito una sola volta per ogni oggetto nella pipeline. Mentre il blocco process è in esecuzione, ogni oggetto pipeline viene assegnato alla variabile automatica $_, un oggetto pipeline alla volta.

La funzione seguente usa la parola chiave process. La funzione visualizza i valori della pipeline:

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

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Se si vuole una funzione che può accettare l'input o l'input della pipeline da un parametro, il blocco process deve gestire entrambi i casi. Per esempio:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

Quando si usa una funzione in una pipeline, gli oggetti inviati tramite pipe alla funzione vengono assegnati alla variabile automatica $input. La funzione esegue istruzioni con la parola chiave begin prima che tutti gli oggetti provengano dalla pipeline. La funzione esegue 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 parole chiave begin e 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:

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 ha l'input dalla pipeline. L'istruzione end 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 $_. L'esempio seguente include 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 su ogni oggetto, un oggetto alla volta. La variabile automatica $input è vuota quando la funzione raggiunge la parola chiave end.

1,2,4 | Get-PipelineInput

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

Per altre informazioni, vedere Using Enumerators

PowerShell 7.3 ha aggiunto il clean blocco. Il clean blocco è un modo pratico per consentire agli utenti di pulire le risorse create e usate nei beginblocchi , processe end . È semanticamente simile a un finally blocco che copre tutti gli altri blocchi denominati di una funzione script o un cmdlet di script. La pulizia delle risorse viene applicata per gli scenari seguenti:

  1. quando l'esecuzione della pipeline viene completata normalmente senza errori irreversibili
  2. quando l'esecuzione della pipeline viene interrotta a causa di un errore irreversibile
  3. quando la pipeline viene interrotta da Select-Object -First
  4. quando la pipeline viene arrestata da ctrl+C o StopProcessing()

Attenzione

L'aggiunta del clean blocco è una modifica che causa un'interruzione. Poiché clean viene analizzato come parola chiave, impedisce agli utenti di chiamare direttamente un comando denominato clean come prima istruzione in un blocco di script. Tuttavia, non è probabile che si tratti di un problema. Il comando può comunque essere richiamato usando l'operatore di chiamata (& clean).

Filtri

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

La sintassi di un filtro è la seguente:

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

Il filtro seguente accetta le 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 { $_ }
}

Può essere usato come segue:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Ambito funzione

Esiste una funzione nell'ambito in cui viene 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 all'esterno di tale script.

È 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 un nuovo ambito. Gli elementi creati in una funzione, ad esempio le variabili, esistono solo nell'ambito della funzione.

Per altre informazioni, 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 di funzioni di PowerShell .

Quando si fa riferimento all'unità Function:, digitare due punti dopo Funzione, come si farebbe quando si fa riferimento all'unità C o D di 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 della Guida relativo al provider di funzione . 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. La funzione è disponibile fino al termine 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 nome file .ps1.

Scrittura della Guida per funzioni

Il cmdlet Get-Help ottiene la Guida 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 funzione Get-MyDisks, digitare:

Get-Help Get-MyDisks

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

  • Guida di Comment-Based per funzioni

    Creare un argomento della Guida usando parole chiave speciali nei commenti. Per creare una Guida basata su commenti per una funzione, è necessario inserire i commenti 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 su commenti, vedere about_Comment_Based_Help.

  • Guida di XML-Based per funzioni

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

    Per associare la funzione all'argomento della Guida basata su XML, utilizzare la parola chiave della Guida basata su commenti .EXTERNALHELP. 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 parola chiave .EXTERNALHELP, vedere about_Comment_Based_Help. Per ulteriori informazioni sulla Guida basata su XML, vedere Come scrivere la Guida per Cmdlet.

Vedere anche

  • Last updated on