Skip to main content
De nombreux jeux utilisent des logiciels anti-triche et d’autres intergiciels. Ces composants sont généralement installés en chaîne lorsque l’utilisateur installe le jeu. Un utilisateur peut installer un jeu au moyen du Microsoft Store, et un autre jeu au moyen d’un autre canal de distribution. La plateforme garantit l’absence de conflits si les deux jeux installent en chaîne le même package d’intergiciel. Le jeu peut inclure dans son package un ou plusieurs fichiers .exe ou .msi arbitraires et demander que ces fichiers soient exécutés pour terminer l’installation de l’application. La fonctionnalité d’actions d’installation personnalisées est destinée à l’installation de logiciels anti-triche pour les jeux ou d’autres intergiciels redistribuables. Vous pouvez ainsi utiliser exactement le même fichier .exe d’installation en chaîne dans un package MSIX soumis au Microsoft Store et dans un fichier .msi ou .exe soumis au moyen d’un autre canal de distribution. Dans les applications Win32 traditionnelles, les intergiciels partagés sont généralement installés au moyen de fichiers redistribuables indépendants, qui prennent normalement la forme d’un fichier .exe autoextractible ou d’un fichier .msi pouvant être fourni avec le jeu lui-même. Les applications du Microsoft Store modélisent les dépendances sous forme de packages d’infrastructure qui ne sont pas fournis avec le jeu, mais déployés séparément au moyen du Microsoft Store. Dans ce modèle, le manifeste de l’application consommatrice déclare une dépendance envers un ou plusieurs packages d’infrastructure. Le Microsoft Store se charge ensuite d’enchaîner l’installation des dépendances. Bien que de nombreux composants redistribuables soient disponibles sous forme de packages d’infrastructure dans le Microsoft Store, certains composants redistribuables ne le seront inévitablement pas. Pour ces packages, la solution consiste à permettre au jeu d’inclure le composant redistribuable dans le package du jeu. Pour inclure des composants redistribuables .exe ou .msi, vous devez apporter des modifications à votre fichier MicrosoftGame.config. Ces modifications comprennent la déclaration du type d’action personnalisée que vous souhaitez utiliser, ainsi que son emplacement dans le package d’installation. Tout composant redistribuable doit être inclus dans le package et déclaré dans MicrosoftGame.config. La déclaration comprend le chemin de l’exécutable (relatif au chemin de dossier déclaré, lui-même relatif au chemin racine du package). La déclaration comprend également les arguments de ligne de commande à transmettre à l’exécutable lors de son exécution. Pour ce faire, on inclut l’élément CustomInstallActions dans le fichier MicrosoftGame.config.

​
CustomInstallActions

L’élément CustomInstallActions contient toutes les définitions indiquant quelles actions d’installation personnalisées doivent être exécutées et à quel moment. Vous ne pouvez déclarer qu’une seule instance de cet élément dans votre fichier MicrosoftGame.config. Il comporte un élément enfant obligatoire, Folder, qui est une chaîne désignant le dossier contenant tous les fichiers requis pour l’ensemble des actions personnalisées. Ce dossier peut contenir des sous-dossiers. Il vous incombe de vous assurer que le package comprend toutes les dépendances des exécutables des actions personnalisées, et que celles-ci se trouvent dans le chemin de chargement approprié pour chacun d’eux.
Lorsque vous créez le package du titre, makepkg traduit cet élément CustomInstallActions en extension MSIX windows.customInstall dans le fichier appxmanifest.xml généré, où l’élément équivalent est <CustomInstall> et où Folder est exprimé sous forme d’attribut. Vous n’avez pas à rédiger vous-même cette forme <CustomInstall> : dans MicrosoftGame.config, Folder est un élément enfant de CustomInstallActions, comme le montrent les exemples de la section Modifications du fichier de configuration du jeu plus loin dans cet article.
Vous ne devez placer aucun des exécutables principaux du jeu ni aucun autre fichier dans le dossier désigné. Il est explicitement réservé aux fichiers d’installation personnalisée.
Dans l’élément CustomInstallActions, l’application peut déclarer les éléments enfants InstallActionList, RepairActionList et UninstallActionList. Ils sont tous facultatifs : vous pouvez en déclarer n’importe lequel ou aucun. Dans chacune de ces listes, vous spécifiez un ou plusieurs éléments enfants InstallAction, RepairAction ou UninstallAction. La plateforme exécute les actions que vous spécifiez dans l’ordre que vous spécifiez, avec les arguments de ligne de commande que vous spécifiez.

​
Types d’actions

Les trois nœuds enfants de l’extension d’installation personnalisée déterminent le moment où certaines actions personnalisées sont exécutées. Il existe trois types d’actions d’installation personnalisées.
  • Action d’installation : actions que la plateforme exécute avant le premier démarrage de l’application
  • Action de réparation : actions exécutées lorsque l’utilisateur sélectionne Réparer ou Réinitialiser
  • Action de désinstallation : actions exécutées lorsque l’utilisateur désinstalle l’application
Malgré son nom, une action d’installation ne s’exécute pas lorsque le package est installé. Chaque type d’action s’exécute à un moment précis du cycle de vie de l’application, et une InstallAction s’exécute une seule fois, immédiatement avant le premier lancement du titre (c’est le premier moment où la plateforme peut afficher l’invite UAC requise). « Install », « Repair » et « Uninstall » désignent la catégorie du cycle de vie à laquelle appartient l’action, et non le moment où elle s’exécute. Si vous avez besoin d’effectuer un travail au moment réel de l’installation ou du téléchargement du package, les actions d’installation personnalisées ne sont pas le mécanisme approprié. Pour la séquence complète, consultez Utilisation des actions personnalisées.
En général, vous spécifiez l’installation en chaîne d’un composant redistribuable en tant qu’InstallAction, puis sa désinstallation en tant qu’UninstallAction. Toutefois, dans certains cas, vous pourriez choisir d’installer sans désinstallation correspondante. Dans ce scénario, votre application installe un élément qu’elle laisse derrière elle lorsqu’elle est désinstallée, ce qui peut convenir aux composants redistribuables partagés par d’autres applications. De même, votre RepairAction peut simplement redéclarer les exécutables que vous avez spécifiés pour votre InstallAction, ce qui est courant. Il est possible que chacune des actions que vous souhaitez effectuer lors de l’installation, de la réparation ou de la désinstallation nécessite un exécutable différent. Le schéma est très souple : la plateforme n’exige aucune des actions. Vous êtes libre de configurer les comportements appropriés pour chaque jeu.
L’action de désinstallation n’est exécutée que si une action d’installation ou de réparation a été exécutée. Le système utilise la propriété Name pour suivre cet état. C’est pourquoi il est important que les actions d’installation, de réparation et de désinstallation portent le même Name.

​
Composantes d’une action

​
File

Pour chaque action, vous devez spécifier le fichier à exécuter, et ce fichier doit se trouver dans votre package. Si vous spécifiez un chemin, il sera implicitement relatif au chemin Folder de votre élément CustomInstallActions. Vous ne pouvez pas spécifier de chemin absolu. Votre chemin ne doit pas commencer par une barre oblique inverse (\).

​
Name

Vous devez spécifier un Name pour l’action. Ce Name doit être unique au sein du nœud Actions parent, mais peut être partagé entre différents nœuds Actions. Par exemple, vous pourriez spécifier File=“MySetup.exe” et Name=“abc123” à la fois comme InstallAction et comme RepairAction. Par contre, si vous avez deux éléments InstallAction, chacun doit avoir un Name différent. Vous devriez utiliser le même Name pour le même exécutable d’une version de package à l’autre, tant que cet exécutable ne change pas. Le Name sert d’identité à l’action et permet à la plateforme de suivre les actions qui ont été exécutées avec succès, ainsi que celles qui doivent être exécutées pour un package mis à jour. Si un package mis à jour spécifie une action personnalisée dont le Name a déjà été exécuté avec succès, la plateforme ignore cette action lors de la mise à jour.
Une différence dans la liste des arguments ne constitue pas une différence d’identité. Si vous souhaitez exécuter le même exécutable avec des arguments différents dans un package mis à jour, vous devez fournir un Name différent. Il vous incombe de configurer correctement les Names que vous déclarez et d’en assurer le suivi d’une version à l’autre.

​
Arguments

Chaque action d’installation personnalisée comporte un troisième élément, argument, qui vous permet d’inclure les arguments nécessaires à l’exécution de la commande du composant redistribuable.

​
Utilisation des actions personnalisées

L’installation d’un logiciel anti-triche exige généralement que l’utilisateur dispose de privilèges d’administrateur et, de manière générale (puisque les actions personnalisées constituent une fonctionnalité extrêmement puissante), la plateforme exige des privilèges d’administrateur pour tout package comportant des actions personnalisées. Pour les opérations exécutées avec des privilèges d’administrateur, Windows exige l’affichage d’une invite de contrôle de compte d’utilisateur (UAC) lors de la première exécution de l’application. Le flux de travail de l’utilisateur est le suivant.
  • La page du Microsoft Store du jeu comprend une description des exigences, notamment si l’installation requiert des privilèges élevés, si l’installation exécute une action personnalisée et ce que cela pourrait signifier pour l’utilisateur. Ces informations sont fournies afin que l’utilisateur puisse prendre une décision éclairée quant à l’achat du jeu.
  • Si l’utilisateur accepte les contraintes et les implications, il sélectionne Installer.
  • La plateforme détecte que le package comprend une action personnalisée et enregistre le fait que l’action personnalisée doit être exécutée. Toutefois, elle n’exécute pas l’action personnalisée pendant la phase d’installation initiale. Toute action personnalisée est plutôt exécutée la première fois que l’utilisateur lance le jeu.
  • Lors du premier lancement du jeu, au moment où la plateforme s’apprête à exécuter les actions personnalisées, elle affiche une invite UAC. L’utilisateur doit alors fournir des informations d’identification d’administrateur et accepter l’élévation. Même si un package contient plusieurs actions personnalisées, l’utilisateur ne reçoit qu’une seule invite UAC. Aucune autre invite UAC n’est affichée pour les mises à jour, sauf si une ou plusieurs des actions personnalisées ont changé. Une invite UAC est affichée lors de la désinstallation du jeu.
Toutes les actions personnalisées doivent retourner zéro en cas de réussite. Si une action personnalisée échoue, la plateforme continue d’exécuter les actions personnalisées restantes et continue de tenter de lancer l’application. À chaque lancement ultérieur de l’application, la plateforme continue de réessayer toute action personnalisée d’installation ayant échoué ou incomplète jusqu’à ce qu’elle réussisse. Si l’application ne fonctionne pas correctement en raison de l’échec d’une action personnalisée, l’utilisateur peut toujours accéder à la page Paramètres de l’application et sélectionner Réparer ou Réinitialiser. Une réparation ou une réinitialisation ne retélécharge pas les fichiers du jeu : elle réinscrit simplement le package. Toute action personnalisée ayant échoué ou n’ayant pas été exécutée est réinscrite pour être exécutée. Si vous avez un programme d’installation personnalisé qui retourne une valeur non nulle en cas de réussite, une option consiste à encapsuler ce programme d’installation dans un autre exécutable que vous créez, qui retourne zéro en cas de réussite. La politique du Microsoft Store comprend des directives sur les types d’intergiciels et de logiciels redistribuables qui peuvent être installés en chaîne. De manière générale, les installations en chaîne sont destinées aux logiciels partagés nécessaires à l’exécution du jeu. Elles ne sont pas destinées à installer des applications non liées ou d’autres logiciels.
Les actions d’installation personnalisées sont prises en charge uniquement dans le package MSIXVC principal. Elles ne sont pas prises en charge dans les packages d’infrastructure, les packages facultatifs, les packages de modification ou tout autre type de package.
Les actions personnalisées d’installation, de réparation et de désinstallation sont exécutées par le pipeline de déploiement commercial du Microsoft Store. Elles ne sont pas exécutées lorsque vous installez le package localement à des fins de développement, par exemple lorsque vous installez un fichier .msixvc libre à l’aide de wdApp install ou que vous inscrivez un package à l’aide de Add-AppxPackage. Une installation de développement locale vous permet tout de même de vérifier que votre package déclare correctement les actions (elles apparaissent dans le fichier appxmanifest.xml généré sous forme d’extension windows.customInstall), mais les exécutables des actions personnalisées eux-mêmes ne sont pas appelés dans ce cas. Pour valider l’exécution complète des actions, installez le titre au moyen d’un flux du Store ou d’un bac à sable.

​
Exécution d’un fichier MSI en tant qu’action d’installation personnalisée

Dans le cas d’un fichier MSI, vous fournissez le nom du fichier MSI, et la plateforme exécute msiexec.exe sur ce fichier. Ne fournissez pas les arguments /i, /f ou /x, car ceux-ci sont déduits du type de l’action (installation, réparation ou désinstallation) dans laquelle le fichier est déclaré. Vous ne pouvez fournir aucune option au commutateur /f. Vous pouvez toutefois fournir tout autre argument facultatif qui serait normalement fourni à msiexec.exe. Il s’agit du seul scénario dans lequel les arguments de ligne de commande sont limités : pour les actions non MSI, vous pouvez fournir les arguments de votre choix. Pour les actions non MSI, la plateforme n’analyse ni ne valide les arguments. Elle se contente de les transmettre à l’exécutable. Il vous incombe de vous assurer que les arguments sont corrects. Il n’existe aucune prise en charge directe des fichiers MST (transformations MSI). Si vous avez besoin d’un MSI/MST, une solution de contournement possible consiste à générer un fichier .exe indépendant qui encapsule msiexec afin d’exécuter votre MSI et d’appliquer votre MST.

​
Modifications du fichier de configuration du jeu

Les exemples XML suivants illustrent les ajouts appropriés à un fichier MicrosoftGame.config pour permettre les actions d’installation personnalisées.
Dans l’exemple précédent, tous les exécutables et toutes leurs dépendances doivent être placés dans le dossier MyInstallers que vous avez spécifié à la racine du package. Dans ce dossier, vous pouvez créer toute structure de sous-dossiers appropriée pour votre application. Dans cet exemple, le chemin de MySetup.exe serait <package root>\MyInstallers\Banana\MySetup.exe. Si cet exécutable a des dépendances, elles doivent également être placées dans le dossier ou le sous-dossier approprié. La séquence suivante montre comment rédiger le manifeste sur plusieurs versions.
Last modified on October 6, 2026