Fonctions PowerShell

admin
Cette entrée est la partie 12 sur 13 de la série Apprendre PowerShell

Dans cet épisode de la série Apprendre PowerShell, nous allons examiner les fonctions PowerShell. Dans le dernier épisode, nous avons abordé les scripts PowerShell où nous avons commencé à créer des solutions et à résoudre des problèmes à l’aide de PowerShell. Les scripts PowerShell sont excellents et de nombreuses personnes passent beaucoup de temps à ce stade de leur apprentissage de PowerShell. Les scripts vous permettent de garder les choses assez simples, et peuvent vous aider à automatiser rapidement des tâches. Au fur et à mesure que vous vous améliorez et que vous commencez à écrire davantage de PowerShell, vous allez devoir vous tourner vers la création de fonctions PowerShell !

Vidéo

Si vous préférez le format vidéo à la documentation écrite, j’aborde ce sujet dans la vidéo TechThoughts suivante :

Quand vous devriez écrire une fonction PowerShell

En fin de compte, un script PowerShell est un ensemble de code qui exécute une tâche. C’est aussi ce que fait une fonction PowerShell ! Alors, pourquoi choisir d’écrire une fonction plutôt qu’un script ? Nous allons examiner quelques raisons ci-dessous. D’une manière générale, un script est quelque chose qui vous est destiné. Lorsque vous voudrez commencer à partager votre code, ou à le faire utiliser par vos coéquipiers, vous voudrez commencer à utiliser certaines des capacités offertes par les fonctions. Il n’y a pas de limite ferme. Pour une tâche rapide qui sera exécutée une seule fois sur votre poste de travail, un script peut être utile. Si vous écrivez un peu de PowerShell que d’autres pourraient utiliser, ou que vous pourriez utiliser plus d’une fois, une fonction servira probablement mieux.

  • Uniquement destiné – une fonction est généralement utilisée pour effectuer une tâche étroite et « faire une chose, et la faire bien ». Cela rend les fonctions hautement réutilisables. Si vous écrivez une fonction de journalisation par exemple, vous pouvez ensuite utiliser cette fonction de journalisation PowerShell avec d’autres fonctions ou scripts.
  • Aide – les fonctions prennent en charge les commentaires basés sur l’aide. Cela permet à vos utilisateurs de faire des choses comme taper Get-Help et de comprendre comment utiliser votre fonction.
  • Paramètres – le support des déclarations et du contrôle des paramètres simples et avancés permet à votre fonction d’être dynamique et de prendre diverses formes d’entrée utilisateur.
  • Testable – les fonctions peuvent être testées et simulées, ce qui améliore grandement la qualité du code.

Anatomie d’une fonction PowerShell

Voici la disposition et l’ordre de base d’une fonction PowerShell. Nous allons plonger dans chacune de ces sections ci-dessous et les explorer en détail. 

# function help - (optional but strongly encouraged)# function name# CmdletBinding - (optional)# parameters - (optional)# function logic (optional Begin / Process / End)# return - (optional)function Verb-Noun { param ( ) begin { } process { } end { }}

Aide de la fonction

Lorsque vous incluez l’aide en haut de votre fonction, elle sera affichée lorsque Get-Help est exécuté contre votre fonction. Il s’agit d’une capacité puissante lorsque d’autres personnes explorent votre code. Prendre le temps d’étoffer un bon Synopsis et une bonne Description combinés à des exemples solides aidera les autres à comprendre à quoi sert votre fonction et comment l’utiliser.

Tous les champs d’aide sont facultatifs et vous pouvez les ajouter ou les supprimer à votre guise. Je vous recommande d’inclure au minimum les champs ci-dessous.

<#.SYNOPSIS Short description.DESCRIPTION Long description.EXAMPLE C:\PS> Example of how to use this cmdlet.EXAMPLE C:\PS> Another example of how to use this cmdlet.PARAMETER InputObject Specifies the object to be processed. You can also pipe the objects to this command..OUTPUTS Output from this cmdlet (if any).NOTES General notes.COMPONENT The component this cmdlet belongs to#>

CmdletBinding 





Lorsque vous écrivez une excellente fonction et que vous lui donnez un nom comme Get-AllFileInformation, elle ressemble et agira comme un cmdlet. Mais il s’agit d’une distinction importante : une fonction PowerShell n’est pas un cmdlet. Les cmdlets sont écrits et compilés en C# et votre fonction PowerShell est écrite en PowerShell.


CmdletBinding est un attribut des fonctions qui active des capacités qui les font fonctionner davantage comme des cmdlets compilés. L’ajouter en haut de votre fonction lui donnera de nombreuses capacités supplémentaires telles que :


    

  •  Write-Verbose – permet aux utilisateurs d’utiliser le commutateur -Verbose pour voir ce que votre fonction fait pendant qu’elle le fait.
    • 

  •  ShouldProcess – si votre fonction apporte un changement à un système à haut risque, vous voudrez peut-être que l’utilisateur confirme l’action. 
    • 

  •  PositionalBinding – permet à votre fonction d’être exécutée sans fournir explicitement chaque nom de paramètre. Les valeurs peuvent être déduites par l’ordre dans lequel elles sont fournies à votre fonction
    • 



paramètres 




param ( $City, $Units = 'USCS', $Language = 'en', $Short)






Les paramètres servent à fournir à l’utilisateur un moyen d’interagir dynamiquement avec votre fonction. Vous pouvez prendre diverses formes d’entrée et effectuer une grande variété de contrôles et de validations pour vous assurer que vous obtenez le bon type d’information.


Vous pouvez rester très basique et ne déclarer que les noms de vos paramètres. Alternativement, vous pouvez devenir très spécifique sur ce qui est requis pour vos paramètres :


    

  • Si le paramètre est obligatoire
    • 

  • La position d’un paramètre (l’ordre)
    • 

  • Le type de paramètre (string/int/bool/etc)
    • 

  • Définir des valeurs par défaut
    • 

  • Validation d’entrée
    • 

  • Ensembles de paramètres
    • 

  • Bien plus
    • 



Ce post ne peut pas couvrir toutes les configurations de paramètres possibles. Même après des années d’écriture de PowerShell, je trouve difficile de mémoriser tous les réglages de paramètres et la syntaxe. Sachez que les déclarations de paramètres sont votre façon de prendre des entrées dans votre fonction. Vous pouvez leur fournir beaucoup de détails et de contrôles, ou les garder simples en fonction de vos besoins. Mettez en signet les liens vers les paramètres au bas de cet article. Aujourd’hui encore, je les visite fréquemment !


Début Processus Fin 


Ces trois mots-clés sont des phases que vous pouvez déclarer au sein de votre fonction.


    

  • Début initialisera certaines étapes au départ
    • 

  • Processus traitera chaque objet tel qu’il est reçu
    • 

  • Fin peut effectuer un nettoyage.
    • 



Ceci est particulièrement utile si vous voulez que votre votre fonction prenne en charge le traitement des entrées du pipeline.


Cela peut être difficile à saisir en théorie, voici donc un exemple qui démontre son utilisation.




function Get-PipelineBeginEnd { param ( $SomeInput ) begin { "Begin: The input is $SomeInput" } process { "The value is: $_" } end { "End: The input is $SomeInput" }}#Get-PipelineBeginEnd1, 2, 3 | Get-PipelineBeginEnd -SomeInput 'Test'




Lorsque vous exécutez le code ci-dessus, notez que Begin s’exécute une fois, tout comme End. Process est exécuté pour chaque élément qui lui est passé et Process a accès à l’objet actuel dans le pipeline.


Logique de la fonction 


La logique contenue à l’intérieur d’une fonction PowerShell n’est pas différente de celle d’un script. C’est là que vous allez écrire la logique de base qui exécute la tâche à laquelle votre fonction est destinée. Cela a été abordé dans les épisodes 1 à 10 de ce cours. Vous pouvez également voir un exemple complet en direct dans l’épisode Scripts PowerShell.


Retour de fonction 




Toutes les fonctions ne renvoient pas quelque chose lors de leur exécution. Si votre fonction doit retourner quelque chose, vous pouvez optionnellement utiliser return. Gardez à l’esprit que lorsque vous utilisez return, toutes les autres actions de la fonction s’arrêteront et la fonction se terminera.




function Get-Total { param ( $Number1, $Number2 ) $total = $Number1 + $Number2 return $total}Get-Total -Number1 2 -Number2 2




Dans l’exemple ci-dessus, cette fonction simple contient deux paramètres de type integer. La logique de la fonction additionne les deux nombres et renvoie le nombre entier à l’utilisateur.


Votre première fonction PowerShell 


Regardez la fonction PowerShell ci-dessous. Notez que la mise en page adhère à ce que nous avons précédemment couvert. Notez également que la section d’aide fournit une grande quantité de détails quant au but et à l’utilisation de la fonction.




<#.SYNOPSIS Returns your public IP address..DESCRIPTION Queries the ipify Public IP Address API and returns your public IP..EXAMPLE Get-PublicIP Returns the public IP..OUTPUTS System.String.NOTES https://github.com/rdegges/ipify-api#>function Get-PublicIP { $uri = 'https://api.ipify.org' try { $invokeRestMethodSplat = @{ Uri = $uri ErrorAction = 'Stop' } $publicIP = Invoke-RestMethod @invokeRestMethodSplat } catch { Write-Error $_ } return $publicIP}#Get-PublicIP




Comme la logique réelle de cette fonction est assez simple, il pourrait être tentant de la laisser comme un script. Notez cependant que cela fait une chose spécifique, et le fait bien. Vous pourriez maintenant incorporer cette fonction dans d’autres logiques avancées, au lieu de devoir référencer ou importer un script. D’autres utilisateurs dans votre environnement pourraient également commencer à engager cette fonction une fois qu’ils se sont familiarisés avec elle.


Portée de la fonction 


Comme la plupart des langages, PowerShell a des règles de portée pour les variables. Lorsqu’une variable se trouve dans une fonction, vous ne pourrez plus « voir » sa valeur. Voici un exemple de ce comportement :




function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2




La fonction se comporte comme prévu et multipliera correctement un nombre par deux. Dans votre console cependant, essayez de voir quelle est la valeur de $total. Vous n’y parviendrez pas. Cela est dû au fait que $total est scopé à la fonction, et non à votre session de console active.


Cela peut être déroutant pour les personnes novices en PowerShell et peut rendre l’écriture de fonctions plus difficile. Il existe quelques stratégies pour faire face à cela.


Vous pourriez écrire la majorité de votre logique dans un format de type script, en testant les variables au fur et à mesure. Une fois que vous êtes sûr que la logique fonctionne comme prévu, vous pourriez alors envelopper la logique à l’intérieur d’une fonction.


Alternativement, vous pouvez utiliser Write-Host, Write-Output, ou mieux encore Write-Debug pour voir ce qui se passe avec vos variables à l’intérieur de votre fonction !




function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 Write-Debug $total return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2 -Debug




Notez qu’avec le commutateur de débogage, nous avons accès à la valeur à l’intérieur de $total pour nous assurer que notre logique fait ce que nous voulons.


Exemple de clôture 


Voici un exemple de clôture plus important de deux fonctions PowerShell qui vous permettront de surfer sur le site populaire reddit en utilisant PowerShell !


Visitez le lien GitHub gist ci-dessous pour accéder au code et le charger dans votre console.


https://gist.github.com/techthoughts2/cd2b720c9b291510cbd643e6ca73e05f


Alors que vous explorez ces fonctions, essayez de répondre aux questions suivantes :


    

  • Des deux fonctions, laquelle est la fonction principale ? 
    • 

  • S’agit-il de fonctions standard ou avancées ? 
    • 

  • Quelle fonction va prendre en charge l’entrée pipeline ?
    • 



 Additional Reading 


    

  • Functions
    • 

  • Parameters
    • 

  • Functions Advanced
    • 

  • Functions Advanced Parameters
    • 

  • PowerShell Approved Verbs
    • 

  • CmdletBindingAttribute
    • 



Series Navigation << PowerShell ScriptsManage Cloud with PowerShell >>