about_Functions_CmdletBindingAttribute

Aggiornamento: maggio 2014

Si applica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

ARGOMENTO

about_Functions_CmdletBindingAttribute

DESCRIZIONE BREVE

In questo articolo viene descritto l'attributo che consente a una funzione di funzionare in modo analogo a un cmdlet compilato.

DESCRIZIONE LUNGA

CmdletBinding è un attributo di funzioni che permette di eseguirle come cmdlet compilati che vengono scritti in C# e fornisce l'accesso alle funzionalità dei cmdlet.

Windows PowerShell® associa i parametri delle funzioni che dispongono dell'attributo CmdletBinding nello stesso modo in cui associa i parametri dei cmdlet compilati. La variabile automatica $PSCmdlet è disponibile per le funzioni con attributo CmdletBinding; tuttavia la variabile $Args non è disponibile.

Nelle funzioni con attributo CmdletBinding, i parametri sconosciuti e gli argomenti posizionali privi di parametri posizionali corrispondenti impediscono di eseguire l'associazione del parametro.

Nota: I cmdlet compilati usano l'attributo obbligatorio Cmdlet, analogo all'attributo CmdletBinding descritto in questo argomento.

SINTASSI

Nell'esempio seguente viene illustrato il formato di una funzione che specifica tutti gli argomenti facoltativi dell'attributo CmdletBinding. Dopo l'esempio, vengono descritti brevemente tutti gli argomenti.

        {
          [CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

          Param ($Parameter1)
          Begin{}
          Process{}
          End{}
        }

ConfirmImpact

L'argomento ConfirmImpact specifica quando è necessario confermare l'azione della funzione da una chiamata al metodo ShouldProcess. La chiamata al metodo ShouldProcess consente di visualizzare una richiesta di conferma soltanto quando l'argomento ConfirmImpact è uguale o maggiore al valore della variabile di preferenza $ConfirmPreference. Il valore predefinito dell'argomento è Medium. Specificare questo argomento soltanto quando viene specificato anche l'argomento SupportsShouldProcess.

Per informazioni sulle richieste di conferma, vedere l'argomento relativo alla richiesta di conferma in MSDN (Microsoft Developer Network) Library all'indirizzo https://go.microsoft.com/fwlink/?LinkId=136658.

DefaultParameterSetName

L'argomento DefaultParameterSetName specifica il nome relativo al set di parametri che Windows PowerShell tenta di usare quando non è possibile determinare il set di parametri da usare. È possibile evitare questo problema rendendo obbligatorio il parametro univoco di ogni set.

HelpURI

L'argomento HelpURI specifica l'indirizzo l'URI dell'indirizzo Internet relativo alla versione online dell'argomento della Guida che descrive la funzione. Il valore dell'argomento HelpUri deve iniziare con "http" o "https".

Il valore dell'argomento HelpURI viene usato per il valore della proprietà HelpURI relativa all'oggetto CommandInfo restituito da Get-Command per la funzione.

Tuttavia, quando si installano i file dell Guida nel computer e il valore del primo link presente nella sezione Realted Links è un URI oppure il valore della direttiva .Link nella Guida basata su commenti è un URI, l'URI contenuto nel file della Guida viene usato come valore della proprietà HelpUri della funzione.

Il cmdlet Get-Help usa il valore della proprietà HelpURI per individuare la versione online dell'argomento della Guida relativo alla funzione, quando viene specificato il parametro di Get-Help Online in un comando.

SupportsPaging

L'argomento SupportsPaging aggiunge i parametri First, Skip e IncludeTotalCount alla funzione. Questi parametri consentono agli utenti di selezionare l'output da un set di risultati molto ampio. Questo argomento è progettato per i cmdlet e per le funzioni che restituiscono dati da archivi dati di grandi dimensioni che supportano la selezione di dati, ad esempio, un database SQL.

Questo argomento è stato introdotto in Windows PowerShell 3.0.

First:

consente di visualizzare soltanto i primi "n" oggetti.

Skip:

ignora i primi "n" oggetti e ottiene quelli rimanenti.

IncludeTotalCount:

indica il numero di oggetti nel set di dati (un numero intero) seguito dagli oggetti. Se il cmdlet non può determinare il numero totale, restituisce "Conteggio totale sconosciuto".

Windows PowerShell include NewTotalCount, un metodo helper che consente di visualizzare il valore del conteggio totale da restituire e include una stima sulla precisione del valore totale.

Nella funzione di esempio seguente viene illustrato come aggiungere il supporto relativo ai parametri di spostamento a una funzione avanzata.

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             param()

             $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
             $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100)

             if ($PSCmdlet.PagingParameters.IncludeTotalCount)
             {
                 $TotalCountAccuracy = 1.0
                 $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy)
                 Write-Output $TotalCount
             }
             $FirstNumber .. $LastNumber | Write-Output
         }

SupportsShouldProcess

L'argomento SupportsShouldProcess aggiunge parametri Confirm e WhatIf alla funzione. Il parametro Confirm chiede l'autorizzazione all'utente prima di eseguire il comando su ogni oggetto nella pipeline. Il parametro WhatIf elenca le modifiche apportate dal comando, invece di eseguirlo.

PositionalBinding

L'argomento PositionalBinding determina se i parametri nella funzione sono posizionali per impostazione predefinita. Il valore predefinito è $True. È possibile usare l'argomento PositionalBinding con valore $False per disattivare i binding posizionali.

L'argomento PositionalBinding è stato introdotto in Windows PowerShell 3.0.

Quando i parametri sono posizionali, il nome del parametro è facoltativo. Windows PowerShell associa i valori dei parametri senza nome ai parametri di funzione, in base all'ordine o alla posizione dei valori relativi al parametro senza nome nel comando di funzione.

Quando i parametri non sono posizionali (sono "denominati"), il nome del parametro (oppure un'abbreviazione o alias del nome) è necessaria nel comando.

Quando PositionalBinding è $True, i parametri della funzione sono posizionali per impostazione predefinita. Windows PowerShell assegna un numero di posizione ai parametri nell'ordine di dichiarazione nella funzione.

Se PositionalBinding è $False, i parametri di funzione non sono posizionali per impostazione predefinita. A meno che l'argomento Position dell'attributo Parameter venga dichiarato nel parametro, il nome del parametro (oppure un alias o un'abbreviazione) deve essere incluso quando il parametro viene usato in una funzione.

L'argomento Position dell'attributo Parameter ha la precedenza sul valore predefinito PositionalBinding. È possibile usare l'argomento Position per specificare un valore di posizione per un parametro. Per altre informazioni sull'argomento Position, vedere about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).

NOTE

L'argomento SupportsTransactions non è supportato nelle funzioni avanzate.

PAROLE CHIAVE

about_Functions_CmdletBinding_Attribute

VEDERE ANCHE

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute