Guide pratique pour écrire un module de script PowerShell

Article
03/25/2025

Un module de script est un script PowerShell valide enregistré dans une extension .psm1. Cette extension permet au moteur PowerShell d’utiliser des règles et des applets de commande de module sur votre fichier. La plupart de ces fonctionnalités sont là pour vous aider à installer votre code sur d’autres systèmes, ainsi qu’à gérer l’étendue. Vous pouvez également utiliser un fichier manifeste de module, qui décrit des installations et des solutions plus complexes.

Écriture d’un module de script PowerShell

Pour créer un module de script, enregistrez un script PowerShell valide dans un fichier .psm1. Le script et le répertoire où il est stocké doivent utiliser le même nom. Par exemple, un script nommé MyPsScript.psm1 est stocké dans un répertoire nommé MyPsScript.

Le répertoire du module doit se trouver dans un chemin d’accès spécifié dans $Env:PSModulePath. Le répertoire du module peut contenir toutes les ressources nécessaires pour exécuter le script et un fichier manifeste de module qui décrit le fonctionnement de votre module dans PowerShell.

Créer un module PowerShell de base

Les étapes suivantes décrivent comment créer un module PowerShell.

Enregistrez un script PowerShell avec une extension .psm1. Utilisez le même nom pour le script et le répertoire dans lequel le script est enregistré.

L’enregistrement d’un script avec l’extension .psm1 signifie que vous pouvez utiliser les applets de commande de module, telles que Import-Module. Les applets de commande de module existent principalement pour vous permettre d’importer et d’exporter votre code sur les systèmes d’autres utilisateurs. La solution alternative consiste à charger votre code sur d’autres systèmes, puis à la source point dans la mémoire active, ce qui n’est pas une solution évolutive. Pour plus d’informations, consultez Présentation d’un module Windows PowerShell. Par défaut, lorsque les utilisateurs importent votre fichier .psm1, toutes les fonctions de votre script sont accessibles, mais les variables ne le sont pas.

Un exemple de script PowerShell, intitulé Show-Calendar, est disponible à la fin de cet article.
```
function Show-Calendar {
param(
    [datetime] $Start = [datetime]::Today,
    [datetime] $End = $Start,
    $FirstDayOfWeek,
    [int[]] $HighlightDay,
    [string[]] $HighlightDate = [datetime]::Today.ToString('yyyy-MM-dd')
    )

    #actual code for the function goes here see the end of the topic for the complete code sample
}
```
Pour contrôler l’accès utilisateur à certaines fonctions ou variables, appelez Export-ModuleMember à la fin de votre script.

L’exemple de code en bas de l’article n’a qu’une seule fonction, qui est exposée par défaut. Toutefois, il est recommandé d’appeler explicitement les fonctions que vous souhaitez exposer, comme décrit dans le code suivant :
```
function Show-Calendar {
      }
Export-ModuleMember -Function Show-Calendar
```
Vous pouvez restreindre ce qui est importé à l’aide d’un manifeste de module. Pour plus d’informations, consultez Importer un module PowerShell et Comment écrire un manifeste de module PowerShell.
Si vous avez des modules que votre propre module doit charger, vous pouvez utiliser Import-Module, en haut de votre module.

L’applet de commande Import-Module importe un module ciblé sur un système et peut être utilisée ultérieurement dans la procédure pour installer votre propre module. L’exemple de code en bas de cet article n’utilise aucun module d’importation. Toutefois, si c’est le cas, elles sont répertoriées en haut du fichier, comme indiqué dans le code suivant :
```
Import-Module GenericModule
```
Pour décrire votre module au système d’aide PowerShell, vous pouvez utiliser des commentaires d’aide standard dans le fichier ou créer un fichier d’aide supplémentaire.

L’exemple de code en bas de cet article inclut les informations d’aide contenues dans les commentaires. Vous pouvez également écrire des fichiers XML développés qui contiennent du contenu d’aide supplémentaire. Pour plus d’informations, consultez l’écriture d’aide pour les modules Windows PowerShell.
Si vous avez des modules, des fichiers XML ou d’autres contenus que vous souhaitez empaqueter avec votre module, vous pouvez utiliser un manifeste de module.

Un manifeste de module est un fichier qui contient les noms d’autres modules, mises en page de répertoires, numéros de contrôle de version, données d’auteur et autres informations. PowerShell utilise le fichier manifeste du module pour organiser et déployer votre solution. Pour plus d’informations, consultez Comment écrire un manifeste de module PowerShell.
Pour installer et exécuter votre module, enregistrez le module dans l’un des chemins PowerShell appropriés et utilisez Import-Module.

Les chemins d’accès où vous pouvez installer votre module se trouvent dans la variable globale $Env:PSModulePath. Par exemple, un chemin d’accès commun pour enregistrer un module sur un système serait %SystemRoot%/users/<user>/Documents/PowerShell/Modules/<moduleName>. Veillez à créer un répertoire pour votre module qui utilise le même nom que le module de script, même s’il ne s’agit que d’un seul fichier .psm1. Si vous n’avez pas enregistré votre module dans l’un de ces chemins, vous devrez spécifier l’emplacement du module dans la commande Import-Module. Sinon, PowerShell ne serait pas en mesure de trouver le module.

Remarque

À compter de PowerShell 3.0, si vous avez placé votre module dans l’un des chemins de module PowerShell, vous n’avez pas besoin de l’importer explicitement. Votre module est automatiquement chargé lorsqu’un utilisateur appelle votre fonction. Pour plus d’informations sur le chemin du module, consultez Importation d’un de module PowerShell et about_PSModulePath.
Pour supprimer un module d’un service actif dans la session PowerShell active, utilisez remove-module.

Remarque

Remove-Module supprime un module de la session PowerShell actuelle, mais ne désinstalle pas le module ni supprime les fichiers du module.

exemple de code Show-Calendar

L’exemple suivant est un module de script qui contient une fonction unique nommée Show-Calendar. Cette fonction affiche une représentation visuelle d’un calendrier. L’exemple contient les chaînes d’aide PowerShell pour le synopsis, la description, les valeurs de paramètre et le code. Lorsque le module est importé, la commande Export-ModuleMember garantit que la fonction Show-Calendar est exportée en tant que membre de module.

<#
 .SYNOPSIS
  Displays a visual representation of a calendar.

 .DESCRIPTION
  Displays a visual representation of a calendar. This function supports multiple months
  and lets you highlight specific date ranges or days.

 .PARAMETER Start
  The first month to display.

 .PARAMETER End
  The last month to display.

 .PARAMETER FirstDayOfWeek
  The day of the month on which the week begins.

 .PARAMETER HighlightDay
  Specific days (numbered) to highlight. Used for date ranges like (25..31).
  Date ranges are specified by the Windows PowerShell range syntax. These dates are
  enclosed in square brackets.

 .PARAMETER HighlightDate
  Specific days (named) to highlight. These dates are surrounded by asterisks.

 .EXAMPLE
   # Show a default display of this month.
   Show-Calendar

 .EXAMPLE
   # Display a date range.
   Show-Calendar -Start "March, 2010" -End "May, 2010"

 .EXAMPLE
   # Highlight a range of days.
   Show-Calendar -HighlightDay (1..10 + 22) -HighlightDate "2008-12-25"
#>
function Show-Calendar {
param(
    [datetime] $Start = [datetime]::Today,
    [datetime] $End = $Start,
    $FirstDayOfWeek,
    [int[]] $HighlightDay,
    [string[]] $HighlightDate = [datetime]::Today.ToString('yyyy-MM-dd')
    )

## Determine the first day of the start and end months.
$Start = New-Object DateTime $Start.Year,$Start.Month,1
$End = New-Object DateTime $End.Year,$End.Month,1

## Convert the highlighted dates into real dates.
[datetime[]] $HighlightDate = [datetime[]] $HighlightDate

## Retrieve the DateTimeFormat information so that the
## calendar can be manipulated.
$dateTimeFormat  = (Get-Culture).DateTimeFormat
if($FirstDayOfWeek)
{
    $dateTimeFormat.FirstDayOfWeek = $FirstDayOfWeek
}

$currentDay = $Start

## Process the requested months.
while($Start -le $End)
{
    ## Return to an earlier point in the function if the first day of the month
    ## is in the middle of the week.
    while($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek)
    {
        $currentDay = $currentDay.AddDays(-1)
    }

    ## Prepare to store information about this date range.
    $currentWeek = New-Object PsObject
    $dayNames = @()
    $weeks = @()

    ## Continue processing dates until the function reaches the end of the month.
    ## The function continues until the week is completed with
    ## days from the next month.
    while(($currentDay -lt $Start.AddMonths(1)) -or
        ($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek))
    {
        ## Determine the day names to use to label the columns.
        $dayName = "{0:ddd}" -f $currentDay
        if($dayNames -notcontains $dayName)
        {
            $dayNames += $dayName
        }

        ## Pad the day number for display, highlighting if necessary.
        $displayDay = " {0,2} " -f $currentDay.Day

        ## Determine whether to highlight a specific date.
        if($HighlightDate)
        {
            $compareDate = New-Object DateTime $currentDay.Year,
                $currentDay.Month,$currentDay.Day
            if($HighlightDate -contains $compareDate)
            {
                $displayDay = "*" + ("{0,2}" -f $currentDay.Day) + "*"
            }
        }

        ## Otherwise, highlight as part of a date range.
        if($HighlightDay -and ($HighlightDay[0] -eq $currentDay.Day))
        {
            $displayDay = "[" + ("{0,2}" -f $currentDay.Day) + "]"
            $null,$HighlightDay = $HighlightDay
        }

        ## Add the day of the week and the day of the month as note properties.
        $currentWeek | Add-Member NoteProperty $dayName $displayDay

        ## Move to the next day of the month.
        $currentDay = $currentDay.AddDays(1)

        ## If the function reaches the next week, store the current week
        ## in the week list and continue.
        if($currentDay.DayOfWeek -eq $dateTimeFormat.FirstDayOfWeek)
        {
            $weeks += $currentWeek
            $currentWeek = New-Object PsObject
        }
    }

    ## Format the weeks as a table.
    $calendar = $weeks | Format-Table $dayNames -AutoSize | Out-String

    ## Add a centered header.
    $width = ($calendar.Split("`n") | Measure-Object -Maximum Length).Maximum
    $header = "{0:MMMM yyyy}" -f $Start
    $padding = " " * (($width - $header.Length) / 2)
    $displayCalendar = " `n" + $padding + $header + "`n " + $calendar
    $displayCalendar.TrimEnd()

    ## Move to the next month.
    $Start = $Start.AddMonths(1)

}
}
Export-ModuleMember -Function Show-Calendar

Partager via

Guide pratique pour écrire un module de script PowerShell

Écriture d’un module de script PowerShell

Créer un module PowerShell de base

exemple de code Show-Calendar

Ressources supplémentaires