Flash info

Une frénésie incontrollée poussent certains individus à convertir tous les scripts d'admin en PowerShell. L'un d'eux aurait été apperçu récemment près du campus universitaire de Talence.

 
Accueil arrow Articles / Tutoriaux arrow Inclure de l’aide dans ses fonctions ou scripts
Inclure de l’aide dans ses fonctions ou scripts
Écrit par Arnaud Petitjean [MVP]   
12-03-2010
ktip.png 

Une des nombreuses nouveautés de PowerShell v2 est la possibilité d’inclure de l’aide dans les scripts ou fonctions de façons à ce que ces dernières aient au final un comportement proche des commandelettes natives incluses dans PowerShell.Pour ce faire, il existe plusieurs façons d’y parvenir :

  1. Créer un fichier XML respectant le schéma MAML (Multi-Agent Modeling Language),
  2. Créer des commentaires à l’intérieur des fonctions ou des scripts

Dans ce tutoriel, nous ne parlerons que de la seconde forme car celle-ci se révèle être la plus simple et elle semble être la plus adaptée à un public d’administrateurs système qui souhaite construire des scripts rapidement sans se prendre trop la tête. 

La création d’un fichier XML externe est, de mon point de vue, plus orientée vers les développeurs qui souhaitent aller plus loin dans la définition des fichiers d’aide associés aux commandes qu’ils fournissent. En effet, utiliser l’aide au format XML permet de proposer de l’aide en différentes langues mais aussi d’avoir accès à certaines rubriques non accessibles autrement. Si vous êtes intéressé par la construction de fichiers d’aide au format MAML, veuillez consulter les deux liens suivants : How To Write Cmdlet Help et Creating the Cmdlet Help File.

Revenons à présent à la forme la plus simple : l’inclusion de commentaires.La syntaxe de l'aide basée sur des commentaires se présente comme cela :

    # .< mot clé d'aide>
    # <contenu d'aide> 

-ou -

     <#
        .< mot clé d'aide>
        < contenu d'aide>
    #> 

REMARQUE : Il est important de noter que si vous utilisez la première forme, c'est-à-dire utiliser un caractère dièse à chaque début de ligne, cela permettra à votre fonction ou script de s’exécuter sans erreur avec PowerShell v1 car l’aide sera purement et simplement ignorée. A l’inverse, si vous utilisez la seconde forme à base de bloc de commentaires, PowerShell v1 ne saura pas les interpréter et le script ou la fonction ne pourra pas s’exécuter.

 

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 ?

Je voudrais juste revenir sur point : la différence entre l’aide intégrée dans un script et l’aide dans une fonction. Celle-ci réside simplement dans l’affichage. 

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_script.png

 

 

 

 

 

 

 

 

 

 

Aide intégrée dans la fonction :

aide_fonction.png 

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

 

Dernière mise à jour : ( 12-03-2010 )
 
© 2017 PowerShell-Scripting.com