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 $PSCmdlet variabile . Questi metodi includono i metodi seguenti:

  • Gli stessi metodi di elaborazione di input disponibili per tutte le funzioni.
  • I ShouldProcess metodi 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 Write metodi 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 beginblocchi , 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 end blocco della funzione. Tuttavia, se si usa uno di questi blocchi denominati o si definisce un dynamicparam blocco, è necessario inserire tutto il codice in un blocco denominato.

Nell'esempio seguente viene illustrata la struttura di una funzione che contiene un begin blocco per la pre-elaborazione monouso, un process blocco per l'elaborazione di più record e un end blocco 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 process blocco senza definire gli altri blocchi. Il numero di esecuzioni di process blocchi 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 process blocco. La $input variabile automatica 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 process blocco una sola volta.
  • All'interno di una pipeline, il process blocco viene eseguito una volta per ogni oggetto di input che raggiunge la funzione.
  • Se l'input della pipeline che raggiunge la funzione è vuoto, il process blocco non viene eseguito.
    • I beginblocchi , ende clean continuano a essere eseguiti.

Importante

Se un parametro di funzione è impostato per accettare l'input della pipeline e un process blocco 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 process blocco deve usare la variabile di parametro definita per l'input della $_ pipeline anziché o $PSItem. Ad 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 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()

Il blocco pulito rimuove qualsiasi output scritto nel flusso Success .

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).

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 process {} blocco 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 ShouldProcess metodo 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 WriteError metodo , descritto nella Write sezione metodi . Quando si verifica un errore irreversibile e la funzione non può continuare, deve chiamare il ThrowTerminatingError metodo . È anche possibile usare l'istruzione throw per gli errori irreversibili e il cmdlet Write-Error per gli 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 Write cmdlet, ad esempio Write-Error.

WriteCommandDetail

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

WriteDebug

Per fornire informazioni che possono essere usate per risolvere i problemi di una funzione, chiamare la funzione come WriteDebug metodo . Il WriteDebug metodo 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 WriteObject metodo 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 per il completamento, questo metodo consente alla funzione di chiamare il WriteProgress metodo in modo che vengano visualizzate 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 la funzione per WriteVerbose 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 messaggi di avviso configurando la $WarningPreference variabile o usando le opzioni della Verbose riga di comando e Debug . per altre informazioni sulla $WarningPreference variabile, vedere about_Preference_Variables.

Altri metodi e proprietà

Per informazioni sugli altri metodi e proprietà accessibili tramite la $PSCmdlet variabile , 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