{{tag>dev powershell fonction}}


====== PowerShell : Fonctions et modules ======

Lorsqu'on produit du code on peut avoir envie ou besoin de :
  * Réutiliser une même séquence d' instructions plusieurs fois dans un script ;
  * Réutiliser des traitements dans un autre contexte.

===== Les fonctions =====

Une fonctions est un bloc de code réutilisable. Plutôt que d'écrire à différents endroits la même séquence d'instructions, il est préférable d'utiliser une fonction. Elle est définie une fois puis appelée autant de fois que nécessaire par le script. Cette factorisation du code est un élément clé pour la lisibilité, le débogage et la maintenance.

Ci-dessous la syntaxe de définition d'une fonction en PowerShell :

<code powershell>
# Définition d'une fonction nommée "Get-SecurityEvent()"
# Acceptant un paramètre de type entier
Function Get-SecurityEvent {
    Param( [int] $Last )
    Get-EventLog Security -Newest $Last
    
    # Valeurs à retourner (optionnel)
    Return($values)
}
</code>

La note [[dev/powershell/parametres|utilisation des paramètres]] détaille  l'usage de l'instruction **Param()**.

Pour appeler la fonction dans le script, utiliser la syntaxe :
<code powershell>
Get-SecurityEnvent -Last 30
</code>

<note>
On peut écrire l'aide associée à la fonction via les commentaires : voir la note [[dev/powershell/integration_aide|Powershell : aide basée sur les commentaires]]. 
</note>

Les fonctions dans les modules peuvent inclure une aide basée sur des commentaires, détectable à l’aide de la cmdlet **Get-Help**. Pour cela, vous devez inclure les informations d’aide dans chaque fonction.

===== Portée des variables =====

3 portées distinctes existent :

^ Global | Variables accessibles dans l'invite PowerShell et les processus fils. |
^ Script | Variables accessibles dans le script courant et les fonctions. Une variable de portée Script masque la valeur d'une variable de portée Global de même nom. |
^ Fonction | Limitée à la seule fonction. |



===== Les Modules =====

Les modules permettent de regrouper des fonctions et des variables afin de les partager entre plusieurs scripts ou de distribuer du code.

  * Les fichiers modules doivent avoir l'extension **psd1** ou **psm1**
  * Les modules présents dans **$env:PSModulePath** sont chargés automatiquement, les fonctions placées dans les modules peuvent être invoquées comme des applets ;
  * Les modules ne doivent pas être directement placés dans les répertoires déclarées par $env:PSModulePath. Il doivent avoir un sous-dossier portant le même nom que le fichier .psm1. 

<code powershell>
# Crée un répertoire pour le module
New-Item -ItemType Directory -Path .\Custom-Message

# Créer un fichier module
Set-Location .\Write-BlueMessage\
New-Item -ItemType File -Path .\Custom-Message.psm1
</code>

Ci-dessous le contenu du module

<code powershell Custom-Message.psm1>
# Fonction : Write-BlueMessage
# Description : Affiche un message de couleur bleue
# Args : Msg : Le message à  afficher

Function Write-BlueMessage{
        Param( [Parameter(Mandatory,helpMessage='Message to display')] [String] $Msg )

        Write-Host -ForegroundColor Blue "$Msg"
}
</code>

Une fois le module créé, il peut être chargé via la cmdlet **Import-Module**
<code powershell>
Import-Module .\Custom-Message.psm1

# Après import la fonction peut être invoquée
Write-BlueMessage -Msg "Hello World !!!"
</code>

===== Dot sourcing ======

Le **dot sourcing** est une méthode d'importation d'un autre script dans la portée actuelle.

Normalement les fonctions définies dans un fichier de script sont supprimées de la mémoire lorsque le script se termine. Avec le "dot sourcing" les fonctions restent en mémoire et vous pouvez les utiliser dans l'environnement courant : le script courant ou l’invite de commande de Windows PowerShell.

<code powershell>
# Chargement d'un script via dot sourcing
. .\aScriptFile.ps1
</code>

L’appel "dot sourcing" peut charger un fichier local ou une ressource réseau à l’aide d’un chemin UNC.

Par le passé, le dot sourcing était la seule méthode permettant de gérer un référentiel centralisé de fonctions réutilisables. A présent les **modules** constituent une méthode préférable et standardisée pour la gestion des fonctions entre plusieurs scripts.

===== Références =====

  * https://learn.microsoft.com/fr-fr/training/modules/use-functions-modules-windows-powershell-scripts/
  * https://learn.microsoft.com/fr-fr/powershell/module/microsoft.powershell.core/about/about_psmodulepath?view=powershell-5.1
  * https://learn.microsoft.com/en-us/powershell/scripting/developer/help/placing-comment-based-help-in-functions?view=powershell-5.1