Placement à l’intérieur d’un script

Vous pouvez utiliser les commentaires aux endroits suivants :

1. Au début du script
2. A la fin du script

Placement à l’intérieur d’une fonction

 Vous pouvez utiliser les commentaires aux endroits suivants :
1.       Avant le mot clé Function
2.       Au début du corps de la fonction, c'est-à-dire juste après l’accolade ouvrante
3.       A la fin du corps de la fonction, c'est-à-dire juste avant l’accolade fermante 

Exemple : 

<#
     .< mot clé d'aide>
     < contenu d'aide>
#>
     function MyFunction { }

 -ou -

    function MyFunction
     {
         <#
         .< mot clé d'aide>
         < contenu d'aide>
         #>
          <commandes de fonction>
     }  

-ou -

      function MyFunction
     {
         <commandes de fonction>
          <#
         .< mot clé d'aide>
         < contenu d'aide>
         #>
     }

Exemple en situation réelle 

Reprenons pour l’exemple le script « Afficher la taille disque disponible à distance (3) » de la bibliothèque de script de la rubrique Fichiers et disques. 

Voici le script dans sa forme originale : 

# get-freespace.ps1
param ($computer = ".", [switch]$total)
# récupérer tous les disques logiques de l'ordinateur:
get-wmiobject -computer $computer win32_logicaldisk |
tee-object -variable disques |
                            select-object @{e={$_.systemname};n="Système"},
                            @{e={$_.name};n="Disque"},
                       @{e={[math]::round($_.freespace/1GB,1)};n="Disponible (Go)"}

# afficher l'espace disponible total si demandé:

if ($total) {
"`nEspace Disponible Total sur $($disques[0].systemname): $([math]::round(($disques|measure-object
freespace -sum).sum/1GB,1)) Go"
}

Nous allons tout d’abord le transformer en fonction car ce sera plus pratique dans cette forme, mais nous aurions très bien pu le laisser en tant que script et intégrer les commentaires à l’intérieur. Nous verrons par la suite quelles sont les différences.

Pour ce faire, il suffit de mettre le mot clé Function en début de script et de mettre le script dans un bloc entre accolades, comme ceci :

Function Get-Freespace{
    Param ([String]$ComputerName = ".", [Switch]$Total)
    Get-WmiObject -ComputerName $ComputerName win32_logicaldisk |
        Tee-Object -variable disques |
                   Select-Object @{e={$_.systemname};n="Système"},
                                  @{e={$_.name};n="Disque"}, 
              @{e={[math]::round($_.freespace/1GB,1)};n="Disponible (Go)"}

     if ($total)
     {
        Write-Output "`nEspace Disponible Total sur $($disques[0].systemname): $([math]::round(($disques|Measure-Object freespace -sum).sum/1GB,1)) Go"
     }
}

A présent pour appeler la fonction, il faut la charger en mémoire. Pour cela, soit vous copier/collez la fonction directement dans l’interpréteur de commande PowerShell, soit vous utilisez la technique du Dot Sourcing pour importer le script dans la portée courante, comme ceci : 

PS > . C:\temp\Get-FreeSpace.ps1

 Attention : ne pas oublier le point devant le chemin du script ! 

Maintenant nous pouvons appeler la fonction en tapant simplement son nom, comme ceci :

 PS > Get-FreeSpace

Système     Disque Disponible (Go)
-------     ------ ---------------
WIN7_BUREAU A:                   0
WIN7_BUREAU C:                 2,8
WIN7_BUREAU D:                79,2 

Il ne nous reste plus qu’à intégrer l’aide à l’intérieur de notre fonction, ce qui donne quelque chose comme cela : 

Function Get-Freespace
{
    <#
    .SYNOPSIS
        Obtient l'espace disque libre sur les disques logiques d'un ordinateur.
    .DESCRIPTION
        La fonction Get-FreeSpace obtient l'espace disque libre sur les disques logiques de l'ordinateur courant où d'un ordinateur distant.
    Il est à noter que l'ordinateur distant doit être configuré pour accepter les requêtes WMI.
    .PARAMETER ComputerName
        Nom de l'ordinateur sur lequel porte la fonction. Si ce paramètre n'est pas spécifié, alors la fonction s'exécute localement.
    .PARAMETER Total
        Paramètre de type commutateur. Si spécifié alors le total d'espace disque restant sera calculé
    .EXAMPLE
        PS > Get-FreeSpace

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    JANEL01       C:                              2,1
    JANEL01       D:                                0

     .EXAMPLE
        PS > Get-FreeSpace -ComputerName MCE01 -Total

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    MCE01         C:                              1,8
    MCE01         D:                              0,6

    Espace Disponible Total sur MCE01: 15,1 Go

     .EXAMPLE
        PS > Get-Content C:\temp\parc.txt | ForEach { Get-FreeSpace $_}

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    JANEL01       C:                              2,1
    JANEL01       D:                                0
    MCE01         C:                              1,8
    MCE01         D:                              0,6
    MCE01         E:                              7,3

    .NOTES
        Author:   Arnaud Petitjean
        Version:  4.0
    #>

     Param ([String]$ComputerName = ".", [Switch]$Total)

     Get-WmiObject -ComputerName $ComputerName win32_logicaldisk |
        tee-object -variable disques |
                 select-object @{e={$_.systemname};n="Système"},
                                 @{e={$_.name};n="Disque"},
                                @{e={[math]::round($_.freespace/1GB,1)};n="Disponible (Go)"}
    
     if ($total)
     {
        Write-Output "`nEspace Disponible Total sur $($disques[0].systemname): $([math]::round(($disques|Measure-Object freespace -sum).sum/1GB,1)) Go"
    } 
} 

A présent si nous rechargeons notre fonction, nous pouvons demander de l’aide standard sur celle-ci de la façon suivante :

 PS > Get-FreeSpace -? 

NOM
    Get-Freespace 

RÉSUMÉ
    Obtient l'espace disque libre sur les disques logiques d'un ordinateur.

SYNTAXE
    Get-Freespace [[-ComputerName] <String>] [-Total] [<CommonParameters>]

DESCRIPTION
    La fonction Get-FreeSpace obtient l'espace disque libre sur les disques logiques de l'ordinateur courant où d'un ordinateur distant.    Il est à noter que l'ordinateur distant doit être configuré pour accepter les requêtes WMI.

LIENS CONNEXES

REMARQUES
    Pour consulter les exemples, tapez : "get-help Get-Freespace -examples".
    Pour plus d'informations, tapez : "get-help Get-Freespace -detailed".
    Pour obtenir des informations techniques, tapez : "get-help Get-Freespace -full".

  Ou l’aide détaillée :

 PS  > Help Get-Freespace -Detailed

 NOM
    Get-Freespace

 RÉSUMÉ
    Obtient l'espace disque libre sur les disques logiques d'un ordinateur.

 SYNTAXE
    Get-Freespace [[-ComputerName] <String>] [-Total] [<CommonParameters>]

  DESCRIPTION
    La fonction Get-FreeSpace obtient l'espace disque libre sur les disques logiques de l'ordinateur courant où d'un ordinateur distant.
    Il est à noter que l'ordinateur distant doit être configuré pour accepter les requêtes WMI.

  PARAMÈTRES
    -ComputerName <String>
        Nom de l'ordinateur sur lequel porte la fonction. Si ce paramètre n'est pas spécifié, alors la fonction s'exécute localement.

     -Total [<SwitchParameter>]
        Paramètre de type commutateur. Si spécifié alors le total d'espace disque restant sera calculé

     <CommonParameters>
        Cette applet de commande prend en charge les paramètres courants : Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer et OutVariable. Pour plus d'informations, tapez
        « get-help about_commonparameters ».

     -------------------------- EXEMPLE 1 --------------------------

     PS >Get-FreeSpace

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    JANEL01       C:                              2,1
    JANEL01       D:                                0

     -------------------------- EXEMPLE 2 --------------------------

     PS >Get-FreeSpace -ComputerName MCE01 -Total

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    MCE01         C:                              1,8
    MCE01         D:                              0,6

    Espace Disponible Total sur MCE01: 15,1 Go

     -------------------------- EXEMPLE 3 --------------------------

     PS >Get-Content C:\temp\parc.txt | ForEach { Get-FreeSpace $_}

    Système       Disque              Disponible (Go)
    -------       ------              ---------------
    JANEL01       C:                              2,1
    JANEL01       D:                                0
    MCE01         C:                              1,8
    MCE01         D:                              0,6
    MCE01         E:                              7,3

  REMARQUES
    Pour consulter les exemples, tapez : "get-help Get-Freespace -examples".
    Pour plus d'informations, tapez : "get-help Get-Freespace -detailed".
    Pour obtenir des informations techniques, tapez : "get-help Get-Freespace -full". 

Facile vous ne trouvez pas ?

Pour bien comprendre, regardez la différence lors de l’appel de l’aide si nous avions intégré l’aide directement dans notre script sans avoir pris soin de le convertir en fonction :

Aide intégrée dans la fonction :

Conclusion

Vous l’aurez compris, l’intégration de l’aide dans un script ou fonction est on ne peut plus simple et constitue une forte valeur ajoutée à vos créations. Cela sera particulièrement utile aux personnes qui utiliseront vos scripts ou fonctions car l’accès à l’aide est identique aux commandelettes natives.Pour plus de détails sur la création d’aide, veuillez consulter la rubrique d’aide « about_Comment_Based_Help » en tapant la commande suivante :

PS > Help about_Comment_Based_Help