Instructions et bonnes pratiques de publication PowerShell Gallery

  • Article

Cet article décrit les étapes recommandées suivies par les équipes Microsoft pour garantir que les packages publiés sur PowerShell Gallery seront largement adoptés et seront sources de valeur ajoutée pour les utilisateurs, en fonction de la manière dont PowerShell Gallery gère les données de manifeste et des nombreux commentaires envoyés par les utilisateurs de PowerShell Gallery. Les packages publiés suivant ces recommandations ont plus de chances d’être installés, approuvés et plébiscités par les utilisateurs.

Voici des recommandations sur ce qui constitue un bon package PowerShell Gallery, les paramètres de manifeste facultatifs les plus importants, les moyens d’améliorer son code grâce aux commentaires des premiers réviseurs et aux informations fournies par l’analyseur de script PowerShell, le contrôle de version des modules, la documentation, les tests et les exemples pour apprendre à utiliser le package partagé. Une grande partie de cette documentation suit les instructions pour publier des modules de ressources DSC haute qualité.

Pour connaître le mécanisme de publication d’un package sur PowerShell Gallery, voir Créer et publier un package.

Les commentaires sur ces instructions sont les bienvenus. Si vous avez des commentaires, faites-le-nous savoir dans le dépôt de notre documentation GitHub.

Meilleures pratiques pour publier des packages

Les bonnes pratiques suivantes reflètent ce que les utilisateurs d’éléments de PowerShell Gallery jugent important, et sont répertoriées par ordre de priorité nominal. Les packages qui suivent ces recommandations ont beaucoup plus de chances d’être téléchargés et adoptés par d’autres d’utilisateurs.

  • Utiliser PSScriptAnalyzer
  • Inclure une documentation et des exemples
  • Répondre aux commentaires
  • Fournir des modules plutôt que des scripts
  • Fournir des liens vers un site de projet
  • Baliser votre package avec les plateformes et PSEdition(s) compatibles
  • Inclure des tests incluant vos modules
  • Inclure et/ou lier les termes du contrat de licence
  • Signer votre code
  • Suivre les instructions SemVer pour la gestion de versions
  • Utiliser des balises courantes, comme expliqué dans les balises courantes de PowerShell Gallery
  • Tester la publication à l’aide d’un dépôt local
  • Utiliser PowerShellGet pour publier

Chacun de ces points est brièvement présenté dans les sections ci-dessous.

Utiliser PSScriptAnalyzer

PSScriptAnalyzer est un outil d’analyse de code statique gratuit qui fonctionne sur le code PowerShell. PSScriptAnalyzer identifie les problèmes les plus courants dans le code PowerShell et fournit souvent une recommandation pour résoudre le problème. Cet outil est facile à utiliser et classe les problèmes en erreurs (graves, à corriger), avertissements (à examiner et à corriger) et informations (à examiner pour définir de bonnes pratiques). Tous les packages publiés sur PowerShell Gallery sont analysés avec PSScriptAnalyzer, et toutes les erreurs sont renvoyées au propriétaire, qui devra les corriger.

La meilleure pratique consiste à exécuter Invoke-ScriptAnalyzer avec -Recurse et un avertissement -Severity.

Examinez les résultats et vérifiez que :

  • Toutes les erreurs ont été corrigées ou traitées dans votre documentation.
  • Tous les avertissements ont été examinés et traités le cas échéant.

Les utilisateurs qui téléchargent des packages à partir de PowerShell Gallery sont fortement encouragés à exécuter PSScriptAnalyzer et à examiner toutes les erreurs et tous les avertissements. Ils contacteront très certainement les propriétaires des packages si PSScriptAnalyzer leur signale une erreur. S’il existe une raison valable pour que votre package conserve du code identifié comme une erreur, ajoutez ces informations à votre documentation pour éviter d’avoir à répondre plusieurs fois à la même question.

Inclure une documentation et des exemples

La meilleure façon de s’assurer que les utilisateurs tirent parti de n’importe quel code partagé est de leur fournir une documentation et des exemples.

La documentation est l’élément le plus utile à inclure dans les packages publiés sur PowerShell Gallery. Les utilisateurs ignorent généralement les packages sans documentation, afin d’éviter d’avoir à lire le code pour comprendre ce que le package représente et comment l’utiliser. Plusieurs articles expliquent comment ajouter de la documentation à des packages PowerShell, notamment :

Des exemples montrent comment utiliser le package. De nombreux développeurs préfèrent consulter la documentation pour comprendre comment utiliser un élément. Les meilleurs exemples montrent un cas d’utilisation basique, un cas d’utilisation réaliste simulé, et le code est bien commenté. Les exemples pour les modules publiés dans PowerShell Gallery doivent figurer dans le dossier Exemples à la racine du module.

Vous trouverez de bons exemples dans le module PSDscResource du dossier Examples\RegistryResource. Quatre exemples de cas d’utilisation sont disponibles avec, en haut de chaque fichier, une brève description des éléments présentés.

Gérer les dépendances

Il est important de spécifier les modules dont dépend votre module dans le manifeste de module. Cela permet à l’utilisateur final de ne pas avoir à se soucier de l’installation des versions appropriées des modules sur lesquels le vôtre a une dépendance. Pour spécifier des modules dépendants, vous devez utiliser le champ de module requis dans le manifeste de module. Cela a pour effet de charger tous les modules listés dans l’environnement global avant d’importer votre module, sauf s’ils ont déjà été chargés. Par exemple, certains modules peuvent déjà être chargés par un module différent. Il est également possible de spécifier une version spécifique à charger à l’aide du champ RequiredVersion plutôt que du champ ModuleVersion. Lors de l’utilisation de ModuleVersion, la dernière version disponible est chargée au minimum la version spécifiée. Lorsque vous n’utilisez pas le champ RequiredVersion pour spécifier une version spécifique, il est important de surveiller les mises à jour de version du module requis. Il est particulièrement important de tenir compte de toutes les modifications avec rupture susceptibles d’avoir une incidence sur l’expérience utilisateur avec votre module.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Répondre aux commentaires

Les propriétaires de packages qui répondent convenablement aux commentaires sont très appréciés de la communauté. Il est important de répondre aux utilisateurs qui apportent des commentaires constructifs, car ces derniers se montrent suffisamment intéressés par le package pour aider à l’améliorer.

PowerShell Gallery propose une méthode pour fournir des commentaires :

  • Contacter le propriétaire : les utilisateurs peuvent ainsi envoyer un e-mail au propriétaire du package. Il est important pour ce dernier de surveiller le compte de messagerie utilisé avec les packages PowerShell Gallery et de répondre aux problèmes soulevés. L’un des inconvénients de cette méthode est que seul l’utilisateur et propriétaire verra la communication et il risque donc de répondre plusieurs fois à la même question.

Les propriétaires qui répondent de manière constructive aux commentaires sont appréciés par la communauté. Utilisez l’opportunité dans le rapport pour demander plus d’informations. Si nécessaire, fournissez une solution de contournement ou déterminez si une mise à jour résout un problème.

Si vous constatez un comportement inapproprié sur l’un de ces canaux de communication, utilisez la fonctionnalité Signaler un abus de PowerShell Gallery pour contacter les administrateurs.

Différences entre les modules et les scripts

Partager un script avec d’autres utilisateurs est une excellente idée qui leur offre d’autres exemples montrant comment résoudre les problèmes qu’ils peuvent rencontrer. Le problème est que les scripts de PowerShell Gallery sont des fichiers sans documentation, exemples ou tests distincts.

Les Modules PowerShell ont une structure de dossiers qui permet d’inclure plusieurs dossiers et fichiers dans le package. La structure du module permet d’inclure les autres packages que nous avons présentés parmi les meilleures pratiques : aide sur la cmdlet, documentation, exemples et tests. Le principal inconvénient est qu’un script situé à l’intérieur d’un module doit être exposé et utilisé en tant que fonction. Pour plus d’informations sur la création d’un module, voir Écrire un module Windows PowerShell.

Il existe des situations où un script fournit une meilleure expérience à l’utilisateur, en particulier avec les configurations DSC. Pour les configurations DSC, la meilleure solution consiste à publier la configuration en tant que script avec un module connexe contenant les documents, les exemples et les tests. Le script répertorie le module associé à l’aide de RequiredModules = @(Name of the Module). Cette approche peut être utilisée avec n’importe quel script.

Les scripts autonomes qui suivent les bonnes pratiques apportent une vraie valeur à d’autres utilisateurs. Il est vivement recommandé de fournir une documentation basée sur des commentaires ainsi qu’un lien vers un site de projet lorsque vous publiez un script dans PowerShell Gallery.

C’est sur le Site de projets que l’éditeur peut interagir directement avec les utilisateurs de ses packages PowerShell Gallery. Les utilisateurs préfèrent les packages qui possèdent un Site de projets, car c’est pour eux le moyen d’obtenir plus facilement des informations sur les packages. De nombreux packages de PowerShell Gallery sont développés sur GitHub, tandis que d’autres sont fournis par des organisations qui possèdent une présence web dédiée. Dans les deux cas, il s’agit d’un site de projet.

L’ajout d’un lien s’effectue en incluant ProjectURI dans la section PSData du manifeste, comme suit :

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Lorsqu’un ProjectURI est indiqué, PowerShell Gallery inclut un lien vers le Site de projets sur le côté gauche de la page du package.

Baliser votre package avec les plateformes et PSEdition(s) compatibles

Utilisez les balises suivantes pour montrer aux utilisateurs quels packages fonctionneront correctement avec leur environnement :

  • PSEdition_Desktop : packages compatibles avec Windows PowerShell
  • PSEdition_Core : packages compatibles avec PowerShell 6 et versions ultérieures
  • Windows : packages compatibles avec le système d’exploitation Windows
  • Linux : packages compatibles avec les systèmes d’exploitation Linux
  • MacOS : packages compatibles avec le système d’exploitation Mac

Si votre package est balisé avec la ou les plateformes compatibles, il sera inclus dans les filtres de recherche de la galerie dans le volet gauche des résultats de recherche. Si vous hébergez votre package sur GitHub, quand vous l’étiquetez, vous pouvez aussi bénéficier de nos protections de compatibilité PowerShell Galleryexemple de protection de compatibilité.

Inclure des tests

Il est important de proposer aux utilisateurs des tests avec un code open source car cela leur fournit des garanties sur le contenu que vous validez ainsi que des informations sur le fonctionne de votre code. Cela permet également aux utilisateurs de s’assurer qu’ils ne bloquent pas votre fonctionnalité d’origine lorsqu’ils modifient votre code pour l’adapter à leur environnement.

Il est fortement recommandé d’écrire des tests qui tirent parti de l’infrastructure de test Pester, qui a été spécialement conçue pour PowerShell. Pester est disponible dans GitHub, dans PowerShell Gallery, et est inclut avec Windows 10, Windows Server 2016, WMF 5.0 et WMF 5.1.

Le site du projet Pester dans GitHub comprend une bonne documentation sur l’écriture de tests de Pester, du démarrage aux bonnes pratiques.

Les cibles pour la couverture de test sont appelées dans la documentation du module de ressources haute qualité, avec une recommandation de couverture du code de test de 70 %.

Tous les packages publiés sur PowerShell Gallery doivent spécifier les termes du contrat de licence ou être liés par la licence incluse dans les Conditions d’utilisation, sous Annexe A. La meilleure approche pour spécifier une autre licence consiste à fournir un lien vers la licence à l’aide de LicenseURI dans PSData. Pour plus d’informations, consultez Manifeste de packages et interface utilisateur de la galerie.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Signer votre code

La signature du code offre aux utilisateurs le niveau le plus élevé d’assurance concernant l’éditeur du package, et leur garantit que la copie du code qu’ils acquièrent correspond exactement à ce que ce dernier a publié. Pour en savoir plus sur la signature du code en général, voir Introduction à la signature du code. PowerShell prend en charge la validation de la signature du code via deux approches :

  • Signature des fichiers de script
  • Signature d’un module par un catalogue

La signature des fichiers PowerShell est une approche parfaitement établie pour garantir que le code en cours d’exécution a été produit par une source fiable et n’a pas été modifié. Pour plus d’informations sur la façon de signer des fichiers de script PowerShell, voir l’article À propose de la signature. Pour résumer, une signature peut être ajoutée à tout fichier .PS1 validé par PowerShell lorsque le script est chargé. PowerShell peut être contraint à utiliser les applets de commande de la stratégie d’exécution pour forcer l’utilisation de scripts signés.

La signature de modules par un catalogue est une fonctionnalité ajoutée à la version 5.1 de PowerShell. La signature d’un module est abordée dans l’article Applets de commande de catalogue. Pour résumer, la signature du catalogue s’effectue en créant un fichier de catalogue contenant une valeur de hachage pour chaque fichier dans le module, puis en signant ce fichier.

Les cmdlets PowerShellGetPublish-Module, Install-Module et Update-Module vérifient la validité de la signature, puis confirment que la valeur de hachage de chaque package correspond à ce qui figure dans le catalogue. Save-Module ne valide pas une signature. Si une version précédente du module est installée sur le système, l’applet de commande Install-Module confirmera que l’autorité de signature de la nouvelle version correspond à ce qui a été précédemment installé. Install-Module et Update-Module utiliseront la signature sur un fichier .PSD1 si le package n’est pas signé par le catalogue. La signature du catalogue complète mais ne remplace pas la signature des fichiers de script. PowerShell ne valide pas les signatures du catalogue lors du chargement du module.

Suivre les instructions SemVer pour la gestion de versions

SemVer est une convention publique qui explique comment structurer et changer une version pour faciliter l’interprétation des modifications. La version de votre package doit être incluse dans les données de manifeste.

  • La version doit être structurée sous forme de trois blocs numériques séparés par des points, par exemple 0.1.1 ou 4.11.192.
  • Les versions commençant par 0 indiquent que le package n’est pas encore prêt pour la mise en production ; le premier numéro doit commencer par 0 uniquement s’il s’agit du seul numéro utilisé.
  • Les modifications dans le premier numéro (1.9.9999 à 2.0.0) indiquent des modifications majeures et importantes entre les versions.
  • Les modifications du second numéro (1.1 à 1.2) indiquent une évolution des fonctionnalités, par exemple, l’ajout de nouvelles cmdlets à un module.
  • Les modifications dans le troisième numéro indiquent des modifications mineures, par exemple de nouveaux paramètres, des exemples mis à jour ou de nouveaux tests.
  • Pour répertorier les versions, PowerShell trie les versions sous forme de chaînes, par conséquent 1.01.0 sera considéré comme étant supérieur à 1.001.0.

Comme PowerShell a été créé avant la publication de SemVer, il prend en charge la plupart mais pas tous les éléments de SemVer, en particulier :

  • Il ne prend pas en charge les chaînes préliminaires dans les numéros de version. Cela est utile lorsqu’un éditeur souhaite fournir une version préliminaire d’une nouvelle version majeure après avoir fourni une version 1.0.0. Cette opération est prise en charge dans une version ultérieure des applets de commande PowerShell Gallery et PowerShellGet.
  • PowerShell et PowerShell Gallery acceptent des chaînes de version contenant 1, 2 et 4 segments. De nombreux modules précédents ne suivaient pas ces instructions, et les versions de produit publiées par Microsoft incluent des informations de build sous forme de blocs à 4 éléments (par exemple 5.1.14393.1066). Du point de vue de la gestion de versions, ces différences sont ignorées.

Tester à l’aide d’un dépôt local

PowerShell Gallery n’est pas conçu pour être une cible servant à tester le processus de publication. La meilleure façon de tester le processus de publication de bout en bout dans PowerShell Gallery consiste à configurer et à utiliser votre propre dépôt local. Vous pouvez effectuer ces opérations de différentes manières, notamment :

  • Configurez une instance locale de PowerShell Gallery avec le projet PS Private Gallery dans GitHub. Ce projet en préversion vous permet de configurer une instance de PowerShell Gallery que vous pouvez contrôler, puis de l’utiliser pour vos tests.
  • Configurez un dépôt Nuget interne. Cette configuration demande plus de travail mais a l’avantage de valider quelques éléments requis supplémentaires, notamment la validation de l’utilisation d’une clé API et la présence ou non de dépendances dans la cible lors de la publication.
  • Configurez un partage de fichiers en tant que dépôt de test. Cette configuration est facile, mais comme il s’agit d’un partage de fichiers, les validations indiquées ci-dessus n’existent pas. Un avantage potentiel ici est que le partage de fichiers ne vérifie pas la clé API obligatoire, donc vous pouvez utiliser la même clé pour publier dans PowerShell Gallery.

Avec l’une de ces solutions, utilisez Register-PSRepository pour définir un nouveau dépôt, que vous utilisez dans le paramètre -Repository pour Publish-Module.

Autre point sur la publication de test : il n’est pas possible de supprimer les packages publiés sur PowerShell Gallery sans l’aide de l’équipe des opérations, qui doit confirmer que rien ne dépend du package en question. Pour cette raison, nous ne prenons pas en charge PowerShell Gallery comme cible de test. Nous contacterons un éditeur qui assure cette prise en charge.

Utiliser PowerShellGet pour publier

Il est fortement recommandé aux éditeurs d’utiliser les applets de commande Publish-Module et Publish-Script avec PowerShell Gallery. PowerShellGet a été créé pour vous éviter d’avoir à retenir certains détails importants au sujet de l’installation et de la publication sur PowerShell Gallery. À certaines occasions, les éditeurs ont choisi d’ignorer PowerShellGet pour utiliser le client NuGet ou les applets de commande PackageManagement à la place de Publish-Module. Il est facile d’oublier certains détails, ce qui donne lieu à diverses demandes de support.

Si vous ne pouvez pas utiliser Publish-Module ou Publish-Script, faites-le nous savoir. Signalez un problème dans le dépôt GitHub de PowerShellGet et dites-nous ce qui vous a amené à opter pour NuGet ou PackageManagement.

L’approche la plus efficace que nous ayons trouvée pour les packages publiés sur PowerShell Gallery est la suivante :

  • Effectuez un développement initial dans un site de projet open source. L’équipe PowerShell utilise GitHub.
  • Utilisez les commentaires des réviseurs et l’analyseur de script Powershell pour amener le code à un état stable.
  • Incluez une documentation afin que d’autres utilisateurs puissent profiter de votre travail.
  • Tester l’action de publication à l’aide d’un dépôt local.
  • Publiez une version stable ou une version alpha dans PowerShell Gallery, en veillant à inclure la documentation et un lien vers votre site de projet.
  • Recueillez des commentaires et effectuez une itération sur le code dans votre site de projet, puis publiez des mises à jour stables dans PowerShell Gallery.
  • Ajoutez des exemples et des tests Pester à votre projet et votre module.
  • Décidez de signer ou non le code de votre package.
  • Lorsque vous estimez que le projet est prêt à être utilisé dans un environnement de production, publiez une version 1.0.0 dans PowerShell Gallery.
  • Continuez à recueillir des commentaires et effectuez une itération sur votre code en fonction des entrées utilisateur.