Recommandations et bonnes pratiques de publication PowerShellGallery

  • Article

Cet article décrit les étapes recommandées utilisées par les équipes Microsoft pour s’assurer que les packages publiés dans PowerShell Gallery seront largement adoptés et fourniront une valeur élevée aux utilisateurs, en fonction de la façon dont PowerShell Gallery gère les données manifestes et des commentaires d’un grand nombre d’utilisateurs de PowerShell Gallery. Les packages publiés en suivant ces instructions seront plus susceptibles d’être installés, approuvés et d’attirer davantage d’utilisateurs.

Vous trouverez ci-dessous des instructions pour ce qui rend un bon package PowerShell Gallery, quels paramètres de manifeste facultatifs sont les plus importants, améliorant votre code avec des commentaires des réviseurs initiaux et PowerShell Script Analyzer, versioning de votre module, documentation, tests et exemples pour savoir comment utiliser ce que vous avez partagé. Une grande partie de cette documentation suit les instructions pour publier modules de ressources DSC de haute qualité.

Pour connaître la mécanique de la publication d’un package dans PowerShell Gallery, consultez Création et publication d’un package.

Les commentaires sur ces lignes directrices sont accueillis. Si vous avez des commentaires, ouvrez des problèmes dans notre référentiel de documentation GitHub.

Meilleures pratiques pour la publication de packages

Les meilleures pratiques suivantes sont ce que disent les utilisateurs des éléments PowerShell Gallery, et sont répertoriées dans l’ordre de priorité nominale. Les packages qui suivent ces instructions sont beaucoup plus susceptibles d’être téléchargés et adoptés par d’autres.

  • Utiliser PSScriptAnalyzer
  • Inclure la documentation et des exemples
  • Soyez réactif aux commentaires
  • Fournir des modules plutôt que des scripts
  • Fournir des liens vers un site de projet
  • Étiqueter votre package avec les plateformes et psEdition compatibles
  • Inclure des tests avec vos modules
  • Inclure et/ou lier des termes du contrat de licence
  • Signer votre code
  • Suivez les instructions SemVer pour le contrôle de version
  • Utiliser des balises courantes, comme documenté dans les balises Common PowerShell Gallery
  • Tester la publication à l’aide d’un référentiel local
  • Utiliser PowerShellGet pour publier

Chacune d’elles est abordée brièvement dans les sections ci-dessous.

Utiliser PSScriptAnalyzer

PSScriptAnalyzer est un outil d’analyse de code statique gratuit qui fonctionne sur du code PowerShell. PSScriptAnalyzer identifie les problèmes les plus courants rencontrés dans le code PowerShell, et il est souvent recommandé de résoudre le problème. L’outil est facile à utiliser et catégorise les problèmes en tant qu’erreurs (graves, doivent être résolus), Avertissement (doivent être examinés et doivent être résolus) et Informations (qui méritent d’être examinées pour connaître les meilleures pratiques). Tous les packages publiés dans PowerShell Gallery seront analysés à l’aide de psScriptAnalyzer, et toutes les erreurs seront signalées au propriétaire et doivent être traitées.

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

Passez en revue les résultats et vérifiez que :

  • Toutes les erreurs sont corrigées ou traitées dans votre documentation.
  • Tous les avertissements sont 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 à évaluer toutes les erreurs et avertissements. Les utilisateurs sont très susceptibles de contacter les propriétaires de package s’ils voient qu’il existe une erreur signalée par PSScriptAnalyzer. S’il existe une raison convaincante pour que votre package conserve le code marqué comme une erreur, ajoutez ces informations à votre documentation pour éviter d’avoir à répondre à la même question plusieurs fois.

Inclure la documentation et des exemples

La documentation et les exemples constituent la meilleure façon de s’assurer que les utilisateurs peuvent tirer parti de n’importe quel code partagé.

La documentation est la chose la plus utile à inclure dans les packages publiés dans PowerShell Gallery. Les utilisateurs contournent généralement les packages sans documentation, car l’alternative consiste à lire le code pour comprendre ce que le package est et comment l’utiliser. Il existe plusieurs articles sur la façon de fournir de la documentation avec des packages PowerShell, notamment :

  • Les instructions pour fournir de l’aide sont dans l’aide sur l’écriture d’applets de commande.
  • Création d’une aide sur les applets de commande, qui est la meilleure approche pour n’importe quel script, fonction ou applet de commande PowerShell. Pour plus d’informations sur la création de l’aide sur l’applet de commande, commencez par Comment écrire l’aide sur les applets de commande. Pour ajouter de l’aide dans un script, consultez À propos de l’aide basée sur les commentaires.
  • De nombreux modules incluent également la documentation au format texte, comme les fichiers MarkDown. Cela peut être particulièrement utile lorsqu’il existe un site de projet dans GitHub, où Markdown est un format fortement utilisé. La meilleure pratique consiste à utiliser MarkdowngitHub.

Les exemples montrent aux utilisateurs comment le package est destiné à être utilisé. De nombreux développeurs disent qu’ils examinent des exemples avant la documentation pour comprendre comment utiliser quelque chose. Les meilleurs types d’exemples montrent l’utilisation de base, ainsi qu’un cas d’usage réaliste simulé, et le code est bien commenté. Les exemples de modules publiés dans PowerShell Gallery doivent se trouver dans un dossier Exemples sous la racine du module.

Vous trouverez un bon modèle pour les exemples dans le module PSDscResource sous le dossier Examples\RegistryResource. Il existe quatre exemples de cas d’usage avec une brève description en haut de chaque fichier qui documente ce qui est démontré.

Gérer les dépendances

Il est important de spécifier les modules dont dépend votre module dans le manifeste du module. Cela permet à l’utilisateur final de ne pas avoir à vous soucier de l’installation des versions appropriées des modules dont vous êtes dépendant. Pour spécifier des modules dépendants, vous devez utiliser le champ de module requis dans le manifeste du module. Cela charge tous les modules répertorié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 autre module. Il est également possible de spécifier une version spécifique à charger à l’aide du champ RequiredVersion à l’aide du champ ModuleVersion. Lorsque vous utilisez ModuleVersion, il charge la version la plus récente disponible avec un minimum de 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 connaître les changements cassants susceptibles d’affecter 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 correctement aux commentaires sont très appréciés par la communauté. Les utilisateurs qui fournissent des commentaires constructifs sont importants pour répondre, car ils sont intéressés par le package pour essayer de l’améliorer.

Il existe une méthode de commentaires disponible dans PowerShell Gallery :

  • Propriétaire du contact : cela permet à un utilisateur d’envoyer un e-mail au propriétaire du package. En tant que propriétaire de package, il est important de surveiller l’adresse e-mail utilisée avec les packages PowerShell Gallery et de répondre aux problèmes déclenchés. L’un des inconvénients de cette méthode est que seul l’utilisateur et le propriétaire verront jamais la communication, de sorte que le propriétaire peut avoir à répondre à la même question plusieurs fois.

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 identifiez si une mise à jour résout un problème.

S’il existe un comportement inapproprié observé à partir de l’un de ces canaux de communication, utilisez la fonctionnalité Report Abuse de PowerShell Gallery pour contacter les administrateurs de la galerie.

Modules et scripts

Le partage d’un script avec d’autres utilisateurs est excellent et fournit d’autres exemples de résolution des problèmes qu’ils peuvent avoir. Le problème est que les scripts dans PowerShell Gallery sont des fichiers uniques sans documentation, exemples et tests distincts.

Les modules PowerShell ont une structure de dossiers qui permet à plusieurs dossiers et fichiers d’être inclus dans le package. La structure de module permet d’inclure les autres packages que nous listons comme meilleures pratiques : aide de l’applet de commande, documentation, exemples et tests. Le plus grand inconvénient est qu’un script à l’intérieur d’un module doit être exposé et utilisé comme fonction. Pour plus d’informations sur la création d’un module, consultez Écriture d’un module Windows PowerShell.

Il existe des situations où un script offre une meilleure expérience pour l’utilisateur, en particulier avec les configurations DSC. La meilleure pratique pour les configurations DSC consiste à publier la configuration en tant que script avec un module associé qui contient les documents, exemples et 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 autres meilleures pratiques fournissent une valeur réelle à d’autres utilisateurs. Fournir une documentation basée sur des commentaires et un lien vers un site de projet sont vivement recommandés lors de la publication d’un script dans PowerShell Gallery.

Un site de projet est l’emplacement où un éditeur peut interagir directement avec les utilisateurs de leurs packages PowerShell Gallery. Les utilisateurs préfèrent les packages qui fournissent cela, car il leur permet d’obtenir plus facilement des informations sur le package. De nombreux packages dans PowerShell Gallery sont développés dans GitHub, d’autres sont fournis par les organisations avec une présence web dédiée. Chacun d’eux peut être considéré comme un site de projet.

L’ajout d’un lien est effectué 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 fourni, PowerShell Gallery inclut un lien vers le site de projet situé à gauche de la page du package.

Étiqueter votre package avec les plateformes et psEdition compatibles

Utilisez les balises suivantes pour montrer aux utilisateurs quels packages fonctionnent bien 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

En étiquetant votre package 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 la recherche. Si vous hébergez votre package sur GitHub, lorsque vous balisez votre package, vous pouvez également tirer parti de nos boucliers de compatibilité PowerShell Galleryexemple de bouclier de compatibilité.

Inclure des tests

L’inclusion de tests avec du code open source est importante pour les utilisateurs, car il leur donne l’assurance de ce que vous validez et fournit des informations sur le fonctionnement de votre code. Il permet également aux utilisateurs de s’assurer qu’ils ne interrompent pas vos fonctionnalités d’origine s’ils modifient votre code pour qu’ils correspondent à leur environnement.

Il est fortement recommandé que les tests soient écrits pour tirer parti de l’infrastructure de test Pester, qui a été conçue spécifiquement pour PowerShell. Pester est disponible dans GitHub, le PowerShell Galleryet est fourni dans Windows 10, Windows Server 2016, WMF 5.0 et WMF 5.1.

Le site de projet pester dans GitHub inclut une documentation correcte sur l’écriture de tests Pester, de la prise en main aux meilleures pratiques.

Les cibles de couverture des tests sont appelées dans la documentation High Quality Resource Module, avec 70% couverture de code de test unitaire recommandée.

Tous les packages publiés dans 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 Exposition A. La meilleure approche pour spécifier une autre licence consiste à fournir un lien vers la licence à l’aide du LicenseURI dans PSData . Pour plus d’informations, consultez manifeste de packages et l’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 de code fournit aux utilisateurs le niveau d’assurance le plus élevé pour qui a publié le package et que la copie du code qu’ils acquiert est exactement ce que l’éditeur a publié. Pour en savoir plus sur la signature de code en général, consultez Présentation de la signature de code. PowerShell prend en charge la validation de la signature de code via deux approches principales :

  • Signature de fichiers de script
  • Catalogue de signature d’un module

La signature de fichiers PowerShell est une approche bien établie pour s’assurer que le code en cours d’exécution a été généré par une source fiable et n’a pas été modifié. Vous trouverez plus d’informations sur la façon de signer des fichiers de script PowerShell dans l’article À propos de la signature. Dans la vue d’ensemble, une signature peut être ajoutée à n’importe quel fichier .PS1 que PowerShell valide lorsque le script est chargé. PowerShell peut être limité à l’aide de la stratégie d’exécution applets de commande pour garantir l’utilisation de scripts signés.

Les modules de signature de catalogue sont une fonctionnalité ajoutée à PowerShell dans la version 5.1. Comment signer un module est abordé dans l’article des applets de commande du catalogue . Dans la vue d’ensemble, la signature de catalogue est effectuée en créant un fichier catalogue, qui contient une valeur de hachage pour chaque fichier du module, puis en signant ce fichier.

Les PowerShellGetPublish-Module, Install-Moduleet les applets de commande Update-Module vérifient que la signature est valide, puis vérifie que la valeur de hachage pour chaque package correspond à ce qui se trouve 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, Install-Module vérifie que l’autorité de signature pour la nouvelle version correspond à ce qui a été installé précédemment. Install-Module et Update-Module utilisera la signature sur un fichier .PSD1 si le package n’est pas signé. La signature de catalogue fonctionne avec, mais ne remplace pas les fichiers de script de signature. PowerShell ne valide pas les signatures de catalogue au moment du chargement du module.

Suivez les instructions SemVer pour le contrôle de version

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

  • La version doit être structurée en tant que trois blocs numériques séparés par des points, comme dans 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 production et que le premier nombre ne doit commencer que par 0 si c’est le seul nombre utilisé.
  • Les modifications apportées au premier nombre (1.9.9999 à 2.0.0) indiquent les changements majeurs et cassants entre les versions.
  • Les modifications apportées au deuxième nombre (1.1 à 1.2) indiquent les modifications au niveau des fonctionnalités, telles que l’ajout de nouvelles applets de commande à un module.
  • Les modifications apportées au troisième nombre indiquent des modifications non cassants, telles que de nouveaux paramètres, des exemples mis à jour ou de nouveaux tests.
  • Lors de la liste des versions, PowerShell trie les versions en tant que chaînes. Par conséquent, 1.01.0 sera traitée comme supérieure à 1.001.0.

PowerShell a été créé avant la publication de SemVer. Il fournit donc la prise en charge de la plupart des éléments de SemVer, en particulier :

  • Elle ne prend pas en charge les chaînes de préversion dans les numéros de version. Cela est utile lorsqu’un éditeur souhaite fournir une préversion d’une nouvelle version majeure après avoir fourni une version 1.0.0. Cela sera pris en charge dans une prochaine version de PowerShell Gallery et applets de commande PowerShellGet.
  • PowerShell et PowerShell Gallery autorisent les chaînes de version avec 1, 2 et 4 segments. De nombreux modules précoces n’ont pas suivi les instructions et les versions de produit de Microsoft incluent des informations de build sous la forme d’un 4ème bloc de nombres (par exemple, 5.1.14393.1066). Du point de vue du contrôle de version, ces différences sont ignorées.

Tester à l’aide d’un référentiel local

PowerShell Gallery n’est pas conçu pour être une cible pour tester le processus de publication. La meilleure façon de tester le processus de publication de bout en bout sur PowerShell Gallery consiste à configurer et à utiliser votre propre référentiel local. Cette opération peut être effectuée de plusieurs façons, notamment :

  • Configurez une instance PowerShell Gallery locale à l’aide du projet galerie privée PS dans GitHub. Ce projet en préversion vous aidera à configurer une instance de PowerShell Gallery que vous pouvez contrôler et à utiliser pour vos tests.
  • Configurez un dépôt Nuget interne . Cela nécessite davantage de travail à configurer, mais aura l’avantage de valider quelques exigences supplémentaires, notamment la validation de l’utilisation d’une clé API et la présence ou non de dépendances dans la cible lorsque vous publiez.
  • Configurez un partage de fichiers en tant que dépôt de test. Cela est facile à configurer, mais étant donné qu’il s’agit d’un partage de fichiers, les validations indiquées ci-dessus ne seront pas effectuées. Dans ce cas, l’un des avantages potentiels est que le partage de fichiers ne vérifie pas la clé API requise. Vous pouvez donc utiliser la même clé que celle que vous utiliseriez pour publier dans PowerShell Gallery.

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

Un point supplémentaire sur la publication de test : tout package que vous publiez dans PowerShell Gallery ne peut pas être supprimé sans aide de l’équipe des opérations, qui vérifie que rien ne dépend du package que vous souhaitez publier. Pour cette raison, nous ne prenons pas en charge PowerShell Gallery comme cible de test et contacterons tous les éditeurs qui le font.

Utiliser PowerShellGet pour publier

Il est fortement recommandé que les éditeurs utilisent les applets de commande Publish-Module et Publish-Script lors de l’utilisation de PowerShell Gallery. PowerShellGet a été créé pour vous aider à éviter de mémoriser des détails importants sur l’installation et la publication dans PowerShell Gallery. À l’occasion, les éditeurs ont choisi d’ignorer PowerShellGet et d’utiliser le client NuGet ou applets de commande PackageManagement, au lieu de . Il existe un certain nombre de détails qui sont facilement manqués, ce qui entraîne une variété de demandes de support.

S’il y a une raison pour laquelle vous ne pouvez pas utiliser Publish-Module ou Publish-Script, veuillez nous informer. Créez un problème dans le dépôt GitHub PowerShellGet et fournissez les détails qui vous amènent à choisir NuGet ou PackageManagement.

L’approche la plus réussie que nous avons trouvée pour les packages publiés dans PowerShell Gallery est la suivante :

  • Effectuez le 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 obtenir le code à l’état stable.
  • Incluez la documentation, afin que d’autres personnes sachent comment utiliser votre travail.
  • Testez l’action de publication à l’aide d’un référentiel local.
  • Publiez une version stable ou alpha dans PowerShell Gallery, en vous assurant d’inclure la documentation et de créer un lien vers votre site de projet.
  • Rassemblez 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 dans votre projet et votre module.
  • Déterminez si vous souhaitez coder le signe de votre package.
  • Lorsque vous pensez 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 à itérer sur votre code en fonction de l’entrée de l’utilisateur.