about_Functions

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. Les instructions de la liste s’exécutent comme si vous les aviez tapées à l’invite de commandes.

Les fonctions peuvent être aussi simples que les suivantes :

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 ou une application.

Comme les applets de commande, les fonctions peuvent avoir des paramètres. Les paramètres peuvent être nommés, positionnels, commutateurs ou paramètres dynamiques. Les paramètres de fonction peuvent être lus à partir de la ligne de commande ou du pipeline.

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 également spécifier une valeur de retour à l’aide du return mot clé. 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.

La liste d’instructions de la fonction peut contenir différents types de listes d’instructions avec les mots clés begin, process, endet clean. Ces instructions répertorient les entrées du pipeline différemment.

Le mot clé de filtre est utilisé pour créer un type de fonction qui s’exécute sur chaque objet du pipeline. Un filtre ressemble à une fonction avec toutes ses instructions dans un process bloc.

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.

Syntaxe

Voici la syntaxe d’une fonction :

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

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
• N’importe quel nombre de paramètres nommés (facultatif)
• Une ou plusieurs commandes PowerShell placées entre accolades {}

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

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 sont représentées par les blocs processend et les beginblocs 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 pour le traitement de plusieurs enregistrements 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.

• L’appel de la fonction au début ou en dehors d’un pipeline 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 clean les blocs ends’exécutent toujours.

end

Ce bloc est utilisé 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 :

1. lorsque l’exécution du pipeline se termine normalement sans erreur de terminaison
2. lorsque l’exécution du pipeline est interrompue en raison d’une erreur de terminaison
3. lorsque le pipeline est interrompu par Select-Object -First
4. lorsque le pipeline est arrêté par Ctrl+c ou StopProcessing()

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

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-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | 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 cette rubrique.

Noms de fonctions

Vous pouvez affecter n’importe quel nom à une fonction, mais les fonctions que vous partagez avec d’autres doivent suivre les règles d’affectation de noms établies pour toutes les commandes PowerShell.

Les noms de fonctions doivent se composer d’une paire de verbes où le verbe identifie l’action effectuée par la fonction et le nom identifie l’élément sur lequel l’applet de commande effectue son action.

Les fonctions doivent utiliser les verbes standard approuvés pour toutes les commandes PowerShell. Ces verbes nous aident à maintenir nos noms de commandes cohérents et faciles à comprendre 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 cette rubrique.

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>
}

Vous trouverez ci-dessous un exemple de cette autre syntaxe.

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

Changer de paramètres

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

Utilisation de la mise en forme pour représenter des paramètres de commande

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 Objects to Functions

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, processet clean en utilisantbegin. end 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 begin mot clé avant que les objets ne proviennent du pipeline. La fonction exécute des instructions avec le end mot clé une fois que tous les objets ont été reçus du pipeline.

L’exemple suivant montre la $input variable automatique avec begin et end les mots clés.

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

Si cette fonction est exécutée à l’aide du pipeline, elle affiche les résultats suivants :

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 redirigé vers la fonction est envoyé à la process liste d’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 :

1. lorsque l’exécution du pipeline se termine normalement sans erreur de terminaison
2. lorsque l’exécution du pipeline est interrompue en raison d’une erreur de terminaison
3. lorsque le pipeline est interrompu par Select-Object -First
4. lorsque le pipeline est arrêté par Ctrl+C ou StopProcessing()

Filtres

Un filtre est un type de fonction qui s’exécute sur chaque objet du pipeline. Un filtre ressemble à une fonction avec toutes ses instructions dans un process bloc.

La syntaxe d’un filtre est la suivante :

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

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-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Elle peut être utilisée comme suit :

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Étendue de la fonction

Une fonction existe dans l’étendue dans laquelle elle est créée.

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.

Recherche et gestion des fonctions à l’aide de la fonction : 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 D le C 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 sur le Function: lecteur, consultez la rubrique d’aide du fournisseur de fonctions . Tapez Get-Help Function.

Réutilisation des fonctions dans les 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.

Écriture d’aide pour Functions

L’applet de commande obtient de l’aide Get-Help pour les fonctions, ainsi que pour 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 une rubrique d’aide à l’aide de 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 ou à la fin du corps de la fonction ou sur les lignes précédant le mot clé 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

  Créez une rubrique d’aide basée sur XML, telle que le type généralement créé pour les applets de commande. L’aide basée sur XML est requise si vous localisez des rubriques d’aide dans plusieurs langues.

  Pour associer la fonction à la rubrique d’aide xml, utilisez le mot clé d’aide basé sur les .EXTERNALHELP commentaires. Sans ce mot clé, Get-Help ne trouvez pas la rubrique d’aide de la fonction et les appels à Get-Help la fonction retournent 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.

Voir aussi

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks