Condividi tramite

about_Functions_Advanced

Breve descrizione

Introduce funzioni avanzate che consentono di creare cmdlet usando script.

Descrizione lunga

Un cmdlet è un singolo comando che partecipa alla semantica della pipeline di PowerShell. Sono inclusi cmdlet binari, funzioni avanzate di PowerShell e cmdlet CDXML.

Le funzioni avanzate consentono di creare cmdlet scritti come funzione di PowerShell. Le funzioni avanzate semplificano la creazione di cmdlet senza dover scrivere e compilare un cmdlet binario. I cmdlet binari sono classi .NET scritte in un linguaggio .NET, ad esempio C#.

Le funzioni avanzate usano l'attributo CmdletBinding per identificarli come funzioni che fungono da cmdlet. L'attributo CmdletBinding è simile all'attributo Cmdlet usato nelle classi di cmdlet compilate per identificare la classe come cmdlet. Per altre informazioni su questo attributo, vedere about_Functions_CmdletBindingAttribute.

I parametri della funzione sono variabili dichiarate nell'istruzione param(). È possibile usare l'attributo facoltativo [Parameter()] da solo o in combinazione con l'attributo [Alias()] o uno qualsiasi degli attributi di convalida dei parametri. Per altre informazioni su come dichiarare i parametri, vedere about_Functions_Advanced_Parameters.

Nell'esempio seguente viene illustrata una funzione che accetta un nome e quindi stampa un messaggio di saluto usando il nome fornito. Si noti anche che questa funzione definisce un nome che include una coppia verbo (Send) e sostantivo (Greeting) come la coppia verb-sostantivo di un cmdlet compilato. Tuttavia, le funzioni non devono avere un nome verbo-sostantivo.

function Send-Greeting
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    process
    {
        Write-Host ("Hello " + $Name + "!")
    }
}

Questa funzione esegue il lavoro nel blocco process, equivalente al metodo ProcessingRecord usato nei cmdlet compilati. Il blocco process e gli altri blocchi denominati sono descritti in about_Functions_Advanced_Methods.

Le funzioni avanzate differiscono dai cmdlet compilati nei modi seguenti:

  • L'associazione avanzata dei parametri di funzione non genera un'eccezione quando una matrice di stringhe è associata a un parametro booleano.
  • L'attributo ValidateSet e l'attributo ValidatePattern non possono passare parametri denominati.
  • Le funzioni avanzate non possono essere usate nelle transazioni.

PIPELINESTOPTOKEN

A partire da PowerShell 7.6-preview.4, $PSCmdlet include la proprietà PipelineStopToken che consente di accedere a un CancellationToken associato all'origine evento di arresto di PowerShell. Il token viene attivato quando la pipeline di PowerShell riceve una richiesta di arresto. Usarlo con un metodo .NET che accetta un overload CancellationToken per uscire dal metodo quando richiesto anziché attendere il completamento del metodo.

Nell'esempio seguente la funzione chiama HttpClient.GetStringAsync, che può richiedere tempo per rispondere quando la rete è lenta o che viene restituita una grande quantità di dati.

function Invoke-CancelableWebRequest {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Url
    )

    $client = [System.Net.Http.HttpClient]::new()
    $client.GetStringAsync(
        $Url,
        $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult()
}

Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10
# Press ctrl+c to cancel

Vedere anche

  • Last updated on