about_Functions
Mis à jour: mai 2014
S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
RUBRIQUE
about_Functions
DESCRIPTION COURTE
Explique comment créer et utiliser des fonctions dans Windows PowerShell®.
DESCRIPTION DÉTAILLÉE
Une fonction est une liste d’instructions Windows PowerShell portant le nom que vous lui affectez. Quand 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 ceci :
function Get-PowerShellProcess {Get-Process PowerShell}
ou aussi complexe qu’une applet de commande ou qu’un programme d’application.
Comme les applets de commande, les fonctions peuvent avoir des paramètres. Les paramètres peuvent être des paramètres nommés, positionnels, de commutateur ou dynamiques. Les paramètres des fonctions 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 à d’autres applets de commande.
La liste d’instructions de la fonction peut contenir différents types de listes d’instruction avec les mots clés Begin, Process et End. Ces listes d’instructions gèrent différemment les entrées provenant du pipeline.
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 qui fonctionne exactement comme une applet de commande sans utiliser de programmation en C#. Pour plus d’informations, consultez about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511).
Syntaxe
Voici la syntaxe d’une fonction :
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Une fonction comprend les éléments suivants :
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
Pour plus d’informations sur le mot clé Dynamicparam et les paramètres dynamiques dans les fonctions, consultez about_Functions_Advanced_Parameters.
Fonctions simples
Les fonctions ne doivent pas nécessairement ê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 Windows PowerShell avec l’option Exécuter en tant qu’administrateur (RunAs).
function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}
Pour utiliser la fonction, tapez : Start-PSAdmin
Pour ajouter des instructions à la fonction, utilisez un point-virgule (;) pour séparer les instructions ou tapez chaque instruction sur une ligne distincte.
Par exemple, la fonction suivante recherche tous les fichiers .jpg dans les 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 {$_.LastWriteTime -gt $Start}
}
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.
Noms des fonctions
Vous pouvez affecter n’importe quel nom à une fonction, mais les fonctions que vous partagez avec d’autres utilisateurs doivent suivre les règles d’affectation de noms qui ont été établies pour toutes les commande Windows PowerShell.
Les noms des fonctions doivent être constitués d’une paire verbe-substantif, où le verbe identifie l’action effectuée par la fonction et où le nom identifie l’élément sur lequel l’applet de commande effectue son action.
Les fonctions doivent utiliser les verbes standard qui ont été approuvés pour toutes les commandes Windows PowerShell. Ces verbes nous aident à conserver les noms de nos commandes simples, cohérents et facile à comprendre par les utilisateurs.
Pour plus d’informations sur les verbes Windows PowerShell standard, consultez « Verbes des applets de commande » sur MSDN, à l’adresse https://go.microsoft.com/fwlink/?LinkID=160773.
FONCTIONS AVEC PARAMÈTRES
Vous pouvez utiliser des paramètres avec les fonctions, y compris 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 (https://go.microsoft.com/fwlink/?LinkID=135173).
Paramètres nommés
Vous pouvez définir un nombre quelconque 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 entre les accolades en utilisant le mot clé Param, comme indiqué dans l’exemple de syntaxe suivante :
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
Vous pouvez aussi définir des paramètres en dehors des accolades sans le mot clé Param, comme indiqué dans l’exemple de syntaxe suivante :
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
Il n’existe aucune différence entre ces deux méthodes. Utilisez la méthode que vous préférez.
Quand 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 paramètre $size. La fonction affiche tous les fichiers dont la taille est inférieure à la valeur du paramètre $size et elle exclut les répertoires :
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Dans la fonction, vous pouvez utiliser la variable $size, qui est le nom défini pour le paramètre.
Pour utiliser cette fonction, tapez la commande suivante :
C:\PS> function 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 que la commande qui nomme le paramètre Size :
C:\PS> function 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 le montre la variante suivante de l’exemple Get-SmallFiles :
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
Si vous tapez « Get-SmallFiles » sans valeur, la fonction affecte la valeur 100 à $size. Si vous fournissez une valeur, la fonction utilise cette valeur.
Si vous le souhaitez, vous pouvez fournir une chaîne d’aide succincte qui décrit la valeur par défaut du paramètre, en ajoutant l’attribut PSDefaultValue à la description du 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 de la fonction Get-SmallFiles, ajoutez l’attribut PSDefaultValue comme indiqué dans l’exemple suivant.
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$size = 100
)
Pour plus d’informations sur la classe d’attributs PSDefaultValue, consultez Membres de PSDefaultValueAttribute sur MSDN. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx
Paramètres positionnels
Un paramètre positionnel est un paramètre sans nom de paramètre. Windows PowerShell utilise l’ordre des valeurs des paramètres pour associer chaque valeur de paramètre à un paramètre de la fonction.
Quand 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 variable de type tableau $args. La valeur qui suit le nom de la fonction est affectée à la première position du tableau $args, qui est $args[0].
La fonction Get-Extension suivante ajoute l’extension de nom de fichier .txt à un nom de fichier que vous fournissez :
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
PARAMÈTRES DE COMMUTATEUR
Un commutateur est un paramètre qui ne requiert pas de valeur. Au lieu de cela, vous tapez le nom de la fonction suivi du nom du paramètre booléen.
Pour définir un paramètre booléen, spécifiez le type [switch] devant le nom du paramètre, comme le montre l’exemple suivant :
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
Quand vous tapez le paramètre booléen On après le nom de la fonction, la fonction affiche « Switch on ». Sans le paramètre booléen, elle affiche « Switch off ».
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
Vous pouvez également affecter une valeur booléenne à un commutateur quand vous exécutez la fonction, comme le montre l’exemple suivant :
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
Utilisation de la projection pour représenter les paramètres d’une commande
Vous pouvez utiliser la projection pour représenter les paramètres d'une commande. Cette fonctionnalité a été 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 la commande, ni de modifier la fonction quand les paramètres de la commande changent.
L’exemple de fonction suivant appelle l’applet de commande Get-Command. 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 quand vous appelez la fonction Get-MyCommand. Les paramètres et les valeurs des paramètres sont passés à la commande à l’aide de @Args.
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
La fonction @Args utilise le paramètre automatique $Args, qui représente les paramètres et les valeurs non déclarés de l’applet de commande provenant des arguments restants.
Pour plus d’informations sur la projection, consultez about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720).
Redirection d’objets vers des fonctions
Toute fonction peut recevoir des entrées du pipeline. Vous pouvez contrôler la façon dont une fonction traite les entrée du pipeline en utilisant les mots clés Begin, Process et End. L’exemple de syntaxe suivant montre les trois mots clés :
function <name> {
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
La liste d’instructions Begin s’exécute une seule fois, au début de la fonction.
La liste d’instruction Process s’exécute une fois pour chaque objet du pipeline. Pendant l’exécution du bloc Process, chaque objet du pipeline est affecté à la variable automatique $_, un objet du pipeline à la fois.
Une fois que la fonction a reçu tous les objets du pipeline, la liste d’instructions End s’exécute une seule 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. La fonction affiche des exemples du pipeline :
function Get-Pipeline
{
process {"The value is: $_"}
}
Pour illustrer cette fonction, entrez une liste de nombres séparés par des virgules, comme indiqué dans l’exemple suivant :
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
Quand vous utilisez une fonction dans un pipeline, les objets placés dans le pipeline et passés à la fonction sont affectés à la variable automatique $input. La fonction exécute les instructions avec le mot clé Begin avant que les objets arrivent 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 montre la variable automatique $input avec les mots clés Begin et End.
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
Si cette fonction est exécutée en utilisant le pipeline, elle affiche les résultats suivants :
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Quand l’instruction Begin s’exécute, la fonction n’a pas d’entrée provenant du pipeline. L’instruction End s’exécute une fois que la fonction a les valeurs.
Si la fonction a un mot clé Process, la fonction lit les données dans $input. L’exemple suivant a une liste d’instructions Process :
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
Dans cet exemple, chaque objet du pipeline qui est transmis à la fonction est envoyé à la liste d’instructions Process. Les instructions Process s’exécutent sur chaque objet, un objet à la fois. La variable automatique $input est vide quand la fonction atteint le mot clé End.
C:\PS> 1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Filtres
Un filtre est un type de fonction qui s’exécute sur chaque objet du pipeline. Un filtre est similaire à une fonction avec toutes ses instructions dans un bloc Process.
La syntaxe d’un filtre est la suivante :
filter [<scope:>]<name> {<statement list>}
Le filtre suivant prend des entrées de journal provenant du pipeline, puis affiche la totalité de l’entrée ou seulement la partie message de l’entrée :
filter Get-ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Étendue de la fonction
Une fonction existe dans l’étendue dans laquelle elle a été 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 à l’invite de commandes.
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 {$_.DependentServices} }
Quand une fonction est dans l’étendue globale, vous pouvez utiliser la fonction dans les scripts, dans les fonctions et sur la ligne de commande.
Fonctions créent normalement une étendue. Les éléments créés dans une fonction, comme des variables, existent seulement dans l’étendue de la fonction.
Pour plus d’informations sur les étendues dans Windows PowerShell, consultez about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260).
Recherche et gestion des fonctions à l’aide du lecteur function:.
Toutes les fonctions et tous les filtres de Windows PowerShell sont automatiquement stockés dans le lecteur function:. Ce lecteur est exposé par le fournisseur function de Windows PowerShell.
Quand vous faites référence au lecteur function:, tapez un signe deux-points après function, comme vous le feriez pour faire référence au lecteur C ou D d’un ordinateur.
La commande suivante affiche toutes les fonctions de la session en cours de Windows PowerShell:
Get-ChildItem function:
Les commandes de la fonction sont stockées sous forme de bloc de script dans la propriété definition de la fonction. Par exemple, pour afficher les commandes dans la fonction Help fournie avec Windows PowerShell, tapez :
(Get-ChildItem function:help).Definition
Pour plus d’informations sur le lecteur function:, consultez la rubrique d’aide pour le fournisseur function. Tapez « Get-Help Function » ou consultez-la dans la bibliothèque TechNet à l’adresse https://go.microsoft.com/fwlink/?LinkID=113436.
Réutilisation de fonctions dans des nouvelles sessions
Quand vous tapez une fonction à l’invite de commandes de Windows PowerShell, la fonction devient partie intégrante de la session active. Elle est disponible jusqu’à ce que la session se termine.
Pour utiliser votre fonction dans toutes les sessions Windows PowerShell, ajoutez la fonction à votre profil Windows PowerShell. Pour plus d’informations sur les profils, consultez about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729).
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 l’aide pour des fonctions
L’applet de commande Get-Help obtient l’aide 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 suivi du nom de la fonction.
Par exemple, pour obtenir de l’aide sur la fonction Get-MyDisks, tapez :
Get-Help Get-MyDisks
Vous pouvez écrire l’aide pour une fonction selon les deux méthodes suivantes :
Aide basée sur des commentaires pour les fonctions
Créez une rubrique d’aide en utilisant des mots clés spéciaux dans les commentaires. Pour créer une 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é function. Pour plus d’informations sur l’aide basée sur des commentaires, consultez about_Comment_Based_Help.
Aide XML pour les fonctions
Créez une rubrique d’aide XML, comme celles qui sont généralement créées pour les applets de commande. Une aide XML est requise si vous devez traduire les rubriques d’aide dans plusieurs langues.
Pour associer la fonction à la rubrique d’aide XML, utilisez le mot clé .ExternalHelp de l’aide basée sur des commentaires. Sans ce mot clé, Get-Help ne peut pas trouver la rubrique d’aide de la fonction et les appels à Get-Help pour la fonction retournent seulement une aide générée automatiquement.
Pour plus d'informations sur le mot clé ExternalHelp, consultez about_Comment_Based_Help. Pour plus d’informations sur l’aide XML, voir « Comment écrire l’aide d’une applet de commande » dans MSDN.
VOIR AUSSI
about_Automatic_Variables
about_Comment_Based_Help
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
Fonction (fournisseur)