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 ont 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 avez tapées à l’invite de commandes.

Les fonctions peuvent être aussi simples que :

function Get-PowerShellProcess { Get-Process PowerShell }

Une fonction peut également être aussi complexe qu’une applet de commande ou un programme d’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 supprime 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, Processet End. Ces instructions répertorient les entrées du pipeline différemment.

Un filtre est un type spécial de fonction qui utilise le Filter mot clé.

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 qu’elles puissent être appelées.

Syntax

Voici la syntaxe d’une fonction :

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

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

Une fonction inclut les éléments suivants :

• Mot Function clé
• Étendue (facultative)
• Nom que vous sélectionnez
• 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.

Fonctions simples

Les fonctions ne doivent pas être compliquées à ê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 verbe-nom dans laquelle 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 à garder nos noms de commandes simples, cohérents et faciles à comprendre.

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

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 illustré 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 mot Param clé, comme indiqué dans l’exemple de syntaxe suivant :

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Voici 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 qui sont inférieurs à 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 illustré 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
  )
}

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 de paramètre positionnelles 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 de nom de .txt 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 de commutateur.

Pour définir un paramètre de commutateur, spécifiez le type avant le nom [switch] 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 paramètre de commutateur après le On nom de la fonction, la fonction affiche « Activer ». Sans le paramètre de commutateur, il affiche « Désactiver ».

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 plateforme Splatting 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 de Get-Command 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 du Get-Command moment où 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 des paramètres et des valeurs d’applet de commande non déclarés à partir d’arguments restants.

Pour plus d’informations sur la plaque, consultez about_Splatting.

Piping Objects to Functions

N’importe quelle fonction peut prendre une entrée à partir du pipeline. Vous pouvez contrôler la façon dont une fonction traite les entrées du pipeline à l’aide Beginde mots clés et End de mots Processclés. L’exemple de syntaxe suivant montre les trois mots clés :

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

La Begin liste d’instructions s’exécute une seule fois, au début de la fonction.

Important

Si votre fonction définit un ou ProcessEnd un Beginbloc, tout votre code doit résider à l’intérieur de ces blocs. Aucun code n’est reconnu en dehors des blocs si l’un des blocs est défini.

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

Une fois que la fonction reçoit tous les objets du pipeline, la End liste d’instructions s’exécute une seule fois. Si aucun , ou mot clé n’est Beginutilisé, toutes les instructions sont traitées comme une liste d’instructionsEnd.EndProcess

La fonction suivante utilise le Process mot clé. 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 illustré dans l’exemple suivant :

1,2,4 | Get-Pipeline

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

Lorsque vous utilisez une fonction dans un pipeline, les objets redirigés vers la fonction sont affectés à la $input variable automatique. La fonction exécute des instructions avec le Begin mot clé avant que tous les objets 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

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 prend les entrées de journal 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 { $_ }
}

É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 au sein 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-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 normalement 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 sur l’étendue dans PowerShell, 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 fonctions PowerShell.

Lorsque vous faites référence au Function: lecteur, tapez un signe deux-points après la fonction, comme vous le feriez lors du référencement de l’ordinateur C ou D du 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 dans 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. Elle est disponible jusqu’à la fin de la session.

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 de l’aide pour les fonctions

L’applet Get-Help de commande obtient de 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 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 Comment-Based pour Functions

  Créez une rubrique d’aide à l’aide de 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é de fonction. Pour plus d’informations sur l’aide basée sur les commentaires, consultez about_Comment_Based_Help.

• aide XML-Based 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 impossible de trouver 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 de 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