Valeurs des métadonnées de package qui impactent l’interface utilisateur de PowerShell Gallery

Cet article explique comment les métadonnées de vos packages sont utilisées par PowerShell Gallery. Pour les modules, les métadonnées sont stockées dans le manifeste du module. Pour les scripts, les métadonnées sont stockées en utilisant des mots clés basés sur des commentaires. Les cmdlets suivantes sont utilisées pour créer ou mettre à jour ces métadonnées :

• New-ModuleManifest
• Update-ModuleManifest
• New-ScriptFileInfo
• Update-ScriptFileInfo

Éléments des fonctionnalités PowerShell Gallery contrôlés par le manifeste du module

La liste suivante montre les éléments de l’interface utilisateur de la page des packages de PowerShell Gallery qui sont contrôlés par le manifeste du module.

• Titre : le nom du package publié dans la galerie.

• Version : la version affichée est la chaîne de version dans les métadonnées ainsi qu’une étiquette de préversion si elle est spécifiée. La chaîne de préversion spécifiée est ajoutée à ModuleVersion. Pour plus d’informations sur les chaînes de préversion dans les modules, consultez Versions de module en préversion.

• Description : il s’agit de la Description dans le manifeste du module.

• Exiger l’acceptation de la licence : un module peut obliger l’utilisateur à accepter une licence en définissant RequireLicenseAcceptance = $true, en fournissant une LicenseURI et en fournissant un fichier license.txt à la racine du dossier du module. Pour plus d’informations, consultez Exiger l’acceptation de la licence.

• Notes de publication : ces informations proviennent de la section ReleaseNotes, sous PSData\PrivateData.

• Propriétaires : les propriétaires sont constitués de la liste des utilisateurs dans PowerShell Gallery qui peuvent mettre à jour un package. La liste des propriétaires n’est pas incluse dans le manifeste du package. Une documentation supplémentaire explique comment gérer les propriétaires de l’élément.

• Auteur : ceci est inclus dans le manifeste du module en tant que Author. Le champ Auteur est souvent utilisé pour spécifier une société ou organisation associée à un package.

• Copyright : il s’agit du champ Copyright dans le manifeste du module.

• FileList : la liste des fichiers est créée quand le package est publié dans PowerShell Gallery. Elle n’est pas contrôlable par les informations du manifeste. PowerShell Gallery crée un fichier .nuspec qui apparaît dans la liste de fichiers de chaque package. Ce fichier n’est pas installé avec le package sur un système. C’est le manifeste du package NuGet pour le package, et il peut être ignoré.

• Étiquettes : les étiquettes sont incluses sous PrivateData\PSData dans le manifeste du module. Les étiquettes ont des exigences et des significations spécifiques qui sont décrites dans la section Détails des étiquettes.

• Cmdlets : ceci est fourni dans le manifeste du module via CmdletsToExport. C’est une bonne pratique de lister explicitement les noms des cmdlets au lieu d’utiliser le caractère générique *. L’existence d’une liste améliore les performances du module de chargement.

• Fonctions : Ceci est fourni dans le manifeste du module via FunctionsToExport. C’est une bonne pratique de lister explicitement les noms des cmdlets au lieu d’utiliser le caractère générique *. L’existence d’une liste améliore les performances du module de chargement.

• Ressources DSC : ceci est fourni dans le manifeste via DscResourcesToExport. Cette valeur est prise en charge seulement pour les modules dans PowerShell 5.0 et ultérieur.

• Fonctionnalités des rôles : les rôles sont listés quand le module a un ou plusieurs fichiers de fonctionnalités des rôles (.psrc). Ces fichiers sont utilisés par JEA. Pour plus d’informations, consultez Fonctionnalités des rôles.

• Éditions PowerShell : pour les modules conçus pour PowerShell 5.0 et antérieurs, ceci est contrôlé en utilisant des Étiquettes. Pour un système de type bureau (Desktop), utilisez la balise PSEdition_Desktop, et pour un système de base (Core), utilisez la balise PSEdition_Core. Pour les modules conçus pour PowerShell 5.1 et ultérieur, il existe une clé CompatiblePSEditions dans le manifeste. Pour plus d’informations, consultez Prise en charge de PSEdition pour les modules.

• Dépendances : ceci est fourni dans le manifeste via RequiredModules.

• Version minimale de PowerShell : ceci est fourni dans le manifeste via PowerShellVersion.

• Historique des versions : montre une liste des versions du module qui ont été publiées dans la galerie. Les packages masqués en utilisant la fonctionnalité Supprimer ne sont pas affichés dans l’historique des versions, sauf si vous êtes propriétaire du package.

• Site du projet : le site du projet est fourni pour les modules dans la section PrivateData\PSData du manifeste du module en spécifiant une ProjectURI.

• Licence : Un lien de licence est fourni pour les modules dans la section PrivateData\PSData du manifeste du module en spécifiant une LicenseURI.

  Important

  Si une licence n’est pas fournie via LicenseURI ou dans le package, les conditions d’utilisation de PowerShell Gallery s’appliquent au package. Pour plus d’informations, consultez les Conditions d’utilisation.

• Icône : un lien est fourni pour les modules dans la section PrivateData\PSData du manifeste du module en spécifiant une IconURI. L’URI doit pointer vers une image de 85 x 85 avec un arrière-plan transparent. L’URI doit être un lien direct vers le fichier image et ne doit pas accéder à une page web ou à un fichier du package PowerShell Gallery.

Éléments des fonctionnalités PowerShell Gallery contrôlés par les métadonnées de script

La liste suivante montre les éléments de l’interface utilisateur de la page des packages de PowerShell Gallery qui sont contrôlés par les métadonnées basées sur des commentaires dans un fichier de script.

• Titre : c’est le nom du package publié dans la galerie

• Version : la version affichée est la chaîne de version dans les métadonnées ainsi qu’une étiquette de préversion si elle est spécifiée. La valeur provient du mot clé .VERSION dans le bloc de commentaire des métadonnées. Lors de la publication du script de préversion, ajoutez la chaîne de préversion à la version. Pour plus d’informations sur la spécification de chaînes de préversion dans les modules, consultez Préversions des scripts.

• Description : ces informations proviennent du mot clé .DESCRIPTION dans l’aide basée sur les commentaires d’un fichier de script.

• Exiger l’acceptation de la licence : l’acceptation de licence n’est pas prise en charge pour les scripts. Cependant, le scénario où un script dépend d’un module qui exige l’acceptation de la licence est pris en charge. Pour plus d’informations, consultez Exiger l’acceptation des licences pour les scripts.

• Notes de publication : ces informations proviennent du mot clé .RELEASENOTES dans les métadonnées basées sur les commentaires d’un fichier de script.

• Propriétaires : les propriétaires sont constitués de la liste des utilisateurs dans PowerShell Gallery qui peuvent mettre à jour un package. La liste des propriétaires n’est pas incluse dans le manifeste du package. Pour plus d’informations, consultez Gérer les propriétaires d’éléments.

• Auteur : cette information provient du mot clé .AUTHOR dans les métadonnées basées sur les commentaires d’un fichier de script. Le champ Auteur est souvent utilisé pour spécifier une société ou organisation associée à un package.

• Copyright : cette information provient du mot clé .COPYRIGHT dans les métadonnées basées sur les commentaires d’un fichier de script.

• FileList : la liste des fichiers est créée quand le package est publié dans PowerShell Gallery. Elle n’est pas contrôlable par les informations du manifeste. PowerShell Gallery crée un fichier .nuspec qui apparaît dans la liste de fichiers de chaque package. Ce fichier n’est pas installé avec le package sur un système. C’est le manifeste du package NuGet pour le package, et il peut être ignoré.

• Étiquettes : *cette information provient du mot clé .TAGS dans les métadonnées basées sur les commentaires d’un fichier de script. Les étiquettes ont des exigences et des significations spécifiques qui sont décrites dans la section Détails des étiquettes.

• Éditions PowerShell : pour les modules conçus pour PowerShell 5.0 et antérieurs, ceci est contrôlé en utilisant des Étiquettes. Pour un système de type bureau (Desktop), utilisez la balise PSEdition_Desktop, et pour un système de base (Core), utilisez la balise PSEdition_Core. Pour les modules conçus pour PowerShell 5.1 et ultérieur, il existe une clé CompatiblePSEditions dans le manifeste. Pour plus d’informations, consultez Prise en charge de PSEdition pour les modules.

• Historique des versions : montre une liste des versions du module qui ont été publiées dans la galerie. Les packages masqués en utilisant la fonctionnalité Supprimer ne sont pas affichés dans l’historique des versions, sauf si vous êtes propriétaire du package.

• Site du projet : cette information provient du mot clé .PROJECTURI dans les métadonnées basées sur les commentaires d’un fichier de script.

• Licence : cette information provient du mot clé .LICENSEURI dans les métadonnées basées sur les commentaires d’un fichier de script.

  Important

  Si une licence n’est pas fournie via la .LICENSEURI ou dans le package, les conditions d’utilisation de PowerShell Gallery s’appliquent au package. Pour plus d’informations, consultez les Conditions d’utilisation.

• Icône : cette information provient du mot clé .ICONURI dans les métadonnées basées sur les commentaires d’un fichier de script. L’URI doit pointer vers une image de 85 x 85 avec un arrière-plan transparent. L’URI doit être un lien direct vers le fichier image et ne doit pas accéder à une page web ou à un fichier du package PowerShell Gallery.

Modification des détails du package

La page de modification du package dans PowerShell Gallery permet aux éditeurs de modifier certains des champs affichés pour un package, en particulier :

• Intitulé
• Description
• Résumé
• URL de l'icône
• URL de la page d’accueil du projet
• Auteurs
• copyright
• Balises
• Notes de publication
• Exiger une licence

Vous devez modifier ces informations seulement dans la galerie pour corriger ce qui s’affiche pour une version antérieure d’un module. Les utilisateurs qui téléchargent le package voient que les métadonnées ne correspondent pas à PowerShell Gallery. Chaque fois que vous modifiez des informations dans la galerie, vous devez publier une nouvelle version du package avec les mêmes modifications.

Détails des étiquettes

Les balises sont de simples chaînes permettant aux utilisateurs de rechercher des packages. Les étiquettes ont plus de valeur ajoutée quand elles sont utilisées de façon cohérente entre les packages associés. L’utilisation de variations du même mot, par exemple donnée et données, ou test et tester, offre peu d’avantages. Les étiquettes sont des chaînes constituées d’un seul mot respectant la casse, et elles ne peuvent pas inclure d’espaces. Si vous pensez qu’une expression fera l’objet de nombreuses recherches, ajoutez-la à la description du package afin qu’elle apparaisse dans les résultats de la recherche. Utilisez la casse Pascal, des traits d’union, des traits de soulignement ou des points pour améliorer la lisibilité. Évitez les balises longues, complexes et inhabituelles, car elles peuvent facilement être mal orthographiées.

PowerShell Gallery et les cmdlets PowerShellGet ont des significations spéciales pour les étiquettes PSEdition_Desktop et PSEdition_Core. Consultez la présentation précédente des éditions de PowerShell.

Comme indiqué précédemment, les étiquettes sont particulièrement utiles quand elles sont spécifiques et qu’elles utilisées de façon cohérente entre plusieurs packages. Quand un éditeur recherche les meilleures balises à utiliser, l’approche la plus simple consiste à rechercher ces balises dans PowerShell Gallery. Dans l’idéal, les packages retournés s’alignent avec votre utilisation de ce mot clé.

Le tableau suivant montre quelques-unes des étiquettes les plus couramment utilisées. L’étiquette préférée doit retourner les meilleurs résultats de recherche.