Introduction
MakePkg.exe est un outil qui place du contenu dans un fichier binaire empaqueté, appelé XBOX Virtual Container (XVC). Les packages pour console ont l’extension de fichier .xvc et les packages pour PC ont l’extension de fichier .msixvc. Outre cette différence d’extension, un suffixe est ajouté au nom du package pour distinguer les packages de la famille XBOX One (_x) de ceux de la famille XBOX Series X|S (_xs). MakePkg.exe utilise le contenu de votre titre et un fichier de mappage comme entrée pour produire des packages chiffrés à l’aide d’une clé de test connue, d’une clé générée aléatoirement ou d’une clé stable sûre pour le chiffrement. La clé utilisée pour le chiffrement dépend du fait que le package est destiné à des tests locaux ou à une soumission à Microsoft en vue de sa publication. Les sections suivantes détaillent les cas d’usage. Le XML du fichier de mappage a deux objectifs. Premièrement, il spécifie l’emplacement des fichiers disponibles pour le titre au moment de l’exécution. Deuxièmement, il spécifie le fichier de chunk auquel appartient chaque fichier. Un ensemble de chunks, appelé jeu de lancement (launch set), est toujours installé avant que le titre ne soit autorisé à s’exécuter. Les chunks restants sont installés pendant l’exécution du titre. Des API permettent d’interroger la progression de l’installation des chunks et de modifier l’ordre d’installation des chunks qui ne sont pas encore installés. Dans cet article :- Étapes de l’empaquetage
- Étapes recommandées pour l’empaquetage pendant le développement
- Test des packages d’installation en streaming
- Meilleures pratiques
- Échecs d’empaquetage causés par des connexions de données ouvertes
- Ressources et conseils
- Voir aussi
Étapes de l’empaquetage
Le processus d’empaquetage de MakePkg comprend plusieurs étapes.Validation de MicrosoftGame.config et de l’existence des fichiers
La commandemakepkg vérifie que le fichier MicrosoftGame.config du répertoire source du contenu est valide et peut être installé.
Lorsque vous exécutez la commande makepkg pack, elle s’assure que les fichiers référencés dans MicrosoftGame.config se trouvent dans le répertoire source. Elle vérifie que ces fichiers sont inclus dans le package pour le jeu de lancement. Cette validation porte sur les binaires, les fichiers image et toutes les autres ressources.
Signature des binaires
XBOX Code Integrity (XCI) analyse et signe les fichiers de votre titre. Dans le cadre de ce processus, il modifie les en-têtes PE détectés dans les fichiers avant de les écrire dans le fichier de package. Si la signature échoue, un message d’erreur est signalé. Ce message inclut une commande permettant de réexécuter manuellement xcihash.exe afin d’obtenir plus de détails sur l’échec de la signature.Création du package
Dès que MakePkg a terminé les étapes de prévalidation, il crée un fichier de package. MakePkg copie ensuite les fichiers source, y compris les exécutables signés, dans le fichier de package, dans les chunks spécifiés par le fichier de mappage XML.Console uniquement : la dernière étape de la création du package consiste à incorporer un fichier Game OS (GameOs.xvd). Ce fichier fait partie du Microsoft Game Development Kit (GDK) et doit se trouver dans le répertoire de disposition, à côté de l’exécutable de votre jeu. L’indicateur
/gameos spécifie un autre emplacement source pour le fichier Game OS.Chiffrement
Signature de test (chiffrement par défaut)
Le comportement par défaut de MakePkg consiste à créer des packages signés pour test, ce qui correspond également à l’utilisation du commutateur/lt lors de l’appel à makepkg pack. La signature de test chiffre le fichier de package généré à l’aide d’une clé de chiffrement de test connue, destinée à la validation des tests de performances, pour une exécution sur XBOX et sur PC. Bien que l’effet du déchiffrement en temps réel du package soit conçu pour être transparent pour le titre, cela garantit que tout problème de performances éventuel lié au chiffrement est détecté avant la certification et la publication finale des titres. Les packages signés pour test ne sont pas destinés à sécuriser le contenu par chiffrement, car le chiffrement utilise une clé fixe. Un package signé pour test peut être installé sur un kit de développement à l’aide de xbapp install et sur un PC de développement à l’aide de wdapp install.
Chiffrement par clé aléatoire (commutateur /l)
Le commutateur /l de MakePkg chiffre le fichier de package avec une clé de chiffrement générée aléatoirement. En plus du package de votre titre, MakePkg /l génère un fichier dont le nom est au format PackageFullName_licenseName_GUID.EKB. (Notez l’utilisation du caractère de soulignement (_).) Les packages créés avec le commutateur /l ne peuvent pas être installés sur un kit de développement ni sur un PC de développement. Vous devez tester votre titre à l’aide de packages signés pour test jusqu’à ce que le titre réussisse toutes les vérifications et tous les tests préalables à la soumission. Une fois cet état atteint, exécutez MakePkg avec le commutateur /l avant la soumission finale à Microsoft.
Recommandé : chiffrement par clé stable (Genkey + commutateur /lk)
Le commutateur/lk de Makepkg chiffre le package avec une clé stable (toujours la même) créée par la commande makepkg genkey. En plus du package de votre titre, makepkg /lk génère des fichiers nommés au format PackageFullName_licenseName_GUID.EKB et PackageFullName_licenseName_GUID.CEKB. (Notez l’utilisation du caractère de soulignement (_).) Les packages créés avec le commutateur /lk peuvent être installés sur un kit de développement, mais pas sur un PC de développement. Pour les PC, vous devez tester votre titre à l’aide de packages signés pour test jusqu’à ce que le titre réussisse toutes les vérifications et tous les tests préalables à la soumission.
Il s’agit du mode de chiffrement recommandé pour les tests sur kit de développement et pour la soumission, en raison des avantages suivants :
- packageutil compare peut générer des estimations correctes de la taille des mises à jour (contrairement à /l).
- Il permet un chargement delta sécurisé vers Partner Center à l’aide du même algorithme que celui utilisé par les consoles et les PC pour télécharger les mises à jour de contenu.
- Il peut être installé sur des devkits (contrairement à
/l). - Il utilise des éléments de clé de chiffrement sécurisés et ne peut être déchiffré que dans des environnements spécifiques (contrairement à
/lt).
/lt et /l, le mode /lk nécessite une étape supplémentaire unique pour être utilisé :
- Une seule fois : exécutez
makepkg genkey /ekb SECRET_KEY.lekbpour créer le fichier SECRET_KEY.lekb. Il s’agit du Local Escrowed Key Blob (LEKB), qui stocke la clé de contenu stable qui chiffre votre package. Il doit être stocké dans un emplacement sécurisé, avec un accès limité aux personnes qui en ont besoin. Dans une configuration idéale, seuls les ordinateurs/comptes de build officiels doivent y avoir accès. - Création du package : exécutez
makepkg pack /lk SECRET_KEY.lekb .... Cela crée un package chiffré à l’aide de la clé stockée dans le fichier SECRET_KEY.lekb. - Chargement du package : les fichiers XVC et EKB sont chargés dans Partner Center comme d’habitude. Les fichiers LEKB et CEKB ne sont pas chargés.
xbapp install installe automatiquement le fichier CEKB nécessaire pour charger le package sur un devkit XBOX. Si vous testez un scénario d’installation
autre que l’installation à l’aide d’outils (disque de jeu, stockage externe, transfert de console à console), utilisez la commande xbapp installkey pour
installer uniquement le fichier CEKB.
peut en déchiffrer le contenu.
peut installer le package sur son devkit, démarrer le package et extraire les fichiers du package avec xbcp.
Validation de la soumission
MakePkg exécute automatiquement Submission Validator (SubmissionValidator.dll) sur les fichiers du titre après la création du package. L’objectif de Submission Validator est de rechercher les erreurs et les problèmes susceptibles de causer des difficultés pour les titres plus tard, lors des processus d’ingestion, de soumission ou de certification chez Microsoft, ou lors de futures mises à jour de contenu. Vous devez corriger tous les problèmes détectés avant de pouvoir générer un package signé à charger dans Partner Center. Le processus de validation de la soumission génère un fichier journal XML détaillant la nature et l’emplacement de tous les échecs. Le processus écrit ce fichier journal au même emplacement que celui spécifié par le paramètre/pd de MakePkg pour la sortie du fichier de package. Ce journal peut contenir des échecs ou des avertissements. Vous devez résoudre les échecs avant de pouvoir soumettre un package à Microsoft. Envisagez de corriger les avertissements afin de garantir que les titres respectent la stratégie et les recommandations des XBOX Requirements (XR).
Lorsque vous chargez un package dans Partner Center et que vous le soumettez au processus d’ingestion, les vérifications de validation sont exécutées à nouveau. Ce processus garantit que le titre est vérifié à l’aide de la dernière version de Submission Validator et que tout problème est détecté le plus tôt possible.
Tests de validation de la soumission
Les tests spécifiques évoluent au fil du temps, à mesure que Microsoft identifie de nouveaux problèmes. La réussite des vérifications de Submission Validator ne doit pas être interprétée comme une garantie qu’aucun autre problème ne surviendra avec la soumission du titre pendant le processus d’ingestion et de certification. L’objectif est plutôt de réduire le temps et le coût des rejets résultant d’erreurs prévisibles. En outre, bien que Submission Validator puisse rechercher certains problèmes liés à la sécurité, il ne doit pas être considéré comme un test de sécurité pour un titre.
Vous pouvez télécharger la dernière version de Submission Validator à partir du site XBOX Game Developer (XGD). Étant donné que l’outil peut évoluer à un rythme différent de celui des versions du XBOX One Software Development Kit, veillez à utiliser la dernière version pour éviter tout rejet pour échec de validation lors du processus de soumission. Pour obtenir la dernière version, consultez XBOX Developer Downloads->XBOX One->Submission Validator.
Pour plus d’informations sur Submission Validator, consultez Submission Validator (SubmissionValidator.dll) dans la documentation du GDK.
Si vous avez des questions sur le processus de validation, contactez votre responsable de compte Microsoft.
Étapes recommandées pour l’empaquetage pendant le développement
Pour créer des packages pendant le développement, procédez comme suit. Utilisezwdapp au lieu de xbapp lorsque vous ciblez un PC.
- Itérez localement à l’aide de packages signés pour test et de xbapp install depuis votre PC de développement. MakePkg.exe pack /f Mapfile /d LooseContentDir /pd OutputFolder Pour commencer, consultez XBOX Developer Downloads.
- Exécutez votre titre en le lançant depuis le shell ou à l’aide de xbapp launch. xbapp install local-XVC-path ou xbapp install http-URI Pour tester d’autres options d’installation en streaming, consultez Test des packages d’installation en streaming plus loin dans cet article.
- Testez l’installation du titre depuis le lecteur optique à l’aide d’un package signé pour test gravé dans le dossier racine d’un disque Blu-ray. Après avoir inséré le disque dans le kit de développement XBOX, exécutez la commande suivante. xbapp install XO:\XVC-file-name
-
Préparez votre soumission finale en utilisant la même commande d’empaquetage que pour votre package signé pour test, mais ajoutez l’indicateur
/l.
Test des packages d’installation en streaming (PC)
Utilisez la commandewdapp pour installer des packages sur le PC de test.
Actuellement, le package MSIXVC de test doit se trouver sur un lecteur physique du PC de test ou sur un serveur web. Dans une prochaine mise à jour, l’installation à partir de partages UNC (Universal Naming Convention) sera ajoutée.
Test des packages d’installation en streaming (console)
Vous pouvez tester l’installation de packages d’installation en streaming signés pour test de quatre manières.Streaming depuis le PC de développement
Le streaming depuis le PC de développement ne prend en charge aucune limitation du débit. La vitesse de l’installation dépend des caractéristiques du processeur et des E/S de votre PC de développement, ainsi que de la bande passante de la connexion réseau entre le PC de développement et le kit de développement. Vous pouvez vous attendre à des vitesses de 300 Mbit/s (environ 36 Mio/s) ou plus sur des connexions Ethernet gigabit depuis des PC de développement modernes équipés de disques durs mécaniques. xbapp install dev-pc-path-to-XVC Installer via la ligne de commande Installer via XBOX ManagerHéberger le package sur un serveur web
Si votre serveur web prend en charge la configuration de la limitation de bande passante, l’hébergement du package sur un serveur web permet de simuler différentes vitesses de distribution réseau. La plateforme XBOX One gère les échecs de connexion et la logique de nouvelle tentative. Votre titre doit s’exécuter de la même manière lors d’une installation depuis une source Internet que depuis un disque optique, à la vitesse près. xbapp install http-URI-to-package Installer via la ligne de commande Installer via XBOX ManagerGraver le package sur un disque, puis l’installer depuis une ligne de commande
Gravez un disque optique contenant votre XVC dans le répertoire racine, puis installez le package à l’aide de la commande suivante. xbapp install XO:\XVC-file-nameGraver le package sur un disque, puis l’installer via le shell
Gravez un disque optique contenant un dossier nommé MSXC qui contient votre package. Insérez le disque dans un kit de développement en cours d’exécution. Le shell commence automatiquement l’installation de votre titre, et le kit de développement affiche une notification une fois le jeu de lancement installé ; le titre peut alors être lancé.Meilleures pratiques
Utiliser les mises à jour de contenu au niveau des sous-fichiers
Utilisez les mises à jour de contenu au niveau des sous-fichiers, qui réduisent la taille des mises à jour de contenu. Concevez la disposition de votre package de manière à garantir des mises à jour de contenu optimales à l’avenir. Pour plus d’informations sur la conception de packages pour des mises à jour optimales, consultez Meilleures pratiques pour les mises à jour de contenu.XBOX Requirement 034 (XR-034 : Streaming Install Initial Play Marker)
L’inclusion d’un marqueur de jeu initial est facultative, mais fortement recommandée. Elle permet à un utilisateur d’exécuter le titre avant qu’il ne soit entièrement installé, pendant que l’installation se poursuit en arrière-plan. Conformément à XR-034 : Streaming Install Initial Player Marker, les titres qui incluent un marqueur de jeu initial doivent offrir une expérience de jeu lorsqu’ils sont lancés à partir de ce marqueur.Tester votre titre
Testez votre titre pendant son installation à partir de différentes sources et à différentes vitesses.Utiliser la dernière version de Submission Validator
Utilisez toujours la version la plus récente de Submission Validator. La dernière version de Submission Validator est disponible sur XBOX Developer Downloads->XBOX One->Submission Validator.Échecs d’empaquetage causés par des connexions de données ouvertes
Lorsque vous installez un package à l’aide dexbapp install /w, ou lorsque XBOX Manager installe un package avec l’option Keep data connection open activée (utilisée pour les scénarios Intelligent Delivery et de chunks à la demande), le canal de données entre la console et le fichier de package sur votre PC reste ouvert une fois l’installation terminée. Cette connexion ouverte verrouille le fichier de package.
Si vous essayez de régénérer ou de réempaqueter votre titre alors que ce canal est ouvert, makepkg échoue avec une violation de partage, car il ne peut pas écrire dans le fichier de package verrouillé.
Pour résoudre ce problème, fermez la connexion de données ouverte avant de régénérer :
- XBOX Manager : dans l’application XBOX Manager, recherchez le package installé et décochez l’option Keep data connection open, ou désinstallez puis réinstallez le package sans activer cette option.
- xbapp install : omettez l’indicateur
/wlorsque vous n’avez pas besoin que le canal reste ouvert après l’installation. Utilisez/wuniquement lorsque votre titre doit demander des chunks supplémentaires au moment de l’exécution pendant les tests de développement. - Fermer XBOX Manager : la fermeture complète de XBOX Manager libère tous les handles de fichiers ouverts qu’il détient sur les fichiers de package.
Ressources et conseils
Pour plus d’informations, consultez les articles suivants :- Système > Vue d’ensemble > Installation en streaming et Intelligent Delivery : vue d’ensemble
- Système > Vue d’ensemble > Installation en streaming > Réorganisation dynamique des chunks
- Système > Vue d’ensemble > Installation en streaming > Installation en streaming : état
- Test, automatisation et publication > Outils > Installation en streaming > Schéma du package de déploiement
- Test, automatisation et publication > Outils > Installation en streaming > Make Package (makepkg.exe)