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) 





Argomenti della Guida