Share via

about_Functions_CmdletBindingAttribute

  • Articolo

Descrizione breve

Descrive l'attributo che rende una funzione funzionante come un cmdlet compilato.

Descrizione lunga

L'attributo CmdletBinding è un attributo di funzioni che li rende utilizzabili come cmdlet compilati scritti in C#. Fornisce l'accesso alle funzionalità dei cmdlet.

PowerShell associa i parametri delle funzioni che hanno l'attributo CmdletBinding nello stesso modo in cui associa i parametri dei cmdlet compilati. La $PSCmdlet variabile automatica è disponibile per le funzioni con l'attributo CmdletBinding , ma la $Args variabile non è disponibile.

Nelle funzioni con l'attributo , parametri sconosciuti e argomenti posizionali che non dispongono di parametri posizionali corrispondenti causano l'esito CmdletBinding negativo dell'associazione di parametri.

Nota

I cmdlet compilati usano l'attributo obbligatorio Cmdlet , simile 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 . Una breve descrizione di ogni argomento segue questo esempio.

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

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

I tipi di argomento booleani dell'attributo CmdletBinding predefinito su False quando vengono omessi dall'attributo CmdletBinding . Impostare il valore dell'argomento su $true o semplicemente elencare l'argomento in base al nome. Ad esempio, gli attributi CmdletBinding seguenti sono equivalenti.

{
    [CmdletBinding(SupportsPaging=$true)]

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

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

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

ConfirmImpact

L'argomento ConfirmImpact specifica quando l'azione della funzione deve essere confermata da una chiamata al metodo ShouldProcess. La chiamata al metodo ShouldProcess visualizza una richiesta di conferma solo quando l'argomento ConfirmImpact è uguale o maggiore del valore della $ConfirmPreference variabile di preferenza. Il valore predefinito dell'argomento è Medio.) Specificare questo argomento solo quando viene specificato anche l'argomento SupportsShouldProcess .

Per altre informazioni sulle richieste di conferma, vedere Richiesta di conferma.

DefaultParameterSetName

L'argomento DefaultParameterSetName specifica il nome del set di parametri che PowerShell tenterà di usare quando non è in grado di determinare quale parametro impostare da usare. È possibile evitare questo problema rendendo il parametro univoco di ogni parametro impostato su un parametro obbligatorio.

HelpURI

L'argomento HelpURI specifica l'indirizzo Internet della 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 utilizzato per il valore della proprietà HelpURI dell'oggetto CommandInfo che Get-Command restituisce per la funzione.

Tuttavia, quando i file della Guida vengono installati nel computer e il valore del primo collegamento nella sezione RelatedLinks del file della Guida è un URI oppure il valore della prima .Link direttiva nella Guida basata su commenti è un URI, l'URI nel file della Guida viene usato come valore della proprietà HelpUri della funzione.

Il Get-Help cmdlet usa il valore della proprietà HelpURI per individuare la versione online dell'argomento della Guida della funzione quando il parametro Online di Get-Help viene specificato 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 grande. Questo argomento è progettato per cmdlet e funzioni che restituiscono dati da archivi dati di grandi dimensioni che supportano la selezione dei dati, ad esempio un database SQL.

Questo argomento è stato introdotto in Windows PowerShell 3.0.

  • Primo: ottiene solo i primi oggetti 'n'.
  • Ignora: ignora i primi oggetti 'n' e quindi ottiene gli oggetti rimanenti.
  • IncludeTotalCount: segnala il numero di oggetti nel set di dati (un numero intero) seguito dagli oggetti . Se il cmdlet non è in grado di determinare il conteggio totale, restituisce "Conteggio totale sconosciuto".

PowerShell include NewTotalCount, un metodo helper che ottiene il valore del conteggio totale da restituire e include una stima dell'accuratezza del valore del conteggio totale.

La funzione di esempio seguente illustra come aggiungere il supporto per i parametri di paging a una funzione avanzata.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    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 i parametri Confirm e WhatIf alla funzione . Il parametro Confirm richiede all'utente prima di eseguire il comando su ogni oggetto nella pipeline. Il parametro WhatIf elenca le modifiche apportate dal comando anziché eseguire il comando.

PositionalBinding

L'argomento PositionalBinding determina se i parametri nella funzione sono posizionali per impostazione predefinita. Il valore predefinito è $True. È possibile utilizzare l'argomento PositionalBinding con un valore di $False per disabilitare l'associazione posizionale.

L'argomento PositionalBinding viene introdotto in Windows PowerShell 3.0.

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

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

Quando PositionalBinding è $True, i parametri della funzione sono posizionali per impostazione predefinita. PowerShell assegna il numero di posizione ai parametri nell'ordine in cui vengono dichiarati nella funzione.

Quando PositionalBinding è $False, i parametri della funzione non sono posizionali per impostazione predefinita. A meno che l'argomento Position dell'attributo Parameter non venga dichiarato nel parametro, il nome del parametro (o 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 utilizzare l'argomento Position per specificare un valore di posizione per un parametro. Per altre informazioni sull'argomento Position , vedere about_Functions_Advanced_Parameters.

Note

L'argomento SupportsTransactions non è supportato nelle funzioni avanzate.

Parole chiave

about_Functions_CmdletBinding_Attribute

Vedi anche