Créer votre manifeste de package

  • Article

Si vous voulez soumettre un package logiciel au dépôt du Gestionnaire de package Windows, commencez par créer un manifeste de package. Le manifeste est un fichier YAML qui décrit l’application à installer.

Vous pouvez utiliser Windows Package Manager Manifest Creator ou le script PowerShell YAMLCreate, ou créer un manifeste manuellement en suivant les instructions ci-dessous.

Notes

Consultez le FAQ sur le manifeste ci-dessous pour obtenir des informations générales expliquant les manifestes, les packages et les versions.

Options de création de manifeste

Utilisation de l’utilitaire WinGetCreate

Vous pouvez installer l’utilitaire wingetcreate à l’aide de la commande ci-dessous.

winget install wingetcreate

Après l’installation, vous pouvez exécuter wingetcreate new pour créer un nouveau package et remplir les invites. La dernière option proposée par l’invite WinGetCreate vous permet d’envoyer le manifeste au dépôt de packages. Si vous choisissez Oui, vous enverrez automatiquement votre demande de tirage (pull request) au dépôt Community du Gestionnaire de package Windows.

Utilisation de YAMLCreate.ps1

Pour faciliter la création des fichiers manifestes, nous fournissons le script PowerShell YAMLCreate.ps1 qui se trouve dans le dossier Tools du dépôt Community du Gestionnaire de package Windows. Vous pouvez utiliser le script en clonant le dépôt sur votre ordinateur, puis exécuter le script directement à partir du dossier Tools. Le script vous invite à entrer l’URL du programme d’installation, puis à renseigner les métadonnées. Comme pour l’utilisation de WinGetCreate, ce script offre la possibilité d’envoyer automatiquement votre manifeste.

Notions de base concernant YAML

Le format YAML a été choisi pour les manifestes de packages parce qu’il est relativement facile à lire et cohérent avec d’autres outils de développement Microsoft. Si vous ne connaissez pas la syntaxe YAML, vous pouvez découvrir les principes fondamentaux sur le site Learn YAML in Y Minutes.

Notes

Les manifestes pour le Gestionnaire de package Windows ne prennent actuellement pas en charge toutes les fonctionnalités YAML. Les fonctionnalités YAML non prises en charge incluent les ancres, les clés complexes et les jeux.

Conventions

Ces conventions sont utilisées dans cet article :

  • À gauche de : figure un mot clé littéral utilisé dans les définitions de manifeste.
  • À droite de : figure un type de données. Le type de données peut être un type primitif, par exemple une chaîne ou une référence à une structure riche définie ailleurs dans cet article.
  • La notation [type_de_données] indique un tableau du type de données mentionné. Par exemple, [ string ] est un tableau de chaînes.
  • La notation {type_de_données:type_de_données} indique un mappage entre deux types de données. Par exemple, { string: string } est une correspondance de chaînes à chaînes.

Contenu du manifeste

Un manifeste de package comprend un ensemble d’éléments obligatoires et d’autres éléments facultatifs susceptibles d’aider à améliorer l’expérience d’installation de votre logiciel par le client. Cette section fournit un résumé succinct du schéma de manifeste obligatoire et des schémas de manifeste complets, ainsi que des exemples de chacun d’eux.

Chaque champ du fichier manifeste doit être en « Pascal case » (première lettre de chaque mot en majuscule) et ne peut pas être dupliqué.

Pour obtenir une liste complète et une description des éléments d’un manifeste, consultez la spécification du manifeste dans le dépôt de communauté Gestionnaire de package Windows.

Schéma obligatoire minimal

Comme spécifié dans le schéma JSON singleton, seuls certains champs sont requis. Le fichier YAML minimal pris en charge doit ressembler à l’exemple ci-dessous. Le format singleton est valide uniquement pour les packages contenant un seul programme d’installation et un seul paramètre régional. Si plusieurs programmes d’installation ou paramètres régionaux sont fournis, le format et le schéma de fichier YAML multiples doivent être utilisés.

Le schéma de partitionnement a été ajouté pour faciliter l’expérience utilisateur de GitHub. Les dossiers avec des milliers d’enfants ne s’affichent pas correctement dans le navigateur.

PackageIdentifier:  # Publisher.package format.
PackageVersion:     # Version numbering format.
PackageLocale:      # BCP 47 format (e.g. en-US)
Publisher:          # The name of the publisher.
PackageName:        # The name of the application.
License:            # The license of the application.
ShortDescription:   # The description of the application.
Installers: 
 - Architecture:    # Enumeration of supported architectures.
   InstallerType:   # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx).
   InstallerUrl:    # Path to download installation file.
   InstallerSha256: # SHA256 calculated from installer.
ManifestType:       # The manifest file type
ManifestVersion: 1.6.0

Fichiers manifeste multiples

Pour offrir la meilleure expérience utilisateur, les manifestes doivent contenir autant de métadonnées que possible. Afin de séparer les problèmes de validation des programmes d’installation et de fourniture de métadonnées localisées, les manifestes doivent être fractionnés en plusieurs fichiers. Le nombre minimal de fichiers YAML pour ce type de manifeste est de trois. Des paramètres régionaux supplémentaires doivent également être fournis.

L’exemple ci-dessous montre de nombreux champs de métadonnées facultatifs et plusieurs paramètres régionaux. Notez que les paramètres régionaux par défaut ont plus d’exigences que les paramètres régionaux supplémentaires. Dans la commande show, les champs obligatoires qui ne sont pas fournis pour des paramètres régionaux supplémentaires affichent les champs des paramètres régionaux par défaut.

Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml

PackageIdentifier: "Microsoft.WindowsTerminal"
PackageVersion: "1.6.10571.0"
DefaultLocale: "en-US"
ManifestType: "version"
ManifestVersion: "1.6.0"

Notes

Si votre programme d’installation est un fichier .exe qui a été créé à l’aide de Nullsoft ou Inno, vous pouvez spécifier ces valeurs à la place. Quand Nullsoft ou Inno sont spécifiés, le client définit automatiquement les comportements Installation sans assistance et Installation sans assistance avec progression pour le programme d’installation.

Commutateurs de programme d’installation

Vous pouvez souvent déterminer quels sont les commutateurs (Switches) silencieux disponibles pour un programme d’installation en transmettant un -? au programme d’installation à partir de la ligne de commande. Voici quelques Switches silencieux courants qui peuvent être utilisés pour différents types de programme d’installation.

Programme d’installation Commande Documentation
MSI /q Options de ligne de commande MSI
InstallShield /s Paramètres de ligne de commande InstallShield
Inno Setup /SILENT or /VERYSILENT Documentation Inno Setup
Nullsoft /S Programmes d’installation/de désinstallation sans assistance Nullsoft

Conseils et bonnes pratiques

  • L’identificateur de package doit être unique. Vous ne pouvez pas avoir plusieurs envois avec le même identificateur de package. Une seule requête de tirage par version de package est autorisée.
  • Évitez de créer plusieurs dossiers d’éditeur. Par exemple, ne créez pas « Contoso Ltd. » s’il existe déjà un dossier « Contoso ».
  • Tous les outils doivent prendre en charge une installation sans assistance. Si vous disposez d’un fichier exécutable qui ne prend pas en charge une installation sans assistance, nous ne pouvons pas fournir cet outil pour l’instant.
  • Indiquez autant de champs que possible. Plus vous fournissez de métadonnées, plus l’expérience utilisateur sera performante. Dans certains cas, les champs ne sont peut-être pas encore pris en charge par le client Gestionnaire de package Windows (winget.exe). Par exemple, le champ AppMoniker est facultatif. Toutefois, si vous incluez ce champ, les clients verront les résultats associés à la valeur Moniker lors de l’exécution de la commande search (par exemple, vscode pour Visual Studio Code). S’il n’existe qu’une seule application avec la valeur Moniker spécifiée, les clients peuvent installer votre application en spécifiant le moniker au lieu de l’ID complet du package.
  • La longueur des chaînes de cette spécification doit être limitée à 100 caractères avant un saut de ligne.
  • Le PackageName doit correspondre à l’entrée effectuée dans Ajout/suppression de programmes pour aider la corrélation avec les manifestes à prendre en charge l’exportationet la mise à niveau.
  • Le Publisher doit correspondre à l’entrée effectuée dans Ajout/suppression de programmes pour aider la corrélation avec les manifestes à prendre en charge l’exportationet la mise à niveau.
  • Les programmes d’installation de package au format MSI utilisent des codes de produit pour identifier les applications de manière unique. Le code de produit d’une version donnée d’un package doit être inclus dans le manifeste pour garantir la meilleure expérience de mise à niveau.
  • Quand il existe plusieurs types de programme d’installation pour la version spécifiée du package, une instance de InstallerType peut être placée sous chacun des Installers.

FAQ sur le manifeste

Qu’est-ce qu’un manifeste ?

Les manifestes sont des fichiers YAML contenant des métadonnées utilisées par le Gestionnaire de package Windows pour installer et mettre à niveau des logiciels sur le système d’exploitation Windows. Il existe des milliers de ces fichiers partitionnés sous le répertoire de manifestes dans le référentiel winget-pkgs sur GitHub. La structure de répertoires Gestionnaire de package Windows doit être partitionnée afin que vous n’ayez pas à faire défiler autant dans le site lorsque vous recherchez un manifeste.

Qu’est-ce qu’un package ?

Considérez un package comme une application ou un programme logiciel. Le gestionnaire de package Windows utilise un « PackageIdentifier » pour représenter un package unique. Ils sont généralement sous la forme de Publisher.Package. Parfois, vous pouvez voir des valeurs supplémentaires séparées par une deuxième période.

Qu’est-ce qu’une version ?

Les versions de package sont associées à une version spécifique. Dans certains cas, vous verrez un numéro de version sémantique parfaitement formé et, dans d’autres cas, vous pouvez voir quelque chose de différent. Il peut s’agir de dates pilotées ou d’autres caractères avec une signification spécifique au package. La clé YAML pour une version de package est « PackageVersion ».

Pour plus d’informations sur la compréhension de la structure d’annuaire et la création de votre premier manifeste, consultez Création de manifestes dans le référentiel winget-pkgs sur GitHub.