Fonctions dans les scripts PowerShell

Une fonction PowerShell est un bloc de code conçu pour effectuer une tâche spécifique. Une fois qu'une fonction est créée et testée, elle peut être utilisée dans plusieurs scripts, réduisant ainsi l'effort de codage et le risque d'erreurs. Utiliser des fonctions bien nommées rend également les scripts plus faciles à lire et à maintenir. Et comme les fonctions peuvent retourner des valeurs qui peuvent être utilisées comme entrée pour d'autres fonctions ou blocs de code, elles facilitent la construction d'opérations complexes.

Cet article explique tout ce que vous devez savoir pour commencer à utiliser les fonctions PowerShell, y compris les meilleures pratiques importantes, et fournit même des conseils pour vous plonger dans des options plus avancées.

Commencer avec les fonctions PowerShell

Comment créer une fonction dans PowerShell

Pour définir une fonction, vous utilisez le mot-clé function. La syntaxe de base est la suivante : 

      function <Function-Name> { 

    <Code-Block> 
}
      

Le code à l'intérieur des accolades {} sera exécuté lorsque la fonction sera appelée.

Si vous le souhaitez, vous pouvez utiliser le mot-clé param pour spécifier les paramètres de la fonction, ainsi que les types de données, les valeurs par défaut, etc. Voici la syntaxe avec les paramètres ajoutés : 

      function <Function-Name> { 

    [param( 

        [<ParameterType>]$<ParameterName>, 

        [<ParameterType>]$<ParameterName2> = <DefaultValue> 

    )] 

    <Code-Block> 

}
      

Cet exemple de fonction PowerShell va multiplier deux nombres et afficher le résultat :

      function Multiply-Numbers { 

    param ( 

        [int]$Number1, 

        [int]$Number2 

    ) 

    $Result = $Number1 * $Number2 

    Write-Output "The multiplication value of $Number1 and $Number2 is $Result." 

}
      

Enregistrer une fonction

Pour sauvegarder une fonction, il suffit de la stocker dans un fichier script avec une extension.ps1.

Appel d'une fonction

Pour invoquer une fonction dans PowerShell, tapez le nom de la fonction suivi de tous les paramètres nommés nécessaires. Par exemple, voici comment appeler la fonction que nous avons définie ci-dessus :

      Multiply-Numbers -number1 6 -Number2 8 

      

Exécution d'une fonction dans le cadre de la session actuelle (Dot-Sourcing)

Le dot-sourcing vous permet d'exécuter un script PowerShell comme s'il était défini directement dans votre session de console actuelle. Pour utiliser le dot-sourcing, précédez le nom de la fonction d'un point et d'un espace (. ) lors de son appel.

Par exemple, supposons que nous avons défini la fonction suivante appelée Add-Numbers: 

      function Add-Numbers { 

    param ( 

        [int]$Number1, 

        [int]$Number2 

    ) 

    $Sum = $Number1 + $Number2 

    Write-Output "The sum of $Number1 and $Number2 is $Sum." 

}
      

Nous pouvons intégrer cette fonction dans notre session comme montré ici :

Nommer vos fonctions PowerShell

Pour tirer le meilleur parti des fonctions PowerShell, assurez-vous de suivre ces directives lors du nommage de vos fonctions.

Utilisez le format verbe-nom.

PowerShell fournit un ensemble de cmdlets préconstruits dont les noms suivent un format spécifique : un verbe qui spécifie l'action à effectuer, suivi d'un nom qui désigne l'objet sur lequel agir. Par exemple, la cmdlet get-user récupère des informations sur un utilisateur et remove-item supprime un élément spécifié.

Il est recommandé de suivre la même convention de nommage pour les fonctions que vous créez. Cela vous aidera à concevoir vos fonctions de manière plus efficace et à les rendre plus faciles à réutiliser.

Utilisez des verbes approuvés.

PowerShell fournit une liste de verbes recommandés pour l'utilisation dans les fonctions. Pour consulter la liste, exécutez simplement le cmdlet suivant :

      Get-Verb 

      

Choisissez des noms descriptifs.

Il est essentiel de ne pas donner à une fonction le même nom qu'un cmdlet intégré. Une bonne manière d'éviter ce problème est de ne pas utiliser de noms génériques comme user et data. Préférez plutôt des noms qui indiquent clairement le type de données sur lesquelles la fonction agit. Par exemple, il est facile de comprendre en quoi ces fonctions diffèrent : Get-EmployeeData, Get-UserInfo et Get-ServiceInfo.

Évitez d'utiliser les noms de fonctions à des fins de versionnage.

Ajouter des numéros de version aux noms de fonctions, comme Get-UserInfoV2, n'est pas recommandé. Cela rend les scripts plus difficiles à comprendre et augmente les risques d'utiliser d'anciennes versions d'une fonction. Préférez gérer le versionnage à travers votre système de versionnage de fichiers.

Capacités de fonctions avancées

Acceptation de l'entrée de pipeline

Vous pouvez concevoir une fonction pour accepter les entrées d'une autre fonction ou commande via un pipeline en utilisant l'attribut ValueFromPipeline.

Pour illustrer, créons une fonction qui traite une liste de chaînes de caractères une par une, convertit chaque chaîne en majuscules et affiche les résultats. Pour plus de clarté, nous diviserons le traitement des chaînes en trois blocs distincts :

• DÉBUT — Ce code s'exécute une fois, avant de traiter toute entrée de pipeline. 
• TRAITEMENT — Cette section s'exécute pour chaque élément transmis au pipeline, traitant les objets d'entrée un par un. 
• FIN — Ce code s'exécute après que toutes les entrées ont été traitées pour finaliser la sortie. 

      function Convert-ToUppercase { 

    [CmdletBinding()] 

    param ( 

        [Parameter(ValueFromPipeline = $true, Mandatory = $true)] 

        [string]$InputString 

    ) 

    BEGIN { 

        Write-Verbose "Starting the uppercase conversion process." 

    } 

    PROCESS { 

        if (-not [string]::IsNullOrWhiteSpace($InputString)) { 

            Write-Verbose "Processing string: $InputString" 

            $InputString.ToUpper() 

        } else { 

            Write-Verbose "Skipped empty or null string." 

        } 

    } 

    END { 

        Write-Verbose "Finished processing all strings." 

    } 

}
      

Voici comment nous pourrions appeler notre fonction pour convertir une liste de chaînes de caractères fournies via un pipeline :

      "hello", "world", "this", "is", "powershell" | Convert-ToUppercase -Verbose 

      

Notez que les fonctions légères appelées filters peuvent fournir un moyen très efficace de traiter les objets transmis via un pipeline. 

Permettre à une fonction de se comporter comme un Cmdlet

Vous pouvez transformer une fonction de base en une fonction avancée en utilisant l'attribut CmdletBinding. Cela permet à la fonction de se comporter comme un cmdlet, y compris la prise en charge des paramètres PowerShell définis.

Voici la fonction de base que nous avons définie plus tôt pour additionner deux nombres :

      function Add-Numbers { 

    param ( 

        [int]$Number1, 

        [int]$Number2 

    ) 

    $Sum = $Number1 + $Number2 

    Write-Output "The sum of $Number1 and $Number2 is $Sum." 

}
      

Nous pouvons le transformer en une fonction avancée comme suit :

      function Add-Numbers { 

    [CmdletBinding()] 

    param ( 

        [Parameter(Mandatory)] 

        [int]$Number1, 

        [Parameter(Mandatory)] 

        [int]$Number2 

    ) 

    process { 

        # Verbose Output 

        Write-Verbose "Starting addition of $Number1 and $Number2" 

        # Debugging Output 

        Write-Debug "Debugging: Ensuring numbers are valid integers" 

        # Perform the Addition 

        try { 

            $Result = $Number1 + $Number2 

            Write-Output $Result 

        } catch { 

            # Handle errors with error stream 

            Write-Error "An error occurred while performing the addition." 

        } 

        # Verbose Completion Message 

        Write-Verbose "Addition completed successfully" 

    } 

}
      

Construction de modules fonctionnels

Un module de fonction est un fichier avec une extension .psm1 qui contient une collection de fonctions liées. Organiser les fonctions en modules facilite la réutilisabilité et la maintenance.

Pour créer un module de fonction, créez simplement un fichier texte, collez-y vos fonctions et enregistrez le fichier avec l'extension .psm1 dans le répertoire C:\Program Files\WindowsPowerShell\Modules. Par exemple, nous pourrions créer un module avec des fonctions arithmétiques telles que la fonction Add-Numbers définie précédemment. 

Pour importer le module dans votre session PowerShell, utilisez la commande Import-Module, comme indiqué ici : 

Gestion des erreurs

PowerShell propose plusieurs techniques de gestion des erreurs pour vous aider à gérer en douceur les problèmes qui pourraient autrement arrêter l'exécution d'une fonction avec une erreur, comme une tentative de division par zéro.

Blocs Try/Catch/Finally

Lorsque vous savez qu'une certaine condition pourrait poser problème, vous pouvez utiliser les blocs Try, Catch et Finally dans votre fonction pour gérer cette condition avec élégance :

• Essayez — Ce bloc contient du code qui peut produire une erreur (comme une opération de division). Si aucune erreur ne se produit, le bloc Catch ne sera pas exécuté. 
• Catch — Si une erreur survient dans le bloc Try, le bloc Catch la gérera en capturant et en traitant les détails de l'erreur.
• Enfin — Cette partie est facultative. Si elle est présente, elle est exécutée après les blocs Try et Catch, que une erreur se soit produite ou non. 

-ErrorAction Paramètre

Le paramètre -ErrorAction vous permet de spécifier comment les erreurs doivent être gérées pour une fonction particulière. Les valeurs possibles sont : 

• Continuer — Afficher un message d'erreur et continuer.
• Arrêt — Interrompt l'exécution du script lorsqu'une erreur se produit.
• SilentlyContinue — Supprimez le message d'erreur et continuez l'exécution.
• Se renseigner — Demandez à l'utilisateur comment gérer l'erreur avec des options telles que Oui, Non et Réessayer.
• Ignorer — Ignorez complètement l'erreur sans même afficher de message.

Voici quelques exemples de l'utilisation du paramètre -ErrorAction : 

      Remove-Item "C:\path\to\nonexistentfile.txt" -ErrorAction SilentlyContinue 

 
Get-Process -Name "Notepad" -ErrorAction Stop
      

Variable $ErrorActionPreference

La variable $ErrorActionPreference contrôle la gestion des erreurs de manière globale pour toutes les cmdlets dans une session. Cette variable peut être définie pour influencer le comportement de la gestion des erreurs pour toutes les commandes, sauf si elle est remplacée par le paramètre -ErrorAction.

Exemple détaillé

Voici un exemple qui utilise plusieurs méthodes de gestion des erreurs :

• La variable $ErrorActionPreference définit la préférence globale de gestion des erreurs sur stop, donc lorsqu'une erreur se produit et qu'elle n'est pas gérée autrement, l'exécution s'arrêtera.
• Les blocs Try/Catch gèrent avec élégance l'erreur potentielle de division par zéro sans arrêter l'exécution. Le bloc Try effectue les opérations mathématiques. S'il rencontre une division par zéro, le traitement passe au bloc Catch, qui imprime un message d'erreur. 
• Le bloc Finally s'exécutera quel que soit la survenue d'une erreur, affichant un message indiquant que les opérations sont terminées. 

      # Set global error action preference to 'Stop' to immediately halt on errors 

$ErrorActionPreference = 'Stop' 

function Perform-MathOperations { 

    param ( 

        [int]$Num1, 

        [int]$Num2 

    ) 

    try { 

        # Performing addition 

        Write-Host "Performing addition: $Num1 + $Num2" 

        $additionResult = $Num1 + $Num2 

        Write-Host "Addition Result: $additionResult" 

        # Checking for division by zero before performing division 

        if ($Num2 -eq 0) { 

            throw "Division by zero is not allowed." 

        } 

        # Performing division 

        Write-Host "Performing division: $Num1 / $Num2" 

        $divisionResult = $Num1 / $Num2 

        Write-Host "Division Result: $divisionResult" 

    } 

    catch { 

        # Catching any error that occurs in the try block 

        Write-Host "An error occurred: $_" 

        Write-Host "Error Type: $($_.Exception.GetType().Name)" 

    } 

    finally { 

        # This block always runs regardless of error occurrence 

        Write-Host "Finished performing math operations." 

    } 

}
      

La capture d'écran ci-dessous montre le résultat de l'appel de cette fonction de deux manières. D'abord, nous l'appelons avec une entrée valide :

Effectuer-MathOperations -Num1 10 -Num2 2

Ensuite, nous l'appelons avec une entrée qui résultera en une tentative de division par zéro :

Effectuez-MathOperations -Num1 10 -Num2 0

Dépannage de vos fonctions

Vous pouvez afficher des messages qui fournissent différents niveaux de détail pendant l'exécution d'une fonction en utilisant Write-output (ou Write-host), Write-Verbose et Write-Debug. Ces informations peuvent vous aider à tracer le chemin d'exécution étape par étape pour identifier un comportement inattendu.

Par exemple, la capture d'écran suivante montre comment nous pourrions réviser notre fonction basique Add-Numbers pour fournir des détails de dépannage. Notez que par défaut, le flux de messages détaillés n'est pas affiché, donc nous devons utiliser -Verbose lors de l'invocation de la fonction. 

      Add-Numbers -Number1 5 -Number2 10 -Verbose 

      

De même, les messages Write-Debug ne sont pas affichés dans la console par défaut, mais vous pouvez les afficher en incluant -Debug lorsque vous exécutez la fonction : 

Add-Numbers -Number1 5 -Number2 10 -Debug

Meilleures pratiques

• Concevez chaque fonction pour qu'elle effectue une seule tâche. Cela les rend plus faciles à tester, utiliser et maintenir.
• Concevez les fonctions de manière modulaire afin qu'elles puissent être réutilisées dans différents scripts.
• Lors de l'utilisation de paramètres, spécifiez leurs valeurs par défaut.
• Incluez des commentaires détaillés dans vos fonctions. Cette aide basée sur les commentaires facilitera le débogage et la réutilisation des fonctions.
• Faites en sorte que vos fonctions retournent des objets plutôt que des sorties formatées pour améliorer la réutilisabilité.

Exemple supplémentaire

La fonction suivante illustre plusieurs des capacités évoquées précédemment, y compris la gestion des erreurs :

      # Function: Backup-Files 

# Description: Backs up files from a source directory to a backup directory. 

function Backup-Files { 

    param ( 

        [Parameter(Mandatory = $true)] 

        [string]$SourcePath, # The directory containing the files to back up 

        [Parameter(Mandatory = $true)] 

        [string]$BackupPath, # The directory where files will be backed up 

        [string[]]$Extensions = @("*") # File extensions to back up (default: all files) 

    ) 

    # Check if the source path exists 

    if (-not (Test-Path -Path $SourcePath)) { 

        Write-Error "Source path '$SourcePath' does not exist." 

        return 

    } 

    # Create the backup directory if it does not exist 

    if (-not (Test-Path -Path $BackupPath)) { 

        Write-Output "Creating backup directory at '$BackupPath'..." 

        New-Item -ItemType Directory -Path $BackupPath | Out-Null 

    } 

    # Get files matching the specified extensions 

    foreach ($extension in $Extensions) { 

        $files = Get-ChildItem -Path $SourcePath -Filter "*.$extension" -File -ErrorAction SilentlyContinue 

        foreach ($file in $files) { 

            $destination = Join-Path -Path $BackupPath -ChildPath $file.Name 

            Write-Output "Backing up file: $($file.FullName) -> $destination" 

            Copy-Item -Path $file.FullName -Destination $destination -Force 

        } 

    } 

    Write-Output "Backup completed successfully." 

}
      

Nous pouvons appeler cette fonction pour sauvegarder tous les fichiers, ou uniquement certaines extensions de fichier comme montré ici :

      Backup-Files -SourcePath "D:\Office\project" -BackupPath "D:\Backup" -Extensions @("csv", "txt") 

      

Conclusion

Les fonctions dans PowerShell offrent une approche structurée de l'écriture de scripts qui améliore la modularité, la réutilisabilité et la maintenabilité. N'hésitez pas à expérimenter avec tous les exemples de code fournis dans cet article. Lorsque vous commencez à créer vos propres fonctions, assurez-vous d'adopter les meilleures pratiques pour les nommer et les utiliser.