Condividi tramite

about_Functions_Advanced_Methods

Breve descrizione

Descrive in che modo le funzioni che specificano l'attributo CmdletBinding possono usare i metodi e le proprietà disponibili per i cmdlet compilati.

Descrizione lunga

Le funzioni che specificano l'attributo CmdletBinding possono accedere a metodi e proprietà aggiuntivi tramite la variabile $PSCmdlet. Questi metodi includono i metodi seguenti:

  • Gli stessi metodi di elaborazione di input disponibili per tutte le funzioni.
  • I metodi ShouldProcess e ShouldContinue usati per ottenere commenti e suggerimenti degli utenti prima dell'esecuzione di un'azione.
  • Metodo ThrowTerminatingError per la generazione di record di errore.
  • Diversi metodi Write che restituiscono tipi diversi di output.

Tutti i metodi e le proprietà della classe PSCmdlet sono disponibili per le funzioni avanzate. Per altre informazioni, vedere System.Management.Automation.PSCmdlet.

Per altre informazioni sull'attributo CmdletBinding, vedere about_Functions_CmdletBindingAttribute. Per la classe CmdletBindingAttribute, vedere System.Management.Automation.Cmdlet.CmdletBindingAttribute.

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 metodo di processo a blocchi clean.

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{}
    clean{}
}

Nota

Questi blocchi si applicano a tutte le funzioni, non solo alle funzioni che usano l'attributo CmdletBinding.

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 $input variabile automatica contiene un enumeratore disponibile solo per le funzioni e gli scriptblock. 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.

Quando si crea una funzione che accetta l'input della pipeline e usa CmdletBinding, il blocco process deve usare la variabile di parametro definita per l'input della pipeline anziché $_ o $PSItem. Per esempio:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

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

end

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

clean

Il blocco clean è stato aggiunto in PowerShell 7.3.

Il blocco clean è un modo pratico per consentire agli utenti di pulire le risorse che si estendono tra i blocchi begin, processe end. È semanticamente simile a un blocco finally 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()

Il blocco pulito rimuove qualsiasi output scritto nel flusso Operazione riuscita.

Cautela

L'aggiunta del blocco clean è 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 uno scriptblock. Tuttavia, non è probabile che si tratti di un problema. Il comando può comunque essere richiamato usando l'operatore di chiamata (& clean).

Metodi di conferma

ShouldProcess

Questo metodo viene chiamato per richiedere conferma all'utente prima che la funzione esegua un'azione che modifica il sistema. La funzione può continuare in base al valore booleano restituito dal metodo . Questo metodo può essere chiamato solo dall'interno del blocco process {} della funzione. L'attributo CmdletBinding deve anche dichiarare che la funzione supporta ShouldProcess (come illustrato nell'esempio precedente).

Per altre informazioni su questo metodo, vedere System.Management.Automation.Cmdlet.ShouldProcess.

Per altre informazioni su come richiedere la conferma, vedere Richiesta di conferma.

ShouldContinue

Questo metodo viene chiamato per richiedere un secondo messaggio di conferma. Deve essere chiamato quando il metodo ShouldProcess restituisce $true. Per altre informazioni su questo metodo, vedere System.Management.Automation.Cmdlet.ShouldContinue.

Metodi di errore

Le funzioni possono chiamare due metodi diversi quando si verificano errori. Quando si verifica un errore non irreversibile, la funzione deve chiamare il metodo WriteError, descritto nella sezione Write metodi. Quando si verifica un errore irreversibile e la funzione non può continuare, deve chiamare il metodo ThrowTerminatingError. È anche possibile usare l'istruzione throw per gli errori irreversibili e il cmdlet write-error per errori non irreversibili.

Per altre informazioni, vedere System.Management.Automation.Cmdlet.ThrowTerminatingError.

Scrivere metodi

Una funzione può chiamare i metodi seguenti per restituire tipi diversi di output. Si noti che non tutti gli output passano al comando successivo nella pipeline. È anche possibile usare i vari cmdlet Write, ad esempio Write-Error.

WriteCommandDetail

Per informazioni sul metodo WriteCommandDetails, vedere System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Per fornire informazioni che possono essere usate per risolvere i problemi di una funzione, chiamare la funzione il metodo WriteDebug. Il metodo WriteDebug visualizza i messaggi di debug all'utente. Per altre informazioni, vedere System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Le funzioni devono chiamare questo metodo quando si verificano errori non irreversibili e la funzione è progettata per continuare l'elaborazione dei record. Per altre informazioni, vedere System.Management.Automation.Cmdlet.WriteError.

Nota

Se si verifica un errore irreversibile, la funzione deve chiamare il metodo ThrowTerminatingError.

WriteObject

Il metodo WriteObject consente alla funzione di inviare un oggetto al comando successivo nella pipeline. Nella maggior parte dei casi, WriteObject è il metodo da usare quando la funzione restituisce dati. Per altre informazioni, vedere System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Per le funzioni con azioni che richiedono molto tempo, questo metodo consente alla funzione di chiamare il metodo WriteProgress in modo che vengano visualizzate le informazioni sullo stato di avanzamento. Ad esempio, è possibile visualizzare la percentuale di completamento. Per altre informazioni, vedere System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Per fornire informazioni dettagliate sull'operazione eseguita dalla funzione, chiamare il metodo WriteVerbose per visualizzare messaggi dettagliati all'utente. Per impostazione predefinita, i messaggi dettagliati non vengono visualizzati. Per altre informazioni, vedere System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Per fornire informazioni sulle condizioni che possono causare risultati imprevisti, chiamare la funzione il metodo WriteWarning per visualizzare i messaggi di avviso all'utente. Per impostazione predefinita, vengono visualizzati messaggi di avviso. Per altre informazioni, vedere System.Management.Automation.PSCmdlet.WriteWarning.

Nota

È anche possibile visualizzare i messaggi di avviso configurando la variabile $WarningPreference oppure usando le opzioni della riga di comando Verbose e Debug. per altre informazioni sulla variabile $WarningPreference, vedere about_Preference_Variables.

Altri metodi e proprietà

Per informazioni sugli altri metodi e proprietà accessibili tramite la variabile $PSCmdlet, vedere System.Management.Automation.PSCmdlet.

Ad esempio, la proprietà ParameterSetName consente di visualizzare il set di parametri in uso. I set di parametri consentono di creare una funzione che esegue attività diverse in base ai parametri specificati quando viene eseguita la funzione.

Vedere anche

  • Last updated on