ARGOMENTO

about_Functions_Advanced_Methods

DESCRIZIONE BREVE
Descrive come le funzioni che specificano l'attributo
CmdletBinding possono utilizzare i metodi e le proprietà
disponibili ai cmdlet compilati.

DESCRIZIONE DETTAGLIATA
Le funzioni che specificano l'attributo CmdletBinding possono
accedere a vari metodi e proprietà tramite la variabile $pscmdlet. Tra
questi metodi sono inclusi:

- Metodi di elaborazione dell'input utilizzati per il

funzionamento dei cmdlet.

- Metodi ShouldProcess e ShouldContinue utilizzati per

ottenere feedback dall'utente prima di eseguire un azione.

- Metodo ThrowTerminatingError per la generazione di record

di errore.

- Vari metodi Write che restituiscono diversi tipi di output.

- Vari metodi Write che restituiscono diversi tipi di output.

Tutti i metodi e le proprietà della classe PSCmdlet sono

disponibili per le funzioni avanzate. Per ulteriori informazioni
su questi metodi e proprietà, vedere System.Management.Automation.
PSCmdlet in MSDN Library all'indirizzo
http://go.microsoft.com/fwlink/?LinkId=142139 (le informazioni
potrebbero essere in lingua inglese).

Metodi di elaborazione dell'input

I metodi descritti in questa sezione sono definiti come metodi di

elaborazione dell'input. Per le funzioni, questi tre metodi vengono
rappresentati dai blocchi Begin, Process ed End della funzione. Ogni
funzione deve includere uno o più di questi blocchi. In fase di
esecuzione di Windows PowerShell viene utilizzato il codice incluso
in questi blocchi per l'esecuzione di una funzione. Questi blocchi
sono anche disponibili alle funzioni che non utilizzano l'attributo
CmdletBinding.

Begin
Questo blocco è utilizzato per fornire pre-elaborazione unica
facoltativa per la funzione. In fase di esecuzione di Windows
PowerShell viene utilizzato il codice incluso in questo blocco
una volta per ogni istanza della funzione nella pipeline.

Process
Questo blocco è utilizzato per fornire elaborazione record per
record per la funzione. Questo blocco può essere utilizzato
qualsiasi numero di volte o non essere utilizzato affatto, a seconda
 dell'input della funzione. Ad esempio, se la funzione è il primo
comando nella pipeline, il blocco Process sarà utilizzato una sola
volta. Se la funzione non è il primo comando nella pipeline, il
blocco Process sarà utilizzato una volta per ogni input che la
funzione riceve dalla pipeline. Se non vi è alcun input della
pipeline, il blocco Process non sarà utilizzato.

Questo blocco deve essere definito se un parametro della funzione

è impostato per accettare input della pipeline. Se questo blocco non
è definito e il parametro accetta input dalla pipeline, mancheranno
i valori passati alla funzione tramite la pipeline.

Inoltre, quando la funzione supporta richieste di conferma

(quando il parametro SupportsShouldProcess dell'attributo
Parameter è impostato su $True), la chiamata al metodo
ShouldProcess deve essere effettuata dall'interno del blocco
Process.

End
Questo blocco è utilizzato per fornire post-elaborazione unica
facoltativa per la funzione.

Nell'esempio seguente viene mostrata la struttura di una

funzione che contiene un blocco Begin per la pre-elaborazione
unica, un blocco Process per l'elaborazione di più record e un
blocco End per post-elaborazione unica.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}

Metodi di conferma

ShouldProcess
Questo metodo è chiamato per richiedere la conferma dell'utente
prima che la funzione esegua un'azione che modificherebbe 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. Inoltre,
l'attributo CmdletBinding deve dichiarare che la funzione supporta
ShouldProcess (come mostrato nell'esempio precedente).

Per ulteriori informazioni su questo metodo, vedere

System.Management.Automation.Cmdlet.ShouldProcess in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142142 (le
informazioni potrebbero essere in lingua inglese).

Per ulteriori informazioni sulla richiesta di conferma, vedere

l'argomento relativo in MSDN Library all'indirizzo
http://go.microsoft.com/fwlink/?LinkID=136658 (le informazioni
potrebbero essere in lingua inglese).
 ShouldContinue
Questo metodo è chiamato per richiedere un secondo messaggio di
conferma. Deve essere chiamato quando il metodo ShouldProcess
restituisce $true. Per ulteriori informazioni su questo metodo,
vedere.
System.Management.Automation.Cmdlet.ShouldContinue in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142143 (le
informazioni potrebbero essere in lingua inglese).

Metodi di errore

Le funzioni possono chiamare due metodi diversi quando si

verificano errori. Quando si verifica un errore non fatale, la
funzione deve chiamare il metodo WriteError, descritto nella
sezione "Metodi Write". Quando si verifica un errore fatale e la
funzione non può continuare, deve chiamare il metodo
ThrowTerminatingError. È anche possibile utilizzare l'istruzione
Throw per gli errori fatali e il cmdlet Write-Error per gli errori non
fatali.

Per ulteriori informazioni, vedere System.Management.Automation.Cm

dlet.
ThrowTerminatingError in MSDN Libray all'indirizzo
http://go.microsoft.com/fwlink/?LinkId=142144 (le informazioni
potrebbero essere in lingua inglese).

Metodi Write

Una funzione può chiamare i metodi seguenti per restituire tipi

diversi di output. Notare che non tutto l'output passa al comando
successivo nella pipeline. È anche possibile utilizzare i vari cmdlet
Write, ad esempio Write-Error.

WriteCommandDetail
Per informazioni sul metodo WriteCommandDetails, vedere
System.Management.Automation.Cmdlet.WriteCommandDetail in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142155 (le
informazioni potrebbero essere in lingua inglese).

WriteDebug
Per fornire informazioni che possono essere utilizzate per
risolvere i problemi relativi a una funzione, impostare la
funzione in modo che chiami il metodo WriteDebug. In questo
modo vengono visualizzati dall'utente i messaggi di debug. Per
ulteriori informazioni, vedere
System.Management.Automation.Cmdlet.WriteDebug in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142156 (le
informazioni potrebbero essere in lingua inglese).

WriteError
Le funzioni devono chiamare questo metodo quando si verificano
errori non fatali e la funzione è progettata per continuare
l'elaborazione dei record. Per ulteriori informazioni, vedere
System.Management.Automation.Cmdlet.WriteError in MSDN Library
 all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142157 (le
informazioni potrebbero essere in lingua inglese).

Nota: se si verifica un errore fatale, la funzione deve

chiamare il metodo ThrowTerminatingError.

WriteObject
Questo metodo consente alla funzione di inviare un oggetto al
comando successivo nella pipeline. Nella maggior parte dei
casi, questo è il metodo da utilizzare quando la funzione
restituisce dati. Per ulteriori informazioni, vedere
System.Management.Automation.PSCmdlet.WriteObject in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142158 (le
informazioni potrebbero essere in lingua inglese).

WriteProgress
Per le funzioni in cui il completamento delle azioni richiede
molto tempo, questo metodo consente alla funzione di chiamare
il metodo WriteProgress in modo da visualizzare le informazioni
sull'avanzamento. È ad esempio possibile visualizzare la percentuale di
completamento. Per ulteriori informazioni, vedere
System.Management.Automation.PSCmdlet.WriteProgress in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142160 (le
informazioni potrebbero essere in lingua inglese).

WriteVerbose
Per fornire informazioni dettagliate sulle operazioni
effettuate da una funzione, impostare la funzione in modo che
chiami il metodo WriteVerbose affinché l'utente visualizzi messaggi
dettagliati. Per impostazione predefinita, i messaggi dettagliati non sono
visualizzati. Per ulteriori informazioni, vedere
System.Management.Automation.PSCmdlet.WriteVerbose in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142162 (le
informazioni potrebbero essere in lingua inglese).

WriteWarning
Per fornire informazioni sulle condizioni che possono provocare
risultati imprevisti, impostare la funzione in modo che chiami
il metodo WriteWarning affinché l'utente visualizzi messaggi di
avviso. Per impostazione predefinita, i messaggi di avviso sono
visualizzati.
Per ulteriori informazioni, vedere
System.Management.Automation.PSCmdlet.WriteWarning in MSDN Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkId=142164 (le
informazioni potrebbero essere in lingua inglese).

Nota: è anche possibile visualizzare i messaggi di avviso

configurando la variabile WarningPreference oppure utilizzando
le opzioni di riga di comando Verbose e Debug.

Altri metodi e proprietà

Per informazioni sugli altri metodi e proprietà accessibili

tramite la variabile $PSCmdlet, vedere
System.Management.Automation.PSCmdlet in MSDN Library all'indirizzo
 http://go.microsoft.com/fwlink/?LinkId=142139 (le informazioni
potrebbero essere in lingua inglese).

Ad esempio, la proprietà ParameterSetName consente di

visualizzare il set di parametri utilizzato. 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
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters