Partager via

à_propos_des_Fonctions_Avancées

Brève description

Présente des fonctions avancées qui permettent de créer des applets de commande à l’aide de scripts.

Description longue

Une applet de commande est une seule commande qui participe à la sémantique de pipeline de PowerShell. Cela inclut des applets de commande binaires, des fonctions avancées PowerShell et des applets de commande CDXML.

Les fonctions avancées vous permettent de créer des applets de commande écrites en tant que fonction PowerShell. Les fonctions avancées facilitent la création d’applets de commande sans avoir à écrire et compiler une applet de commande binaire. Les applets de commande binaires sont des classes .NET écrites dans un langage .NET tel que C#.

Les fonctions avancées utilisent l’attribut CmdletBinding pour les identifier en tant que fonctions qui agissent comme des applets de commande. L’attribut CmdletBinding est similaire à l’attribut Cmdlet utilisé dans les classes d’applet de commande compilées pour identifier la classe en tant qu’applet de commande. Pour plus d’informations sur cet attribut, consultez about_Functions_CmdletBindingAttribute.

Les paramètres de la fonction sont des variables déclarées dans l’instruction param(). Vous pouvez utiliser l’attribut [Parameter()] facultatif seul ou en combinaison avec l’attribut [Alias()] ou l’un des attributs de validation de paramètre. Pour plus d’informations sur la façon de déclarer des paramètres, consultez about_Functions_Advanced_Parameters.

L’exemple suivant montre une fonction qui accepte un nom, puis imprime un message d’accueil à l’aide du nom fourni. Notez également que cette fonction définit un nom qui inclut un verbe (Envoyer) et une paire nom (Greeting) comme la paire verbe-nom d’une applet de commande compilée. Toutefois, les fonctions ne sont pas tenues d'avoir un nom de type verbe-nom.

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

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

Cette fonction effectue le travail dans le bloc process, qui équivaut à la méthode ProcessingRecord utilisée dans les applets de commande compilées. Le bloc process et les autres blocs nommés sont décrits dans about_Functions_Advanced_Methods.

Les fonctions avancées diffèrent des applets de commande compilées de la manière suivante :

  • La liaison avancée des paramètres de fonction ne lève pas d’exception lorsqu’un tableau de chaînes de caractères est associé à un paramètre booléen .
  • L’attribut ValidateSet et l’attribut ValidatePattern ne peuvent pas passer de paramètres nommés.
  • Les fonctions avancées ne peuvent pas être utilisées dans les transactions.

PIPELINESTOPTOKEN

À compter de PowerShell 7.6-preview.4, $PSCmdlet inclut la propriété PipelineStopToken permettant d’accéder à une CancellationToken liée à la source d’événement d’arrêt PowerShell. Le jeton est déclenché lorsque le pipeline PowerShell reçoit une demande d’arrêt. Utilisez-la avec une méthode .NET qui accepte une surcharge de CancellationToken pour quitter la méthode lorsqu’elle est demandée plutôt que d’attendre que la méthode retourne.

Dans l’exemple suivant, la fonction appelle HttpClient.GetStringAsync, ce qui peut prendre du temps pour répondre lorsque le réseau est lent ou qu’il y a beaucoup de données retournées.

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

Voir aussi

  • Last updated on