Existe-t-il des conventions de codage PowerShell bien connues?

Existe-t-il des conventions bien définies lors de la programmation dans PowerShell?

Par exemple, dans les scripts qui doivent être maintenus à long terme, devons-nous:

• Utilisez le vrai nom ou l'alias de la cmdlet?
• Spécifiez le nom du paramètre d'applet de commande en totalité ou seulement partiellement ( dir -Recursepar rapport à dir -r)
• Lorsque vous spécifiez des arguments de chaîne pour les applets de commande, les placez-vous entre guillemets ( New-Object 'System.Int32'par rapport àNew-Object System.Int32
• Lorsque vous écrivez des fonctions et des filtres, spécifiez-vous les types de paramètres?
• Écrivez-vous des applets de commande dans le cas (officiel) correct?
• Pour les mots clés comme BEGIN...PROCESS...ENDles écrivez-vous uniquement en majuscules?

Il semble que MSDN manque de document sur les conventions de codage pour PowerShell, alors que ce document existe par exemple pour C #.

@Robert Harvey a fait référence à de bons liens officiels. À titre de document moins formel, mes réflexions seraient les suivantes:

Utilisez le vrai nom ou l'alias de la cmdlet?

N'utilisez l'alias que s'il est plus clair que le nom complet. Par exemple, je pense que la plupart des gens trouveraient dirou lsplus clair dans un script que Get-ChildItemsur la base de l'expérience précédente (par exemple, fondamentalement, quiconque écrit un script PowerShell a l'une de ces deux fois dans les scripts batch DOS ou les scripts Unix).

Spécifiez le nom du paramètre d'applet de commande en totalité ou seulement partiellement (dir -Recurse versus dir -r)

Dans un script, j'épelerais complètement le nom parce que (contrairement à l'exemple ci-dessus), je ne peux pas penser à un moment où l'interrupteur le plus court serait en fait plus clair que de le préciser. Les noms de commutateur plus courts permettent d'économiser la saisie. Sur une ligne de commande, cela est impératif. Dans un script, les frappes supplémentaires en valent la peine pour la lisibilité et la maintenabilité.

Lorsque vous spécifiez des arguments de chaîne pour les applets de commande, les placez-vous entre guillemets (New-Object 'System.Int32' contre New-Object System.Int32

Mettre des arguments de chaîne entre guillemets semble beaucoup plus clair lors de la lecture du code, donc je les inclurais.

Lorsque vous écrivez des fonctions et des filtres, spécifiez-vous les types de paramètres?

Uniquement lorsque cela est nécessaire pour résoudre l'ambiguïté de l'interprète (ce qui se produit). Si vous voulez essayer de mettre des types sur tout, vous pouvez aussi bien écrire des applications en ligne de commande C # (ce qui n'est pas toujours une mauvaise chose, mais cela annule le gain de temps que vous obtenez en scriptant).

Écrivez-vous des applets de commande dans le cas (officiel) correct?

Tu devrais . Je fais d' habitude . Quand je suis pressé, je suis connu pour être un peu laxiste car cela n'a pas d'importance syntaxique.

Pour les mots clés comme COMMENCER ... PROCESSUS ... FIN les écrivez-vous uniquement en majuscules?

Non, ce n'est pas FORTRAN. Je pense que la plupart des gens trouvent beginou sont Beginplus lisibles que BEGIN. Il y a une raison pour laquelle nous associons toutes les majuscules aux cris en ligne et crier les parties les plus banales du programme entrave la lisibilité en attirant l'attention sur les parties les moins importantes.

Le principe directeur devrait être la lisibilité. Les scripts, par leur nature même de programmes rapides et sales, tournent vers le code en écriture seule. Chaque décision doit être prise pour vous assurer que vous et votre équipe pouvez toujours comprendre le script en six mois. Essayez de vous sortir de vos propres chaussures en regardant votre code et posez cette question: "si j'avais commencé ce travail il y a une semaine (et que je n'étais donc pas vraiment endoctriné dans la culture générale), est-ce que je trouverais la façon dont cela est écrit éclairant ou déroutant? "

Microsoft a écrit et publié un très bon ensemble de directives de développement de cmdlet

Extrait:

Les rubriques de cette section fournissent des instructions de développement que vous pouvez utiliser pour produire des applets de commande bien formées. En tirant parti des fonctionnalités communes fournies par le runtime Windows PowerShell et en suivant ces instructions, vous pouvez développer des applets de commande robustes avec un minimum d'effort et offrir à l'utilisateur une expérience cohérente. De plus, vous réduirez la charge de test car les fonctionnalités courantes ne nécessitent pas de nouveau test.

Dans cette section

• Lignes directrices de développement requises
• Directives de développement fortement encouragées
• Lignes directrices de développement consultatif

Ces directives ne se limitent à aucune langue (elles ne mentionnent pas de langue) et sont parfaitement applicables lors de l'écriture d'applets de commande dans PowerShell.

L'utilisation de ces instructions vous aidera à écrire des applets de commande claires, découvrables, utilisables et réutilisables. Je trouve qu'après avoir créé plusieurs modules PowerShell suivant ces lignes directrices n'est pas difficile, et m'a aidé à devenir un meilleur développeur PowerShell. Cette compétence est également directement utilisable lors de l'écriture de scripts simples.

Comme deuxième réponse; vous pouvez utiliser le module PSScriptAnalyzer pour valider votre code.

Invoke-ScriptAnalyzer -Path .

Il est basé sur l'analyse de code, à l'aide d'un ensemble de règles. Il validera la conception du code et vous aidera à détecter de nombreux petits problèmes dans votre code.

Nous l'avons incorporé dans nos builds (nous utilisons des builds et un référentiel privé pour les modules), afin d'attraper les problèmes de conception et de qualité.

Si vous êtes intéressé, ce module contient également un formateur de code PowerShell (qui peut utiliser plusieurs styles), vous pouvez donc l'utiliser pour normaliser la disposition du code.

Les documents contenus dans la réponse de @ o are sont une bonne source, quoique quelque peu tangentielle.

Si vous utilisez Visual Studio Code, qui est prévu pour remplacer le PowerShell ISE vieillissant, puis installez l' extension VS Code PowerShell , qui inclut plusieurs options de formatage qui étaient au moins partiellement basées sur le guide non officiel des meilleures pratiques et du style PowerShell . VS Code et l'extension PowerShell sont gérés par Microsoft, il est donc à peu près aussi officiel qu'un guide non officiel peut l'être.

Je ne suis pas d'accord avec tout ce qu'ils disent. Par exemple, je viens de PHP, Java, C # et SQL où des points-virgules sont attendus si ce n'est pas requis. Le code semble incorrect me sans eux, donc je les inclue. S'il y en avait un, #requires SemicolonTerminatorje l'activerais sur la plupart de mes scripts, donc je n'ai pas à me soucier de la coupure d'une ligne blanche. Je déteste échapper aux retours chariot et autres VB-ismes.

Les autres sont mon avis:

Utilisez le vrai nom ou l'alias de la cmdlet?

Soyez sans ambiguïté. N'utilisez jamais d'alias dans un script enregistré; même un alias par défaut. Rien n'empêche un utilisateur de modifier les alias par défaut. Il est plus sûr de supposer qu'ils ne sont pas immuables.

Spécifiez le nom du paramètre d'applet de commande en totalité ou seulement partiellement (dir -Recurse versus dir -r)

Encore une fois, soyez sans ambiguïté. Les noms de paramètres complets ont la meilleure compatibilité ascendante. -rpeut être sans ambiguïté aujourd'hui, mais rien n'empêche les futures versions d'une commande d'introduire de nouveaux paramètres. Vous allez utiliser un IDE (ISE ou VS Code). Appuyez sur Ctrl+ Spaceet complétez automatiquement ce paramètre.

Notez que ls -r c'est ambigu. -ReadOnlyest un autre paramètre de Get-ChildItem.

Lorsque vous spécifiez des arguments de chaîne pour les applets de commande, les placez-vous entre guillemets (New-Object 'System.Int32' contre New-Object System.Int32

En général, les guillemets ne doivent être utilisés que lorsque cela est nécessaire (par exemple New-Object -TypeName 'System.Collections.Generic.HashSet[System.Int32]'. Utilisez des guillemets simples lorsque vous le pouvez et uniquement des guillemets doubles lorsque vous devez encapsuler des guillemets simples ou intégrer des variables.

Lorsque vous écrivez des fonctions et des filtres, spécifiez-vous les types de paramètres?

Je le fais généralement, sauf si je dois spécifiquement accepter une grande variété de types avec le même paramètre et que je ne veux pas écrire d'ensembles de paramètres individuels.

Écrivez-vous des applets de commande dans le cas (officiel) correct?

Affaire Pascal. Oui.

Pour les mots clés comme COMMENCER ... PROCESSUS ... FIN les écrivez-vous uniquement en majuscules?

J'ai vu les déclarations, les opérateurs et les constructions de langage que Begin, If, ForEach, -NotInainsi que begin, if, foreach,-notin . Personnellement, je préfère les minuscules et laisse les commandes comme Pascal, mais elles sont toutes les deux également courantes.

Autres:

• Spécifiez toujours les paramètres. Ne vous fiez pas à l'ordre positionnel. New-Object -TypeName System.Int32fini New-Object System.Int32. Je ne sais pas si cela a été convenu, mais, encore une fois, cela semble soutenir l'idée générale de "ne pas être ambigu".

• Si j'écris un module, j'utilise des verbes standard indiqués par Get-Verb. Cette liste est cependant extrêmement étroite, donc les noms de script autonomes pour les scripts que moi-même exécuterai souvent ne le font pas. Le problème avec la liste de verbes générique est qu'elle tend vers Get-ScriptForSpecificPurposeNoNotThatOneTheOtherOne.ps1. Si j'écris un script qui extrait certaines pages d'un fichier PDF, je ne l'appelle pas Get-ExtractedAccountPDFPages.ps1. Je l'appelle Extract-AccountPDFPages.ps1. Je ne suis pas préoccupé par la découvrabilité d'un script qui s'exécute comme un programme lui-même et n'est pas destiné à être modulaire par sa nature même.

• Brisez les règles quand elles sont plus lisibles, plus concrètes ou plus faciles à maintenir.

Au fil des ans, il y a eu différentes façons d'écrire des noms de plusieurs mots pour des variables, des fonctions, etc.

PROGRAMFORSORTINGLOTSOFTHINGS est difficile à lire.

PROGRAM_FOR_SORTING_LOTS_OF_THINGS est un peu plus facile.

program_for_sorting_lots_of_things est encore plus facile.

ProgramForSortingLotsOfThings supprime le trait de soulignement et maintient la lisibilité. Powershell le fait pour la plupart.