Interpréter le contenu du fichier d’aide et mettre à jour le contenu de l’aide locale dans PowerShell
Quand vous trouvez la commande dont vous avez besoin pour une tâche, vous pouvez utiliser son fichier d’aide pour apprendre à l’utiliser. Vous pouvez notamment passer en revue les exemples et essayer de comprendre l’utilisation de la commande dans ces exemples. Toutefois, il est rare que des exemples couvrent toutes les variantes possibles de l’utilisation de la commande. En apprenant à interpréter la syntaxe du fichier d’aide, vous pourrez identifier toutes les fonctionnalités d’une commande donnée.
Aide de la commande Get-EventLog
Utilisez l’aide de Get-EventLog comme exemple. Si vous entrez la commande Get-Help Get-EventLog dans la console et appuyez sur la touche Entrée, l’aide retourne la syntaxe suivante :
Get-EventLog [-LogName] <String> [[-InstanceId] <Int64[]>] [-After <DateTime>] [-AsBaseObject] [-Before <DateTime>] [-ComputerName <String[]>] [-EntryType {Error | Information | FailureAudit | SuccessAudit | Warning}] [-Index <Int32[]>] [-Message <String>] [-Newest <Int32>] [-Source <String[]>] [-UserName <String[]>] [<CommonParameters>]
Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]
Les deux blocs de texte sont des ensembles de paramètres, chacun représentant une façon dont vous pouvez exécuter la commande. Notez que les deux jeux contiennent de nombreux paramètres et qu’ils ont plusieurs paramètres en commun. Vous ne pouvez pas combiner des paramètres des deux jeux. Autrement dit, si vous décidez d’utiliser le paramètre –List , vous ne pouvez pas également utiliser –LogName, car ces paramètres n’apparaissent pas ensemble dans le même jeu de paramètres.
Le nom du paramètre –LogName est placé entre crochets, ce qui signifie qu’il s’agit d’un paramètre positionnel. Vous ne pouvez pas exécuter la commande sans nom de journal. Toutefois, vous n’avez pas besoin d’entrer le nom du paramètre –LogName . Vous devez passer la chaîne de nom du journal en tant que premier paramètre, car c’est la position dans le fichier d’aide où le paramètre –LogName s’affiche. Les deux commandes suivantes fournissent donc les mêmes résultats :
Get-EventLog –LogName Application
Get-EventLog Application
Omission des noms de paramètres
Soyez prudent quand vous omettez des noms de paramètres, ce qui peut arriver pour différentes raisons. Vous ne pouvez pas omettre tous les paramètres. Par exemple, le paramètre -ComputerName ne peut pas avoir le nom du paramètre omis. En outre, vous pouvez rapidement perdre le fil du processus. Quand vous fournissez des noms de paramètres, les paramètres peuvent apparaître dans n’importe quel ordre comme l’illustre la commande suivante :
Get-EventLog –ComputerName LON-DC1 –LogName Application –Newest 10
Toutefois, quand vous omettez les noms de paramètres, vous devez veiller à entrer les paramètres dans l’ordre correct. Par exemple, la commande suivante ne fonctionne pas, car la valeur du nom de journal n’apparaît pas à la position correcte :
Get-EventLog –ComputerName LON-DC1 Application
Spécification de plusieurs valeurs
Certains paramètres acceptent plusieurs valeurs. Dans la section SYNTAXE , une notation entre crochets doubles dans le type de valeur de paramètre désigne ces paramètres. Par exemple :
-ComputerName <string[]>
La syntaxe ci-dessus indique que le paramètre –ComputerName peut accepter une ou plusieurs valeurs de chaîne. Pour spécifier plusieurs valeurs, vous pouvez notamment utiliser une liste de valeurs séparées par des virgules. Vous n’avez pas besoin de placer les valeurs entre guillemets, sauf si les valeurs elles-mêmes contiennent une virgule ou un espace blanc, y compris un caractère de tabulation. Par exemple, utilisez la commande suivante pour spécifier plusieurs noms d’ordinateur :
Get-EventLog –LogName Application –ComputerName LON-CL1,LON-DC1
Notes
Vous trouverez plus d’informations sur chaque paramètre en consultant l’aide complète de la commande. Par exemple, exécutez Get-Help Get-EventLog –Complet pour passer en revue l’aide complète de Get-EventLog et notez les informations supplémentaires qui s’affichent. Par exemple, vous pouvez confirmer que le paramètre –LogName est obligatoire et apparaît dans la première position.
Bonne pratique : Si vous commencez simplement à utiliser Windows PowerShell, essayez de fournir des noms de paramètres complets au lieu de passer des valeurs de paramètre par position. Les noms de paramètres complets facilitent la révision des commandes et la résolution des problèmes de paramètre. De plus, ils simplifient la détection des erreurs si vous entrez la commande incorrectement.
Mise à jour de l’aide
Windows PowerShell 3.0 (et versions ultérieures) n’est pas fourni avec les fichiers d’aide. Au lieu de cela, les fichiers d’aide sont disponibles comme service en ligne. Les fichiers d’aide des commandes créées par Microsoft sont hébergés sur des serveurs web appartenant à Microsoft. Les commandes non-Microsoft sont parfois disponibles en ligne, si l’auteur ou le fournisseur génère correctement le module et fournit l’emplacement en ligne des fichiers d’aide. En utilisant le modèle en ligne, les auteurs qui écrivent des commandes, y compris les auteurs Microsoft, peuvent apporter des corrections et des améliorations à leurs fichiers d’aide au fil du temps, puis les mettre à disposition sans avoir à créer une mise à jour complète du produit.
Exécutez Update-Help pour analyser votre ordinateur pour rechercher tous les modules installés, récupérer les emplacements d’aide en ligne pour chacun d’eux et essayer de télécharger leurs fichiers d’aide respectifs. Vous devez exécuter cette commande en tant que membre du groupe Administrateurs local, car l’aide de la commande principale Windows PowerShell est stockée dans le dossier %systemdir% . Des messages d’erreur s’affichent si l’aide n’est pas téléchargeable. Dans ce cas, Windows PowerShell affiche toujours une aide par défaut pour les commandes.
Par défaut, Windows PowerShell télécharge les fichiers d’aide dans la langue configurée de votre système. Si l’aide n’est pas disponible dans cette langue, Windows PowerShell est défini par défaut sur la langue en-US (anglais américain). Vous pouvez remplacer ce comportement à l’aide d’un paramètre Update-Help pour spécifier l’UICulture pour laquelle vous souhaitez récupérer de l’aide.
Par défaut, Update-Help recherche les fichiers d’aide une fois toutes les 24 heures, même si vous exécutez la commande plusieurs fois dans une ligne. Pour remplacer ce comportement, incluez le paramètre –Force .
Le compagnon de Update-Help est Save-Help. Il télécharge le contenu d’aide et l’enregistre à un emplacement que vous spécifiez. Cette fonctionnalité vous permet de copier ce contenu sur des ordinateurs qui ne sont pas connectés à Internet. Update-Help propose un paramètre pour spécifier un autre emplacement source. Cette fonctionnalité permet de mettre à jour l’aide sur des ordinateurs qui ne sont pas connectés à Internet.
Avant Windows PowerShell 4.0, Update-Help et Save-Help téléchargent l’aide uniquement pour les applets de commande installées sur l’ordinateur local (à partir de laquelle vous exécutez la commande). Dans Windows PowerShell 4.0 et versions ultérieures, vous pouvez utiliser Save-Help pour les modules installés sur des ordinateurs distants.