Windows Games Explorer pour les développeurs de jeux

Windows Vista améliore l’expérience utilisateur du gaming sur Windows en incluant Games Explorer. Games Explorer est exposé dans le menu Démarrer de Windows Vista en tant que dossier Jeux et offre un emplacement central pour accéder aux jeux.

À compter de la version de mars 2009 du SDK DirectX, un nouveau schéma de fichier de définition de jeu (GDF) est utilisé pour prendre en charge les fonctionnalités dans Windows 7, le fournisseur de jeux et le flux RSS, et IGameExplorer2. IGameExplorer2 est une nouvelle interface sur Windows 7 qui simplifie le processus d’intégration d’un jeu à Games Explorer.

Cet article décrit le processus d’inscription d’un jeu auprès de Games Explorer et le contrôle parental sur Windows Vista et Windows 7 à l’aide du nouveau schéma GDF.

Contenu :

• Conditions préalables
• Intégration à un programme d’installation
• Processus d’intégration
• Tâches Games Explorer
• Intégration à InstallScript
• Intégration à un package MSI
• Conseils de débogage
  • Tester avec un exemple de code
  • Vérifier que votre jeu a été supprimé correctement
  • Veiller à signer avec Authenticode
  • Vérifier que les contrôles parentaux sont disponibles
  • Vérifier que les tâches sont du type approprié
  • Vérifier les données dans un binaire GDF
• Résumé

Prérequis

Avant de pouvoir intégrer un jeu à Games Explorer, vous devez créer un fichier de définition de jeu (GDF). Un fichier GDF est un fichier XML qui contient des métadonnées décrivant le jeu. Dans la version de mars 2009 du SDK DirectX, une section pour le fournisseur de jeux, le flux RSS et la tâche de jeu a été ajoutée au schéma GDF. Pour utiliser les instructions de cet article, vous devez utiliser ce nouveau format GDF pour créer votre fichier GDF.

Microsoft fournit un outil permettant de créer des fichiers GDF dans le SDK DirectX, l’Éditeur de fichiers de définition de jeu, pour faciliter ce processus de création. Cet outil vous aide également à créer des versions localisées d’un GDF.

Une fois qu’un GDF a été créé et localisé, il doit être encapsulé dans une section de ressource d’un fichier binaire (un exécutable ou une DLL), ainsi que la miniature et l’icône du jeu. Le GDF contient toutes les métadonnées associées au jeu, y compris la classification du jeu. Le Contrôle parental de Windows utilise la classification du jeu pour permettre aux parents de contrôler l’accès au jeu. Le fichier binaire qui contient le GDF doit être signé numériquement avec un certificat Authenticode valide, sinon Games Explorer et le système de contrôle parental ignorent la classification du jeu parce que les informations de classification ne peuvent pas être approuvées sans certification. Pour plus d’informations sur la signature du code avec Authenticode, consultez Signature Authenticode pour les développeurs de jeux.

Intégration à un programme d’installation

Pour simplifier l’intégration à Games Explorer, l’exemple GameUXInstallHelper fournit une API commune qui peut être appelée sur Windows XP, Windows Vista et Windows 7. Elle est conçue pour fonctionner avec des scripts pour InstallShield et Wise Installation System, ainsi que des actions personnalisées MSI et des outils d’installation personnalisés. La détection du système d’exploitation est gérée dans cet exemple de DLL, donc l’appelant n’a pas besoin de s’inquiéter si le client exécute Windows XP, Windows Vista ou Windows 7.

Les fonctions exportées par cette DLL sont les suivantes :

GameExplorerInstallW

Inscrit un jeu à Games Explorer en fonction d’un chemin d’accès au fichier binaire GDF, d’un chemin d’accès complet au dossier où le jeu est installé et de l’étendue de l’installation.

GameExplorerInstallA

Inscrit un jeu à Games Explorer ; version ANSI de GameExplorerInstallW.

GameExplorerUninstallW

Désinscrit un jeu de Games Explorer, en fonction d’un chemin d’accès au fichier binaire GDF.

GameExplorerUninstallA

Désinscrit un jeu de Games Explorer ; version ANSI de GameExplorerUninstallW.

GameExplorerSetMSIProperties

Configure les propriétés CustomActionData pour les actions d’une installation personnalisée différée du MSI. L’utilisation de cette fonction est décrite en détail plus loin dans cet article.

GameExplorerInstallUsingMSI

Ajoute un jeu à Games Explorer ; à utiliser pendant une installation d’action personnalisée du MSI.

GameExplorerUninstallUsingMSI

Supprime un jeu de Games Explorer ; à utiliser pendant une installation d’action personnalisée du MSI.

Ces fonctions sont expliquées plus en détail dans l’en-tête GameUXInstallHelper.h.

Processus d’intégration

Une fois que les fichiers GDF et associés ont été ajoutés à une ressource binaire, il est ensuite possible d’intégrer le jeu à Games Explorer. L’utilisation de GameUXInstallHelper simplifie le processus d’intégration. Pour inscrire le jeu à Games Explorer, appelez GameExplorerInstall avec un chemin d’accès au fichier binaire GDF, un chemin d’accès complet au dossier où le jeu est installé et l’étendue de l’installation. Pour désinscrire le jeu, appelez GameExplorerUninstall avec un chemin d’accès au fichier binaire GDF.

Notez que le processus de suppression ne supprime qu’une seule installation. Si un jeu a été installé plusieurs fois, ce processus doit être répété pour chacune des installations.

Tâches Games Explorer

Les tâches Games Explorer s’affichent dans le menu contextuel d’un élément dans Games Explorer. Les tâches sont divisées en tâches de jeu et en tâches de support. Les tâches de jeu lancent un jeu dans un mode particulier, tandis que les tâches de support servent n’importe quel autre objectif, y compris la liaison à des sites web.

Dans Windows Vista, les tâches sont simplement des raccourcis situés dans des dossiers spécifiques. Les tâches de lecture et les tâches de support sont stockées dans des dossiers avec des noms correspondants, PlayTasks et SupportTasks. GameUXInstallHelper peut lire les informations de tâche du jeu à partir du fichier binaire GDF et créer automatiquement tous les raccourcis.

Dans Windows 7, les raccourcis vers les tâches ne sont pas nécessaires, car Games Explorer obtient toutes les informations de tâche directement à partir du fichier binaire GDF.

Intégration à InstallScript

L’appel des API Games Explorer à partir du script InstallScript d’InstallShield est facile en utilisant l’échantillon GameUXInstallHelper. Les étapes nécessaires à l’intégration à InstallShield sont les suivantes :

1. Ouvrez un projet InstallScript dans l’éditeur InstallShield.

2. Ajoutez GameUXInstallHelper.dll au projet à installer dans le répertoire cible.

   Pour ajouter GameUXInstallHelper.dll à un projet InstallScript :

   1. Sous l’onglet Concepteur d’installation, cliquez sur Données d’application dans le volet de navigation à gauche.

   2. Cliquez sur Fichiers et dossiers et parcourez les Dossiers de l’ordinateur source pour localiser GameUXInstallerHelper.dll dans les Fichiers de l’ordinateur source.

      L’emplacement par défaut de GameUXInstallerHelper.dll est Racine du SDK DirectX\Samples\C++\Misc\Bin\x86.

   3. Sous Dossiers de l’ordinateur de destination, cliquez sur Dossier cible de l’application.

   4. Faites glisser GameUXInstallerHelper.dll des Fichiers de l’ordinateur source vers les Fichiers de l’ordinateur de destination.

3. Dans l’explorateur d’InstallScript, cliquez sur le fichier InstallScript (généralement setup.rul) qui appelle la fonction DLL.

4. Collez le script InstallScript suivant dans le fichier :

   typedef GUID
   begin
   LONG  Data1;
   SHORT Data2;
   SHORT Data3;
   CHAR  Data4(8);
   end;
   
   prototype LONG GameUXInstallHelper.GameExplorerInstallW(WSTRING, WSTRING, NUMBER);
   prototype LONG GameUXInstallHelper.GameExplorerUninstallW(WSTRING);
   
   function OnMoved()
   
   WSTRING gdfbin[256];
   WSTRING path[256];
   NUMBER scope;
   
   begin
   
   if !MAINTENANCE then
   
   UseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   path = TARGETDIR;
   gdfbin = TARGETDIR ^ "bin\\ExampleGame.exe";  // TODO: Change this to point to binary containing the GDF
   
   if ALLUSERS == 1 then
   scope = 3;
   else
   scope = 2;
   endif;
   
   GameUXInstallHelper.GameExplorerInstallW( gdfbin, path, scope);
   
   UnUseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UnUseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   endif;
   
   end;
   
   function OnMoving()
   
   WSTRING gdfbin[256];
   
   begin
   
   if MAINTENANCE && UNINST != "" then
   
   UseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   gdfbin = path ^ "bin\\ExampleGame.exe";  // TODO: Change this to point to binary containing the GDF
   
   GameUXInstallHelper.GameExplorerUninstallW(gdfbin);
   UnUseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UnUseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   endif;
   
   end;
   

Intégration à un package MSI

Voici une description générale des étapes requises pour appeler les API Games Explorer à l’aide d’actions personnalisées MSI :

1. Ajoutez une propriété à la table des propriétés MSI appelée « RelativePathToGDF » contenant le chemin d’accès relatif au fichier binaire GDF.
2. Après l’action CostFinalize, appelez la fonction de la DLL GameUXInstallHelper SetMSIGameExplorerProperties dans une action personnalisée immédiate afin de définir les propriétés MSI appropriées pour les autres actions personnalisées.
3. Lors de l’installation, déclenchez une action personnalisée différée après l’action InstallFiles qui appelle la fonction de la DLL GameUXInstallHelper AddToGameExplorerUsingMSI. Si l’installation concerne tous les utilisateurs, l’action personnalisée doit définir l’indicateur msidbCustomActionTypeNoImpersonate ; sinon, elle ne doit pas définir cet indicateur. C’est pourquoi deux actions personnalisées presque identiques sont définies : GameUXAddAsAdmin et GameUXAddAsCurUser.
4. Lors de la suppression de l’installation, déclenchez une action personnalisée différée avant l’action RemoveFiles qui appelle la fonction de la DLL GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Si l’installation concerne tous les utilisateurs, l’action personnalisée doit définir l’indicateur msidbCustomActionTypeNoImpersonate ; sinon, elle ne doit pas définir cet indicateur. C’est pourquoi deux actions personnalisées presque identiques sont définies : GameUXRemoveAsAdmin et GameUXRemoveAsCurUser.
5. Définissez les actions personnalisées de restauration pour gérer le cas où l’utilisateur annule l’installation ou la suppression après l’une de ces actions personnalisées. Cela entraîne 4 actions personnalisées supplémentaires : GameUXRollBackAddAsAdmin, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAsAdmin et GameUXRollBackRemoveAsCurUser.

Cette procédure est décrite en détail dans les instructions suivantes, qui décrivent un processus pouvant être effectué à l’aide d’un éditeur MSI, tel que l’éditeur Orca trouvé dans le SDK de plateforme. Certains éditeurs MSI ont des Assistants qui simplifient certaines de ces étapes de configuration.

Pour configurer un package MSI en vue d’une intégration à Games Explorer

1. Ouvrez le package MSI dans Orca.

2. Ajoutez la ligne indiquée dans le tableau suivant au tableau Binary dans le package MSI.

   Nom	Données
   GAMEUX	chemin de fichier vers DLL\GameUXInstallHelper.dll

    

   Remarque

   Ce fichier sera incorporé dans le package MSI, donc vous devez effectuer cette étape chaque fois que vous recompilez GameUXInstallHelper.dll.

    

3. Ajoutez les lignes indiquées dans le tableau suivant au tableau CustomAction dans le package MSI.

   Action	Type	Source	Cible
   GameUXSetMSIProperties	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue = 65	GAMEUX	SetMSIGameExplorerProperties
   GameUXAddAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	AddToGameExplorerUsingMSI
   GameUXAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	AddToGameExplorerUsingMSI
   GameUXRollBackAddAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRollBackAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRemoveAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRollBackRemoveAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	AddToGameExplorerUsingMSI
   GameUXRollBackRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	AddToGameExplorerUsingMSI

    

4. Ajoutez les valeurs affichées pour Action, Condition et Sequence dans le tableau suivant au tableau InstallExecuteSequence dans le package MSI.

   Action	Condition	Séquence	Notes
   GameUXSetMSIProperties		1015	Le numéro de séquence place l’action peu après CostFinalize.
   GameUXAddAsAdmin	NOT Installed AND ALLUSERS	4003	Cette action personnalisée se produit uniquement lors d’une nouvelle installation pour tous les utilisateurs. Le numéro de séquence place l’action après InstallFiles et après les restaurations.
   GameUXAddAsCurUser	NOT Installed AND NOT ALLUSERS	4004	Cette action personnalisée se produit uniquement lors d’une nouvelle installation pour l’utilisateur actuel uniquement. Le numéro de séquence place l’action après InstallFiles et après les restaurations.
   GameUXRollBackAddAsAdmin	NOT Installed AND ALLUSERS	4001	Cette action personnalisée se produit uniquement lorsqu’une nouvelle installation pour tous les utilisateurs est annulée. Le numéro de séquence place l’action après InstallFiles et avant l’action personnalisée Add.
   GameUXRollBackAddAsCurUser	NOT Installed AND NOT ALLUSERS	4002	Cette action personnalisée se produit uniquement lorsqu’une nouvelle installation pour l’utilisateur actuel uniquement est annulée. Le numéro de séquence place l’action après InstallFiles et avant l’action personnalisée Add.
   GameUXRemoveAsAdmin	REMOVE~="ALL" AND ALLUSERS	3452	Cette action personnalisée se produit uniquement lors de la suppression pour tous les utilisateurs. Le numéro de séquence place l’action directement avant RemoveFiles et après les restaurations.
   GameUXRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLUSERS	3453	Cette action personnalisée se produit uniquement lors de la suppression pour l’utilisateur actuel. Le numéro de séquence place l’action directement avant RemoveFiles et après les restaurations.
   GameUXRollBackRemoveAsAdmin	REMOVE~="ALL" AND ALLUSERS	3450	Cette action personnalisée se produit uniquement lorsque la suppression pour tous les utilisateurs est annulée. Le numéro de séquence place l’action directement avant RemoveFiles et avant l’action personnalisée Remove.
   GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLUSERS	3451	Cette action personnalisée se produit uniquement lorsque la suppression pour l’utilisateur actuel est annulée. Le numéro de séquence place l’action directement avant RemoveFiles et avant l’action personnalisée Remove.

    

5. Ajoutez la ligne indiquée dans le tableau suivant au tableau Property dans le package MSI.

   Propriété	Valeur
   RelativePathToGDF	chemin de fichier relatif\nom du fichier binaire qui contient le fichier GDF

    

   Remarque

   L’emplacement spécifié par le chemin est relatif à l’emplacement spécifié par le chemin d’installation. Par exemple, bin\GDF.dll.

    

6. Enregistrez le package MSI.

Pour plus d’informations sur les packages MSI et Windows Installer, consultez Windows Installer.

Conseils de débogage

Voici quelques conseils pour vous aider à déboguer des problèmes lors de l’appel des API Games Explorer :

Tester avec un exemple de code

La création de l’exemple de solution GameUXInstallHelper crée GameUXInstallHelper.dll et GDFInstall.exe. GDFInstall.exe est un exemple d’application qui utilise GameUXInstallHelper.dll. L’exécution de GDFInstall.exe vous demande si vous souhaitez installer ou supprimer un fichier binaire GDF dans l’explorateur de jeux. Vous pouvez tester votre fichier binaire GDF en le transmettant en tant que premier argument de ligne de commande à GDFInstall.exe.

Si vous n’avez pas de fichier binaire GDF ou si vous ne parvenez pas à l’installer, essayez d’utiliser l’exemple de GDF dans le SDK DirectX. L’exemple GDFExampleBinary se trouve dans le SDK DirectX. Il s’agit juste d’une DLL qui contient uniquement un fichier GDF. Son projet GDFMaker est également inclus dans la source. Vous pouvez le générer et le tester à l’aide de GDFInstall.exe. Vous pouvez également comparer son code XML au vôtre pour identifier exactement où se trouve le problème.

Vérifier que votre jeu a été supprimé correctement

Si le jeu est déjà installé dans Games Explorer, les appels suivants à IGameExplorer::AddGame retournent E_FAIL, donc assurez-vous que votre jeu n’est pas installé avant les tests. Cela s’applique également si vous installez le GDF uniquement pour l’utilisateur actuel, puis que vous essayez d’installer le GDF pour tous les utilisateurs. Vous devez d’abord supprimer le jeu des utilisateurs actuels pour que IGameExplorer::AddGame réussisse.

Si vous exécutez l’enum GDFInstall.exe, l’exemple d’application entre dans un autre mode qui énumère tous les jeux Games Explorer installés et vous invite à les supprimer. Vous pouvez également parcourir et rechercher dans le Registre dans HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX pour vous assurer que votre jeu n’est pas installé pour un autre utilisateur sur le système. Toutefois, ne modifiez ces paramètres de Registre à aucune autre fin, car ils ne sont pas garantis pour rester compatibles dans les futures versions du système d’exploitation.

Veiller à signer avec Authenticode

Si vous avez fourni une classification, mais que vous ne la voyez pas dans Games Explorer, vérifiez que vous avez utilisé Authenticode pour signer le fichier exécutable ou DLL qui contient la classification. Games Explorer ignore les informations de classification dans les fichiers non signés. Pour plus d’informations sur Authenticode, consultez Signature avec Authenticode pour les développeurs de jeux.

Vérifier que les contrôles parentaux sont disponibles

Vérifiez que vous testez le contrôle parental sur une édition de Windows Vista qui fournit le contrôle parental : Familiale Basique, Familiale Premium ou Intégrale. Windows Vista Professionnel et Windows Vista Entreprise ne fournissent pas de contrôle parental. Par contre, si vous effectuez les tests sur Windows Vista Édition Intégrale et que l’ordinateur de test est joint à un domaine, vous devez changer un paramètre de stratégie de groupe pour rendre visible le contrôle parental. Pour ce faire, consultez Bien démarrer avec Games Explorer.

Vérifier que les tâches sont du type approprié

Si vous avez spécifié des tâches de support qui n’apparaissent pas dans Games Explorer, vérifiez que ce sont toutes des liens web. Toutes les autres tâches de raccourci doivent être créées en tant que tâches de lecture. Les tâches sont abordées plus haut dans cet article dans Tâches Games Explorer.

Vérifier les données dans un binaire GDF

GDFTrace.exe est un outil trouvé dans le SDK DirectX. Vous pouvez exécuter GDFTrace.exe sur votre fichier binaire GDF, qui générera toutes les métadonnées GDF contenues dans le fichier binaire pour chaque langage pris en charge à des fins de validation rapide. Il affiche également les avertissements relatifs aux informations manquantes ou obsolètes.

Résumé

Games Explorer dans Windows Vista offre un moyen facile et personnalisable de présenter votre jeu aux utilisateurs de Windows Vista, mais il vous oblige également à inscrire le jeu auprès du système pendant le processus d’installation. L’exemple GameUXInstallHelper simplifie considérablement ce processus pour les développeurs.