à_propos_des_fonctions

2025-04-17

Description courte

Décrit comment créer et utiliser des fonctions dans PowerShell.

Description longue

Une fonction est une liste d’instructions PowerShell qui a un nom que vous attribuez. Lorsque vous exécutez une fonction, vous tapez le nom de la fonction.

PowerShell définit deux types de fonctions :

Une fonction est un bloc de code qui peut être appelé par nom. Elle peut prendre l’entrée et la sortie de retour. Les fonctions sont définies à l’aide du function mot clé.
Un filtre est un type de fonction conçu pour traiter les données à partir du pipeline. Les filtres sont définis à l’aide du filter mot clé.

Vous pouvez regrouper les instructions d’une fonction dans l’un des quatre blocs de script prédéfinis différents. Ces blocs de script sont nommés à l’aide des mots clés begin, process, endet clean. Si vous n’utilisez pas ces mots clés, PowerShell place les instructions dans le bloc de code approprié.

Les fonctions peuvent également agir comme des applets de commande. Vous pouvez créer une fonction qui fonctionne comme une applet de commande sans utiliser C# de programmation. Pour plus d’informations, consultez about_Functions_Advanced.

Important

Dans les fichiers de script et les modules basés sur des scripts, les fonctions doivent être définies avant de pouvoir être appelées.

Syntaxe de la fonction

Les fonctions sont définies à l’aide de la syntaxe suivante :

function [<scope:>]<name> {
  param([type]$Parameter1 [,[type]$Parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Une fonction inclut les éléments suivants :

Un function mot clé
Étendue (facultative)
Nom que vous sélectionnez
Tout nombre de paramètres nommés (facultatifs), y compris les paramètres dynamiques
Une ou plusieurs instructions PowerShell placées entre accolades {}

Si vous n’utilisez pas l’un des mots clés (begin, process, , endclean) dans une function définition, PowerShell place les instructions dans le end bloc.

Pour plus d’informations sur le dynamicparam mot clé et les paramètres dynamiques dans les fonctions, consultez about_Functions_Advanced_Parameters.

Une fonction peut être aussi simple que :

function Get-PowerShellProcess { Get-Process pwsh }

Une fois qu’une fonction est définie, vous pouvez l’utiliser comme les applets de commande intégrées. Par exemple, pour appeler la fonction nouvellement définie Get-PowerShellProcess :

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

Une fonction peut également être aussi complexe qu’une applet de commande.

Les fonctions peuvent retourner des valeurs qui peuvent être affichées, affectées à des variables ou transmises à d’autres fonctions ou applets de commande. Vous pouvez utiliser le mot clé pour retourner la return sortie. Le return mot clé n’affecte pas ou ne supprime pas d’autres sorties retournées par votre fonction. Toutefois, le return mot clé quitte la fonction à cette ligne. Pour plus d’informations, consultez about_Return.

Syntaxe de filtre

L’intention de la filter fonction est de fournir un moyen court de définir une fonction qui s’exécute sur chaque objet du pipeline.

La syntaxe d’un filtre est la suivante :

filter [<scope:>]<name> {<statement list>}

Pour simplifier la syntaxe des filter fonctions, omettez le mot clé de bloc de script (begin, process, endclean). PowerShell place les instructions dans le process bloc. Vous pouvez utiliser l’un des autres blocs d’une fonction de filtre, mais l’intention était de fournir un moyen court de définir une fonction qui a le seul objectif de traiter chaque objet dans le pipeline.

Le filtre suivant accepte les entrées de journal à partir du pipeline, puis affiche l’entrée entière ou uniquement la partie message de l’entrée :

filter Get-EventMessage ([switch]$MessageOnly) {
  if ($MessageOnly) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Elle peut être utilisée comme suit :

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

Méthodes de traitement d’entrée

Les méthodes décrites dans cette section sont appelées méthodes de traitement d’entrée. Pour les fonctions, ces trois méthodes nommées à l’aide des blocs beginet process des endblocs de la fonction. PowerShell 7.3 ajoute une clean méthode de processus de bloc.

Vous n’êtes pas obligé d’utiliser ces blocs dans vos fonctions. Si vous n’utilisez pas de bloc nommé, PowerShell place le code dans le end bloc de la fonction. Toutefois, si vous utilisez l’un de ces blocs nommés ou définissez un dynamicparam bloc, vous devez placer tout le code dans un bloc nommé.

L’exemple suivant montre le plan d’une fonction qui contient un bloc pour le begin prétraitement unique, un process bloc de données à partir du pipeline et un end bloc pour le post-traitement unique.

Function Test-ScriptCmdlet {
    [CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
}

`begin`

Ce bloc est utilisé pour fournir un prétraitement unique facultatif pour la fonction. Le runtime PowerShell utilise le code de ce bloc une fois pour chaque instance de la fonction dans le pipeline.

`process`

Ce bloc est utilisé pour fournir un traitement d’enregistrement par enregistrement pour la fonction. Vous pouvez utiliser un process bloc sans définir les autres blocs. Le nombre d’exécutions de blocs dépend de process la façon dont vous utilisez la fonction et de l’entrée que la fonction reçoit.

Variable automatique $_ ou $PSItem contient l’objet actuel dans le pipeline à utiliser dans le process bloc. La $input variable automatique contient un énumérateur disponible uniquement pour les fonctions et les blocs de script. Pour plus d’informations, consultez about_Automatic_Variables.

Si la fonction est appelée sans entrée de pipeline, PowerShell exécute le process bloc une seule fois.
Dans un pipeline, le process bloc s’exécute une fois pour chaque objet d’entrée qui atteint la fonction.
Si l’entrée de pipeline qui atteint la fonction est vide, le process bloc n’est pas exécuté.
- Les beginblocs et end les blocs cleans’exécutent toujours.

Important

Si un paramètre de fonction accepte l’entrée de pipeline et qu’un bloc n’est pas défini, le process traitement d’enregistrement par enregistrement échoue. Dans ce cas, votre fonction s’exécute une seule fois, quelle que soit l’entrée.

`end`

Utilisez ce bloc pour fournir un post-traitement unique facultatif pour la fonction.

`clean`

Le clean bloc a été ajouté dans PowerShell 7.3.

Le bloc clean est un moyen pratique pour les utilisateurs de nettoyer les ressources qui se trouvent dans les blocs begin, process et end. Il est sémantiquement similaire à un bloc finally qui couvre tous les autres blocs nommés d'une fonction de script ou d’une applet de commande de script. Un nettoyage des ressources est effectué dans les cas suivants :

lorsque l’exécution du pipeline se termine sans terminer l’erreur
lorsque l’exécution du pipeline est interrompue en raison d’une erreur de terminaison
lorsque le pipeline est tronqué, par exemple : Select-Object -First
lorsque le pipeline est arrêté par Ctrl+c ou StopProcessing()

Le bloc propre ignore toute sortie écrite dans le flux de réussite .

Attention

L’ajout du bloc clean est un changement cassant. Étant donné que clean est analysé comme un mot clé, il empêche les utilisateurs d’appeler directement une commande nommée clean comme première déclaration dans un bloc de script. Toutefois, il n’est pas probable qu’il s’agit d’un problème. Vous pouvez toujours appeler la commande à l’aide de l’opérateur d’appel (& clean).

Fonctions simples

Les fonctions n’ont pas besoin d’être compliquées pour être utiles. Les fonctions les plus simples ont le format suivant :

function <function-name> { statements }

Par exemple, la fonction suivante démarre PowerShell avec l’option Exécuter en tant qu’administrateur .

function Start-PSAdmin { Start-Process PowerShell -Verb RunAs }

Pour utiliser la fonction, tapez : Start-PSAdmin

Pour ajouter des instructions à la fonction, tapez chaque instruction sur une ligne distincte ou utilisez un point-virgule (;) pour séparer les instructions.

Par exemple, la fonction suivante recherche tous les fichiers dans les .jpg répertoires de l’utilisateur actuel qui ont été modifiés après la date de début.

function Get-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | Where-Object {$_.LastWriteTime -gt $Start}
}

Vous pouvez créer une boîte à outils de petites fonctions utiles. Ajoutez ces fonctions à votre profil PowerShell, comme décrit dans about_Profiles et plus loin dans cet article.

Noms des fonctions

Vous pouvez affecter n’importe quel nom à une fonction. Toutefois, pour les fonctions que vous partagez avec d’autres personnes, vous devez suivre les règles de nommage PowerShell standard.

Les noms doivent se composer d’une paire verbe-nom où le verbe identifie l’action que la fonction exécute et le nom identifie l’élément sur lequel l’applet de commande effectue l’action.
Les noms doivent utiliser les verbes approuvés pour toutes les commandes PowerShell. L’utilisation de verbes approuvés crée une cohérence pour les utilisateurs.

Pour plus d’informations sur les verbes PowerShell standard, consultez Verbes approuvés.

Fonctions avec paramètres

Vous pouvez utiliser des paramètres avec des fonctions, notamment des paramètres nommés, des paramètres positionnels, des paramètres de commutateur et des paramètres dynamiques. Pour plus d’informations sur les paramètres dynamiques dans les fonctions, consultez about_Functions_Advanced_Parameters.

Paramètres nommés

Vous pouvez définir n’importe quel nombre de paramètres nommés. Vous pouvez inclure une valeur par défaut pour les paramètres nommés, comme décrit plus loin dans cet article.

Vous pouvez définir des paramètres à l’intérieur des accolades à l’aide du param mot clé, comme indiqué dans l’exemple de syntaxe suivant :

function <name> {
  param ([type]$Parameter1 [,[type]$Parameter2])
  <statement list>
}

Vous pouvez également définir des paramètres en dehors des accolades sans le param mot clé, comme indiqué dans l’exemple de syntaxe suivant :

function <name> [([type]$Parameter1[,[type]$Parameter2])] {
  <statement list>
}

Par exemple, la fonction suivante utilise la syntaxe alternative pour définir deux paramètres :

function Add-Numbers([int]$One, [int]$Two) {
    $One + $Two
}

Bien que la première méthode soit préférée, il n’existe aucune différence entre ces deux méthodes.

Lorsque vous exécutez la fonction, la valeur que vous fournissez pour un paramètre est affectée à une variable qui contient le nom du paramètre. La valeur de cette variable peut être utilisée dans la fonction.

L’exemple suivant est une fonction appelée Get-SmallFiles. Cette fonction a un $Size paramètre. La fonction affiche tous les fichiers plus petits que la valeur du $Size paramètre et exclut les répertoires :

function Get-SmallFiles {
  param ($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Dans la fonction, vous pouvez utiliser la $Size variable, qui est le nom défini pour le paramètre.

Pour utiliser cette fonction, tapez la commande suivante :

Get-SmallFiles -Size 50

Vous pouvez également entrer une valeur pour un paramètre nommé sans le nom du paramètre. Par exemple, la commande suivante donne le même résultat qu’une commande qui nomme le paramètre Size :

Get-SmallFiles 50

Pour définir une valeur par défaut pour un paramètre, tapez un signe égal et la valeur après le nom du paramètre, comme indiqué dans la variante suivante de l’exemple Get-SmallFiles :

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Si vous tapez Get-SmallFiles sans valeur, la fonction affecte 100 à $size. Si vous fournissez une valeur, la fonction utilise cette valeur.

Si vous le souhaitez, vous pouvez fournir une brève chaîne d’aide qui décrit la valeur par défaut de votre paramètre, en ajoutant l’attribut PSDefaultValue à la description de votre paramètre et en spécifiant la propriété Help de PSDefaultValue. Pour fournir une chaîne d’aide qui décrit la valeur par défaut (100) du paramètre Size dans la Get-SmallFiles fonction, ajoutez l’attribut PSDefaultValue , comme illustré dans l’exemple suivant.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Pour plus d’informations sur la classe d’attribut PSDefaultValue , consultez les membres de l’attribut PSDefaultValue.

Paramètres positionnels

Un paramètre positionnel est un paramètre sans nom de paramètre. PowerShell utilise l’ordre de valeur de paramètre pour associer chaque valeur de paramètre à un paramètre dans la fonction.

Lorsque vous utilisez des paramètres positionnels, tapez une ou plusieurs valeurs après le nom de la fonction. Les valeurs des paramètres positionnels sont affectées à la $args variable de tableau. La valeur qui suit le nom de la fonction est affectée à la première position du $args tableau. $args[0]

La fonction suivante Get-Extension ajoute l’extension .txt de nom de fichier à un nom de fichier que vous fournissez :

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Paramètres de commutateur

Un commutateur est un paramètre qui ne nécessite pas de valeur. Au lieu de cela, vous tapez le nom de la fonction suivi du nom du paramètre switch.

Pour définir un paramètre de commutateur, spécifiez le type [switch] avant le nom du paramètre, comme illustré dans l’exemple suivant :

function Switch-Item {
  param ([switch]$On)
  if ($On) { "Switch on" }
  else { "Switch off" }
}

Lorsque vous tapez le On paramètre switch après le nom de la fonction, la fonction s’affiche Switch on. Sans le paramètre switch, il s’affiche Switch off.

Switch-Item -On

Switch on

Switch-Item

Switch off

Vous pouvez également affecter une valeur booléenne à un commutateur lorsque vous exécutez la fonction, comme illustré dans l’exemple suivant :

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Utiliser la mise en forme pour passer des valeurs de paramètre

Vous pouvez utiliser la mise en forme pour représenter les paramètres d’une commande. Cette fonctionnalité est introduite dans Windows PowerShell 3.0.

Utilisez cette technique dans les fonctions qui appellent des commandes dans la session. Vous n’avez pas besoin de déclarer ou d’énumérer les paramètres de commande ou de modifier la fonction lorsque les paramètres de commande changent.

L’exemple de fonction suivant appelle l’applet Get-Command de commande. La commande utilise @args pour représenter les paramètres de Get-Command.

function Get-MyCommand { Get-Command @args }

Vous pouvez utiliser tous les paramètres de Get-Command lorsque vous appelez la Get-MyCommand fonction. Les paramètres et les valeurs de paramètre sont passés à la commande à l’aide @argsde .

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

La @args fonctionnalité utilise le $args paramètre automatique, qui représente les paramètres et valeurs d’applet de commande non déclarés des arguments restants.

Pour plus d’informations, consultez about_Splatting.

Piping d’objets vers des fonctions

N’importe quelle fonction peut prendre une entrée à partir du pipeline. Vous pouvez contrôler comment une fonction traite les entrées à partir du pipeline à l’aide de mots clés, beginet process en utilisantend. clean L’exemple de syntaxe suivant montre ces mots clés :

La process liste d’instructions s’exécute une fois pour chaque objet du pipeline. Pendant que le process bloc est en cours d’exécution, chaque objet de pipeline est affecté à la variable automatique, un objet de pipeline à la $_ fois.

La fonction suivante utilise le process mot clé. La fonction affiche les valeurs du pipeline :

function Get-Pipeline
{
  process {"The value is: $_"}
}

1, 2, 4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Si vous souhaitez une fonction qui peut prendre une entrée de pipeline ou une entrée à partir d’un paramètre, le process bloc doit gérer les deux cas. Par exemple :

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1, 2, 3, 4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1, 2, 3, 4
10

Lorsque vous utilisez une fonction dans un pipeline, les objets dirigés vers la fonction sont affectés à la $input variable automatique. La fonction exécute des instructions avec le bloc de begin script avant que les objets ne proviennent du pipeline. La fonction exécute des instructions avec le bloc de end script lorsqu’il n’y a plus d’objets dans le pipeline.

L’exemple suivant montre la $input variable automatique utilisée dans les blocs et begin blocs de end script.

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Lorsque vous exécutez la fonction avec une entrée de pipeline, les résultats suivants s’affichent :

1, 2, 4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Lorsque l’instruction begin s’exécute, la fonction n’a pas l’entrée du pipeline. L’instruction end s’exécute une fois que la fonction a les valeurs.

Si la fonction a un process mot clé, chaque objet est $input supprimé et $input affecté à $_. L’exemple suivant contient une liste d’instructions process :

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

Dans cet exemple, chaque objet dirigé vers la fonction est envoyé à la process liste des instructions. Les process instructions s’exécutent sur chaque objet, un objet à la fois. La $input variable automatique est vide lorsque la fonction atteint le end mot clé.

1, 2, 4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Pour plus d’informations, consultez Utilisation des énumérateurs

PowerShell 7.3 a ajouté le clean bloc. Le bloc clean est un moyen pratique pour les utilisateurs de nettoyer les ressources créées et utilisées dans les blocs begin, process et end. Il est sémantiquement similaire à un bloc finally qui couvre tous les autres blocs nommés d'une fonction de script ou d’une applet de commande de script. Un nettoyage des ressources est effectué dans les cas suivants :

lorsque l’exécution du pipeline se termine normalement sans erreur de terminaison
lorsque l’exécution du pipeline est interrompue en raison d’une erreur de terminaison
lorsque le pipeline est tronqué, par exemple : Select-Object -First
lorsque le pipeline est arrêté par Ctrl+C ou StopProcessing()

Attention

L’ajout du bloc clean est un changement cassant. Étant donné que clean est analysé comme un mot clé, il empêche les utilisateurs d’appeler directement une commande nommée clean comme première déclaration dans un bloc de script. Toutefois, il n’est pas probable qu’il s’agit d’un problème. La commande peut toujours être appelée à l’aide de l’opérateur d’appel (& clean).

Étendue de la fonction

Une fonction existe dans l’étendue dans laquelle vous la créez.

Si une fonction fait partie d’un script, la fonction est disponible pour les instructions de ce script. Par défaut, une fonction dans un script n’est pas disponible en dehors de ce script.

Vous pouvez spécifier l’étendue d’une fonction. Par exemple, la fonction est ajoutée à l’étendue globale dans l’exemple suivant :

function Global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Lorsqu’une fonction se trouve dans l’étendue globale, vous pouvez utiliser la fonction dans les scripts, dans les fonctions et sur la ligne de commande.

Les fonctions créent une étendue. Les éléments créés dans une fonction, tels que les variables, existent uniquement dans l’étendue de la fonction.

Pour plus d’informations, consultez about_Scopes.

Rechercher et gérer des fonctions à l’aide du `Function:` lecteur

Toutes les fonctions et filtres dans PowerShell sont automatiquement stockés dans le Function: lecteur. Ce lecteur est exposé par le fournisseur de fonction PowerShell.

Lorsque vous faites référence au Function: lecteur, tapez un signe deux-points après la fonction, comme vous le feriez lorsque vous référencez le ou C le D lecteur d’un ordinateur.

La commande suivante affiche toutes les fonctions de la session active de PowerShell :

Get-ChildItem Function:

Les commandes de la fonction sont stockées en tant que bloc de script dans la propriété de définition de la fonction. Par exemple, pour afficher les commandes de la fonction d’aide fournie avec PowerShell, tapez :

(Get-ChildItem Function:help).Definition

Vous pouvez également utiliser la syntaxe suivante.

$Function:help

Pour plus d’informations, consultez about_Function_Provider.

Réutiliser des fonctions dans de nouvelles sessions

Lorsque vous tapez une fonction à l’invite de commandes PowerShell, la fonction fait partie de la session active. La fonction est disponible jusqu’à ce que la session se termine.

Pour utiliser votre fonction dans toutes les sessions PowerShell, ajoutez la fonction à votre profil PowerShell. Pour plus d'informations sur les profils, consultez about_Profiles.

Vous pouvez également enregistrer votre fonction dans un fichier de script PowerShell. Tapez votre fonction dans un fichier texte, puis enregistrez le fichier avec l’extension de nom de .ps1 fichier.

Créer de l’aide pour les fonctions

L’applet de commande obtient de l’aide Get-Help pour les fonctions, les applets de commande, les fournisseurs et les scripts. Pour obtenir de l’aide pour une fonction, tapez Get-Help le nom de la fonction.

Par exemple, pour obtenir de l’aide pour la Get-MyDisks fonction, tapez :

Get-Help Get-MyDisks

Vous pouvez écrire de l’aide pour une fonction à l’aide de l’une des deux méthodes suivantes :

Aide basée sur les commentaires pour Functions

Créez de l’aide à l’aide des mots clés spéciaux dans les commentaires. Pour créer de l’aide basée sur des commentaires pour une fonction, les commentaires doivent être placés au début, à la fin ou dans le corps de la fonction. Pour plus d’informations sur l’aide basée sur les commentaires, consultez about_Comment_Based_Help.
Aide basée sur XML pour Functions

L’aide basée sur XML est requise si vous devez localiser le contenu de l’aide dans plusieurs langues. Pour associer la fonction au fichier d’aide XML, utilisez le mot clé d’aide basé sur les .EXTERNALHELP commentaires. Sans ce mot clé, Get-Help ne trouve pas le fichier d’aide de la fonction et retourne uniquement l’aide générée automatiquement.

Pour plus d’informations sur le .EXTERNALHELP mot clé, consultez about_Comment_Based_Help. Pour plus d’informations sur l’aide basée sur XML, consultez Comment écrire l’aide sur les applets de commande.

Partager via