RUBRIQUE
about_Functions
DESCRIPTION COURTE
Décrit comment créer et utiliser des fonctions dans Windows PowerShell.
DESCRIPTION LONGUE
Une fonction est une liste d'instructions portant un nom que vous
affectez. Lorsque vous exécutez une fonction, vous tapez son nom. Les
instructions de la liste s'exécutent comme si vous les aviez tapées à
l'invite de commandes.
Tout comme les applets de commande, les fonctions peuvent avoir
des paramètres. Les paramètres peuvent être nommés, positionnels,
booléens ou 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 passées à d'autres
fonctions ou applets de commande.
La liste d'instructions de la fonction peut contenir différents
types de listes d'instructions avec les mots clés Begin, Process
et End. Ces listes d'instructions gèrent l'entrée provenant du
pipeline différemment.
Un filtre est un type spécial de fonction qui utilise le mot clé
Filter.
Les fonctions peuvent également agir comme des applets de
commande. Vous pouvez créer une fonction fonctionnant exactement
comme une applet de commande sans utiliser la programmation C#.
Pour plus d'informations, consultez about_Functions_Advanced.
Syntaxe
Voici la syntaxe pour une fonction :
function [<portée:>]<nom> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<liste d'instructions>}
begin {<liste d'instructions>}
process {<liste d'instructions>}
end {<liste d'instructions>}
}
Une fonction inclut les éléments suivants :
- un mot clé Function ;
- une portée (facultatif) ;
- un nom que vous sélectionnez ;
- un certain nombre de paramètres nommés (facultatif) ;
- une ou plusieurs commandes Windows PowerShell placées
entre accolades ({}).
Pour plus d'informations sur le mot clé Dynamicparam et sur les
paramètres dynamiques des fonctions, consultez
about_Functions_Advanced_Parameters.
Fonctions simples
Les fonctions n'ont pas à être compliquées pour être utiles. La
fonction suivante obtient les variables d'environnement qui
n'appartiennent pas au compte Système du système actuel :
function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<Système>"}
}
Pour exécuter la fonction, tapez " other_env ".
Vous pouvez créer une boîte à outils de petites fonctions
utiles. Ajoutez ces fonctions à votre profil Windows
PowerShell, comme décrit dans about_Profiles et plus loin dans
cette rubrique.
Fonctions avec paramètres
Vous pouvez utiliser des paramètres avec les fonctions,
notamment des paramètres nommés, des paramètres positionnels,
des paramètres booléens et des paramètres dynamiques. Pour plus
d'informations sur les paramètres dynamiques des fonctions,
consultez about_Functions_Advanced_Parameters.
Paramètres nommés
Vous pouvez définir le nombre de paramètres nommés de votre
choix. 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 mot clé Param, 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 à l'extérieur des
accolades sans le mot clé Param, comme indiqué dans l'exemple
de syntaxe suivant :
function <nom> [([type]$parameter1[,[type]$parameter2])] {
<liste d'instructions>
}
Il n'y a aucune différence entre ces deux méthodes. Utilisez la
méthode que vous préférez.
Lorsque vous exécutez la fonction, la valeur que vous
fournissez pour un paramètre est affectée à une variable qui
contient le nom de paramètre. La valeur de cette variable peut
être utilisée dans la fonction.
L'exemple suivant est celui d'une fonction appelée
Petits_fichiers. Cette fonction comporte un paramètre $size.
Elle affiche tous les fichiers dont la taille est inférieure à
la valeur du paramètre $size et exclut les répertoires :
function petits_fichiers {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
Dans la fonction, vous pouvez utiliser la variable $size, qui
correspond au nom défini pour le paramètre.
Pour utiliser cette fonction, tapez la commande suivante :
C:\PS> function petits_fichiers -size 50
Vous pouvez également entrer une valeur pour un paramètre nommé
sans le nom de paramètre. Par exemple, la commande suivante
donne le même résultat qu'une commande qui nomme le paramètre Size :
C:\PS> function petits_fichiers 50
Pour définir une valeur par défaut pour un paramètre, tapez un
signe égal et la valeur après le nom de paramètre, comme
indiqué dans la variation suivante de l'exemple Petits_fichiers :
function petits_fichiers ($size = 100) {
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
Si vous tapez " petits_fichiers " sans valeur, la fonction
affecte 100 à $size. Si vous fournissez une valeur, la fonction
utilise cette valeur.
Paramètres positionnels
Un paramètre positionnel est un paramètre sans nom de
paramètre. Windows PowerShell utilise l'ordre des valeurs de
paramètre pour associer chaque valeur de paramètre à un
paramètre de la fonction.
Lorsque vous utilisez des paramètres positionnels, tapez une ou
plusieurs valeurs après le nom de fonction. Les valeurs de paramètre
positionnel sont affectées à la variable tableau $args. La valeur qui
suit le nom de fonction est affectée à la première position dans le
tableau $args, $args[0].
La fonction Extension suivante ajoute l'extension de nom de
fichier .txt à un nom de fichier que vous fournissez :
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension monFichierTexte
monFichierTexte.txt
Les fonctions peuvent accepter plusieurs paramètres
positionnels. L'exemple suivant affiche toutes les valeurs
entrées avec le nom de fonction.
function repeat { foreach ($arg in $args) { "L'entrée est $arg" } }
C:\PS>repeat un
L'entrée est un
C:\PS> repeat un deux trois
L'entrée est un
L'entrée est deux
L'entrée est trois
Cette fonction peut être utilisée avec tout nombre de valeurs.
La fonction affecte chaque valeur à une position dans le
tableau $args.
Paramètres booléens
Un paramètre booléen est un paramètre qui ne requiert pas de
valeur. À la place, vous tapez le nom de fonction suivi du nom
du paramètre booléen.
Pour définir un paramètre booléen, spécifiez le type [switch]
avant le nom de paramètre, comme indiqué dans l'exemple suivant :
function switchExample {
param ([switch]$on)
if ($on) { "Allumer" }
else { "Éteindre" }
}
Lorsque vous tapez le paramètre booléen On après le nom de
fonction, la fonction affiche " Allumer ". Sans ce paramètre
booléen, elle affiche " Éteindre ".
C:\PS> SwitchExample -on
Allumer
C:\PS> SwitchExample
Éteindre
Vous pouvez également affecter une valeur booléenne à un
paramètre booléen lorsque vous exécutez la fonction, comme
indiqué dans l'exemple suivant :
C:\PS> SwitchExample -on:$true
Allumer
C:\PS> SwitchExample -on:$false
Éteindre
Redirection d'objets vers des fonctions
Toute fonction peut accepter une entrée provenant du pipeline.
Vous pouvez contrôler la façon dont une fonction traite une
entrée provenant du pipeline à l'aide des mots clés Begin,
Process et End. L'exemple de syntaxe suivant affiche les trois
mots clés :
function <nom> {
begin {<liste d'instructions>}
process {<liste d'instructions>}
end {<liste d'instructions>}
}
La liste d'instructions Begin s'exécute une fois seulement, au
début de la fonction.
La liste d'instructions Process s'exécute une fois pour chaque
objet du pipeline.
Pendant l'exécution du bloc Process, chaque objet du pipeline
est affecté, tour à tour, à la variable automatique $_.
Lorsque la fonction a reçu tous les objets du pipeline, la liste
d'instructions End s'exécute une fois. Si aucun mot clé Begin,
Process ou End n'est utilisé, toutes les instructions sont
traitées comme une liste d'instructions End.
La fonction suivante utilise le mot clé Process. Elle affiche
des exemples provenant du pipeline :
function pipelineFunction
{
process {"La valeur est : $_"}
}
Pour une démonstration de cette fonction, entrez un tableau de
nombres créé avec des virgules, comme indiqué dans l'exemple
suivant :
C:\PS> 1,2,4 | pipelineFunction
La valeur est : 1
La valeur est : 2
La valeur est : 4
Lorsque vous utilisez une fonction dans un pipeline, les objets
redirigés vers la fonction sont affectés à la variable
automatique $input. La fonction exécute les instructions avec
le mot clé Begin avant que des objets ne proviennent du
pipeline. La fonction exécute les instructions avec le mot clé
End une fois que tous les objets ont été reçus du pipeline.
L'exemple suivant affiche la variable automatique $input avec
les mots clés Begin et End.
function PipelineBeginEnd
{
begin {"Begin: L'entrée est $input"}
end {"End: L'entrée est $input" }
}
Si cette fonction est exécutée à l'aide du pipeline, elle
affiche les résultats suivants :
C:\PS> 1,2,4 | PipelineBeginEnd
Begin: L'entrée est
End: L'entrée est 1 2 4
Lorsque l'instruction Begin s'exécute, la fonction ne dispose
pas de l'entrée du pipeline. L'instruction End s'exécute une
fois que la fonction dispose des valeurs.
Si la fonction comporte un mot clé Process, elle lit les
données de $input. L'exemple suivant comporte une liste
d'instructions Process :
function PipelineInput
{
process {"Traitement : $_ " }
end {"End: L'entrée est : $input" }
}
Dans cet exemple, chaque objet redirigé vers la fonction est
envoyé à la liste d'instructions Process. Les instructions
Process s'exécutent sur chaque objet, l'un après l'autre. La
variable automatique $input est vide lorsque la fonction
atteint le mot clé End.
C:\PS> 1,2,4 | PipelineInput
Traitement : 1
Traitement : 2
Traitement : 4
End: L'entrée est :
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 bloc Process.
La syntaxe d'un filtre est comme suit :
filter [<portée:>]<nom> {<liste d'instructions>}
Le filtre suivant prend des entrées de journal du pipeline,
puis affiche soit l'entrée complète, soit uniquement la partie
message de l'entrée :
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Portée d'une fonction
Une fonction existe dans la portée dans laquelle elle a été créée.
Si une fonction fait partie d'un script, elle est disponible
pour les instructions au sein de ce script. Par défaut, une
fonction de script n'est pas disponible à l'invite de commandes.
Vous pouvez spécifier la portée d'une fonction. Par exemple, la
fonction est ajoutée à la portée globale dans l'exemple suivant :
function global:get-dependentsvs { get-service |
where {$_.dependentservices} }
Lorsqu'une fonction se trouve dans la portée globale, vous
pouvez l'utiliser dans des scripts, dans des fonctions et sur
la ligne de commande.
Les fonctions créent normalement une portée. Les éléments créés
dans une fonction, tels que les variables, existent uniquement
dans la portée de la fonction.
Pour plus d'informations sur la portée dans Windows PowerShell,
consultez about_Scope.
Recherche et gestion de fonctions à l'aide du lecteur Function:
Dans Windows PowerShell, toutes les fonctions et tous les filtres
sont automatiquement stockés dans le lecteur Function:. Ce lecteur
est exposé par le fournisseur Function de Windows PowerShell.
Pour faire référence au lecteur Function:, tapez un signe
deux-points après Function, tout comme vous le feriez pour le
lecteur C ou D d'un ordinateur.
La commande suivante affiche toutes les fonctions dans la
session active de Windows PowerShell :
C:\PS> dir 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 Help
fournie avec Windows PowerShell, tapez :
(dir function:help).definition
Pour plus d'informations sur le lecteur Function:, consultez
Function.
Réutilisation de fonctions dans de nouvelles sessions
Lorsque vous tapez une fonction à l'invite de commandes Windows
PowerShell, la fonction devient partie intégrante de la session
active. Elle est disponible jusqu'à la fin de la session.
Pour utiliser votre fonction dans toutes les sessions Windows
PowerShell, ajoutez-la à votre profil Windows PowerShell. Pour
plus d'informations sur les profils, consultez about_Profiles.
Vous pouvez également enregistrer votre fonction dans un
fichier de script Windows PowerShell. Tapez votre fonction dans
un fichier texte, puis enregistrez le fichier avec l'extension
de nom de fichier .ps1.
Écriture de rubriques d'aide pour les fonctions
L'applet de commande Get-Help permet d'obtenir de l'aide sur les
fonctions, mais aussi sur les applets de commande, les
fournisseurs et les scripts. Pour obtenir de l'aide sur une
fonction, tapez Get-Help suivi du nom de fonction.
Par exemple, pour obtenir de l'aide sur la fonction MyDisks, tapez :
get-help MyDisks
Vous pouvez écrire de l'aide pour une fonction grâce à l'une ou
l'autre des deux méthodes suivantes :
-- Aide basée sur des commentaires pour les fonctions
Crée une rubrique d'aide en utilisant 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 ou à la fin du corps de la fonction ou sur
les lignes qui précèdent le mot clé de fonction. Pour plus
d'informations sur l'aide basée sur des commentaires, consultez
about_Comment_Based_Help.
-- Aide XML pour les fonctions
Crée une rubrique d'aide XML du type généralement créé pour
les applets de commande. L'aide 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é de commentaires d'aide .ExternalHelp. Pour plus
d'informations sur le mot clé ExternalHelp, consultez
about_Comment_Based_Help. Pour plus d'informations sur l'aide XML,
consultez " How to Write Cmdlet Help " (page éventuellement en
anglais) dans MSDN.
VOIR AUSSI
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (fournisseur)