• 2/27/2019
  • 12 minutes pour lire
    • S
    • s

Courte description

Explique comment créer et utiliser des fonctions dans PowerShell.

description longue

Une fonction est une liste d’instructions PowerShell qui a un nom que youassign. Lorsque vous exécutez une fonction, vous tapez le nom de la fonction. Les statementsdans la liste s’exécutent comme si vous les aviez tapés à l’invite de commande.,

les Fonctions peuvent être aussi simple que:

function Get-PowerShellProcess { Get-Process PowerShell }

Une fonction peut être aussi complexe que l’applet de commande ou d’un programme d’application.

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

Les fonctions peuvent renvoyer des valeurs qui peuvent être affichées, affectées à des variables ou passées à d’autres fonctions ou applets de commande. Vous pouvez également spécifier une valeur de retour en utilisant le mot-clé return., Le mot-cléreturn n’affecte ni ne supprime les autres sorties renvoyées par votre fonction. Cependant, le mot-clé return quitte la fonction à cette ligne. Pour plus d’informations, voir about_Return.

la liste d’instructions de la fonction peut contenir différents types de listes d’instructions avec les mots-clésBegin,ProcessetEnd. Ces instructions listshandle entrée 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 qui fonctionne comme une applet de commande sans utiliser la programmation C#. Pour plus d’informations,voir about_Functions_Advanced.,

Syntaxe

La syntaxe est la suivante pour une fonction:

Une fonction comprend les éléments suivants:

  • Function mots clés
  • Un champ (facultatif)
  • Un nom que vous sélectionnez
  • n’Importe quel nombre de paramètres nommés (facultatif)
  • Une ou plusieurs commandes PowerShell entre accolades {}

Pour plus d’informations sur le Dynamicparam mots clés et les paramètres de la dynamique infunctions, seeabout_Functions_Advanced_Parameters.,

Fonctions

les Fonctions n’ont pas à être compliqué pour être utile. 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 asAdministrator.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Pour utiliser la fonction, type: Start-PSAdmin

Pour ajouter la fonction, le type de chaque énoncé sur une ligne distincte, oruse un point-virgule ; pour séparer les déclarations.,

par exemple, la fonction suivante trouve tous les fichiers .jpg dans les répertoires de l’utilisateur actuel qui ont été modifiés après la date de début.

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 tard dans cette rubrique.

noms de fonction

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 être constitués d’une paire verbe-nom dans laquelle le verbidentifie l’action que la fonction effectue 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 les commandes allPowerShell. Ces verbes nous aident à garder nos noms de commandesimple, cohérent et facile à comprendre pour les utilisateurs.

pour plus d’informations sur les verbes PowerShell standard, voir verbes approuvés dans les documents Microsoft.,

fonctions avec paramètres

Vous pouvez utiliser des paramètres avec des fonctions, y compris des paramètres nommés, des paramètres positionalparameters, des paramètres de commutation et des paramètres dynamiques. Pour plus d’informations sur les paramètres dynamiques dans les fonctions, voirabout_functions_advanced_parameters.

Paramètres Nommés

Vous pouvez définir un nombre quelconque de paramètres nommés. Vous pouvez inclure une valeur par defautpour 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 en utilisant le mot-clé Param, comme indiqué dans l’exemple de syntaxe suivant:

function <name> { param ($parameter1$parameter2]) <statement list>}

Vous pouvez également définir des paramètres en dehors des accolades sans le mot-clé Param, comme div id= »ac557b2035″>

Voici un exemple de cette syntaxe alternative.

Function Add-Numbers($one, $two) { $one + $two}

bien que la première méthode soit préférée, il n’y a pas de différence entre ces deux méthodes.,

Lorsque vous exécutez la fonction, la valeur d’un paramètre est affecté toa variable qui contient le nom du paramètre. La valeur de cette variable peut êtreutilisé 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 plus petits que la valeur du paramètre$Size, 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 variable$Size, qui est le nom défini pour le paramètre.

Pour utiliser cette fonction, tapez la commande suivante:

Get-SmallFiles -Size 50

Vous pouvez aussi 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 valueaprès le nom du paramètre, comme indiqué dans la variation suivante deGet-SmallFiles exemple:

function Get-SmallFiles ($Size = 100) { Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer }}

Si vous tapez Get-SmallFiles sans valeur, la fonction attribue 100 à$size. Si vous fournissez une valeur, la fonction utilise cette valeur.,

En Option, vous pouvez fournir une brève chaîne d’aide qui décrit la valeur defaultvalue de votre paramètre, en ajoutant L’attribut PSDefaultValue à la description de votre paramètre et en spécifiant la propriété Help ofPSDefaultValue. Pour fournir une chaîne d’aide qui décrit la valeur par défaut(100) du paramètre Size dans la fonction Get-SmallFiles, ajoutez l’attribut thePSDefaultValue comme indiqué dans l’exemple suivant.

function Get-SmallFiles { param ( $Size = 100 )}

pour plus d’informations sur la classe d’attributs PSDefaultValue, consultez les membres de l’attribut PSDefaultValue.,

Paramètres Positionnels

Un paramètre de position est un paramètre sans un nom de paramètre. PowerShell utilise l’ordre des valeurs des paramètres 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 variable de tableau$args.La valeur qui suit le nom de la fonction est affectée à la première position dansle tableau $args, $args.,

Les Get-Extension fonction ajoute la balise .txt extension de nom de fichier afile nom que vous fournissez:

function Get-Extension { $name = $args + ".txt" $name}
Get-Extension myTextFile
myTextFile.txt

les Paramètres de Commutateur

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 de avant parametername, comme illustré dans l’exemple suivant:

function Switch-Item { param ($on) if ($on) { "Switch on" } else { "Switch off" }}

Lorsque vous tapez le On paramètre de commutateur après le nom de la fonction, la functiondisplays « allumer ». Sans le paramètre switch, il affiche « éteindre ».,

Switch-Item -on
Switch on
Switch-Item
Switch off

Vous pouvez également attribuer une valeur Booléenne à un commutateur lorsque vous exécutez la fonction, asshown 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 splatting pour représenter les paramètres d’une commande. Cette fonctionnalitéest introduit 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 commandeGet-Command. La commande utilise la balise@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 leGet-MyCommand fonction. Les paramètres et les valeurs des paramètres sont transmis à thecommand en utilisant @Args.,

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

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

pour plus d’informations sur le splatting, voir about_Splatting.

canaliser des objets vers des fonctions

N’importe quelle fonction peut prendre des entrées du pipeline. Vous pouvez contrôler comment une fonction traite les entrées du pipeline en utilisant les mots-clésBegin,Process etEnd., 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’instructionsBegin s’exécute une seule fois, au début de la fonction.

Important

Si votre fonction définit une balise Begin, Process ou End bloc, tous vos codemust résider à l’intérieur de ces blocs. Aucun code ne sera reconnu en dehors des blocs si l’un des blocs est défini.

la liste d’instructionsProcess s’exécute une fois pour chaque objet du pipeline.,Pendant l’exécution du bloc Process, chaque objet 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’instructionsEnds’exécute une fois. Si aucun Begin, Process ou End keywordsare utilisé, toutes les déclarations sont traitées comme un End déclaration de la liste.

la fonction suivante utilise le mot cléProcess., La fonction affiche les exemples du pipeline:

function Get-Pipeline{ process {"The value is: $_"}}

pour démontrer cette fonction, entrez une liste de Nombres séparés par des virgules, comme indiqué dans l’exemple suivant:

1,2,4 | Get-Pipeline
The value is: 1The value is: 2The value is: 4

lorsque vous utilisez une fonction dans un pipeline, les objets acheminés vers la fonction sont attribués à la variable automatique $input. La fonction exécute des instructions avec le mot-clé Begin avant que tous les objets proviennent du pipeline., La fonction s’exécute avec le mot-clé End après que tous les objets ont été reçus du pipeline.

L’exemple suivant montre la balise $input variable automatique avec Begin etEnd 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 en utilisant le pipeline, il affiche le followingresults:

1,2,4 | Get-PipelineBeginEnd
Begin: The input isEnd: The input is 1 2 4

Lors de la Begin instruction est exécutée, la fonction n’a pas de l’entrée de thepipeline., L’instruction End s’exécute après que la fonction a les valeurs.

Si la fonction a un Process mot clé, chaque objet dans $input est removedfrom $input et affecté à $_. L’exemple suivant est un Processdéclaration de la liste:

function Get-PipelineInput{ process {"Processing: $_ " } end {"End: The input is: $input" }}

Dans cet exemple, chaque objet est transmise à la fonction est envoyé à la baliseProcess déclaration de la liste. Les instructions Process s’exécutent sur chaque objet, unobject à la fois., La variable automatique$input est vide lorsque la fonction atteint le mot-cléEnd.

1,2,4 | Get-PipelineInput
Processing: 1Processing: 2Processing: 4End: The input is:

Pour plus d’informations, voir l’Aide d’agents Recenseurs

Filtres

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

la syntaxe d’un filtre est la suivante: 

filter <name> {<statement list>}

le filtre suivant prend les entrées de journal du pipeline, puis affiche l’entrée entière ou seulement la partie message de l’entrée: 

filter Get-ErrorLog ($message){ if ($message) { Out-Host -InputObject $_.Message } else { $_ }}

portée de la fonction

Une fonction existe dans

Si une fonction fait partie d’un script, la fonction est disponible pour les déclarations dans ce script. Par défaut, une fonction dans un script n’est pas disponible à l’invite de commande.

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-Object {$_.DependentServices}}

Lorsqu’une fonction est dans la portée globale, vous pouvez utiliser la fonction dans les scripts,fonctions, et à la ligne de commande.

Les fonctions créent normalement une portée. Les éléments créés dans une fonction, tels quevariables, n’existent que dans la portée de la fonction.

Pour plus d’informations sur la portée dans PowerShell, voirabout_scopes.,

recherche et gestion des fonctions à l’aide de la fonction: Drive

toutes les fonctions et filtres de PowerShell sont automatiquement stockés dans le lecteurFunction:. Ce lecteur est exposé par le fournisseur PowerShellFunction.

lorsque vous faites référence au lecteurFunction:, tapez deux points après la fonction, comme vous le feriez lorsque vous faites référence au lecteurC ouD d’un ordinateur.,

la commande suivante affiche toutes les fonctions de la session en cours de PowerShell: 

Get-ChildItem function:

Les commandes de la fonction sont stockées sous forme de 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 l’aide topicfor la Fonction de fournisseur. Type Get-Help Function.,

réutilisation de fonctions dans de nouvelles Sessions

lorsque vous tapez une fonction à L’invite de commande PowerShell, la fonction fait partie de la session en cours. Il est disponible jusqu’à thesession se termine.

pour utiliser votre fonction dans toutes les sessions PowerShell, ajoutez la fonction à votre profil PowerShell. Pour plus d’informations sur les profils,voir about_Profiles.

Vous pouvez également enregistrer votre fonction dans un fichier de script PowerShell. Tapez votrefunction dans un fichier texte, puis enregistrez le fichier avec l’extension .ps1 nom du fichier.,

aide à L’écriture des fonctions

l’applet de commandeGet-Help reçoit 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 le Get-MyDisks fonction, tapez:

Get-Help Get-MyDisks

Vous pouvez écrire à l’aide d’une fonction en utilisant l’une des deux followingmethods:

  • Commentaire de l’Aide pour les Fonctions

    Créer une rubrique d’aide en utilisant des mots-clés 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, voirabout_comment_based_help.

  • aide basée sur XML pour les fonctions

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

    pour associer la fonction à la rubrique d’aide basée sur XML, utilisez le mot-clé.ExternalHelp aide basée sur les commentaires., Sans ce mot-clé, Get-Helpne peut pas trouver la rubrique d’aide de la fonction et appelle Get-Help pour l’aide générée automatiquement uniquement par functionreturn.

    Pour plus d’informations sur le mot-clé ExternalHelp, consultez le documentabout_comment_based_help. Pour plus d’informations sur L’aide basée sur XML, voir comment écrire L’aide de L’applet de commande.

Voir aussi

about_Automatic_Variables