about_Functions

Article
06/21/2023

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 :

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, switch 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 transmises à d’autres fonctions ou applets de commande. Vous pouvez également spécifier une valeur de retour à l’aide de la return mot clé. Le return mot clé n’affecte pas ou ne supprime pas les 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 listes d’instructions gèrent différemment l’entrée du pipeline.

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 la C# programmation. Pour plus d’informations, consultez about_Functions_Advanced.

Important

Dans les fichiers de script et les modules basés sur un script, les fonctions doivent être définies avant de pouvoir ê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 comprend les éléments suivants :

Un Function mot clé
Étendue (facultatif)
Nom que vous sélectionnez
Nombre quelconque de paramètres nommés (facultatif)
Une ou plusieurs commandes PowerShell placées dans des accolades {}

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

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 .jpg fichiers 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-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 versions ultérieures de cette rubrique.

Noms des fonctions

Vous pouvez attribuer n’importe quel nom à une fonction, mais les fonctions que vous partagez avec d’autres doivent suivre les règles de nommage qui ont été é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 qui ont été approuvés pour toutes les commandes PowerShell. Ces verbes nous aident à garder nos noms de commandes simples, cohérents et faciles à comprendre pour les utilisateurs.

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

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’y a 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 plus petits que la $Size valeur du paramètre, et elle 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
  )
}

Pour plus d’informations sur la classe d’attribut PSDefaultValue , consultez 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 des valeurs 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 attribuées à la variable de $args 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 .txt 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 de commutateur.

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 affiche « Activer ». Sans le paramètre switch, 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 Splatting pour représenter les paramètres de commande

Vous pouvez utiliser la platetage 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, ni 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 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 de @Args.

Get-MyCommand -Name Get-ChildItem

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

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

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

Canalisation d’objets vers des fonctions

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 à partir du pipeline à l’aide Beginde mots clés , Processet End . 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 Beginbloc , Process ou End , 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 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é , ou n’est BeginEnd utilisé, toutes les instructions sont traitées comme une liste d’instructionsEnd. Process

La fonction suivante utilise le Process mot clé. La fonction affiche des exemples à partir 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 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 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 les Begin mots clés et End .

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 dans $input est supprimé de $input et 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 liste d’instructions Process . 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 d’é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 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 l’utiliser 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 tous les 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 Function, comme vous le feriez lorsque vous référencez le C lecteur ou D 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 fonction . Tapez Get-Help Function.

Réutilisation de fonctions dans de nouvelles sessions

Lorsque vous tapez une fonction à l’invite de commandes PowerShell, la fonction fait partie de la session active. Il 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 .ps1 nom de fichier.

Écriture d’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 suivi du 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

Create une rubrique d’aide à l’aide de mots clés spéciaux dans les commentaires. Pour créer une aide basée sur les 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 la fonction mot clé. Pour plus d’informations sur l’aide basée sur les commentaires, consultez about_Comment_Based_Help.
aide XML-Based pour Functions

Create une rubrique d’aide xml, telle que le type qui est généralement créé pour les applets de commande. Une aide xml est requise si vous localisez des rubriques d’aide dans plusieurs langues.

Pour associer la fonction à la rubrique d’aide XML, utilisez la .ExternalHelp mot clé d’aide basée sur les commentaires. Sans cette mot clé, Get-Help impossible de trouver la rubrique d’aide de la fonction et les appels à Get-Help pour 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 xml, consultez Guide pratique pour écrire l’aide sur les applets de commande.

Share via