Windows Games Explorer para desenvolvedores de jogos

O Windows Vista melhora a experiência do usuário de jogos no Windows incluindo o Games Explorer. O Games Explorer é exposto no Menu Iniciar do Windows Vista como a pasta Jogos e fornece um local central para acessar jogos.

A partir da versão de março de 2009 do SDK do DirectX, um novo esquema de arquivo de definição de jogo (GDF) é usado para oferecer suporte a recursos no Windows 7, no Provedor de Jogos e no RSS feed e no IGameExplorer2. IGameExplorer2 é uma nova interface no Windows 7 que simplifica o processo de integração de um jogo com o Games Explorer.

Este artigo descreve o processo de registro de um jogo com o Game Explorer e controle dos pais no Windows Vista e Windows 7 usando o novo esquema GDF.

Observação

O Gerenciador de Jogos não está disponível no Windows 10, versão 1803 e posterior.

Conteúdo:

• Pré-requisitos
• Integrando com um instalador
• Processo de Integração
• Tarefas do Games Explorer
• Integrando-se ao InstallScript
• Integrando em um pacote MSI
• Dicas de depuração
  • Teste com código de exemplo
  • Certifique-se de que o jogo foi removido corretamente
  • Certifique-se de assinar usando Authenticode
  • Certifique-se de que os controles dos pais estão disponíveis
  • Verifique se as tarefas são do tipo correto
  • Verifique os dados no binário GDF
• Resumo

Pré-requisitos

Antes de integrar um jogo ao Games Explorer, você deve criar um arquivo de definição de jogo (GDF). Um GDF é um arquivo XML que contém metadados que descrevem o jogo. Na versão de março de 2009 do SDK do DirectX, uma seção para provedor de jogos, RSS feed e tarefa de jogo foi adicionada ao esquema GDF. Para usar as instruções neste artigo, você deve usar esse novo formato GDF para criar seu arquivo GDF.

A Microsoft fornece uma ferramenta para criar GDFs no SDK do DirectX, Editor de Arquivos de Definição de Jogo, para facilitar esse processo de criação. Essa ferramenta também ajuda a criar versões localizadas de um GDF.

Depois que um GDF é criado e localizado, ele deve ser encapsulado em uma seção de recursos de um arquivo binário (um executável ou DLL), juntamente com a miniatura e o ícone do jogo. O GDF contém todos os metadados associados ao jogo, incluindo a classificação do jogo. Os Controles dos Pais do Windows usam a classificação do jogo para permitir que os pais controlem o acesso ao jogo. O arquivo binário que contém o GDF deve ser assinado digitalmente com um certificado Authenticode válido; caso contrário, o Games Explorer e o sistema de controle dos pais ignoram a classificação do jogo, porque as informações de classificação não podem ser fidedignas sem certificação. Para obter mais detalhes sobre como assinar código com o Authenticode, consulte Assinatura de Authenticode para desenvolvedores de jogos.

Integração com um instalador

Para simplificar a integração do Games Explorer, o exemplo GameUXInstallHelper fornece uma API comum que pode ser chamada no Windows XP, Windows Vista e Windows 7. Ele foi projetado para trabalhar com scripts para InstallShield e Wise Installation System, bem como ações personalizadas MSI e ferramentas de instalação personalizadas. A detecção do sistema operacional é manipulada dentro dessa DLL de exemplo, portanto, o chamador não precisa se preocupar se o cliente está executando o Windows XP, Windows Vista ou Windows 7.

As funções exportadas por esta DLL são as seguintes:

GameExplorerInstallW

Registra um jogo com o Games Explorer, dado um caminho para o binário GDF, um caminho completo para a pasta onde o jogo está instalado e o escopo de instalação.

GameExplorerInstallA

Registra um jogo com o Games Explorer; Versão ANSI do GameExplorerInstallW.

GameExplorerUninstallW

Remove um jogo do registro no Games Explorer, dado um caminho para o binário GDF.

GameExplorerDesinstalarA

Remove um jogo do registro no Games Explorer; Versão ANSI do GameExplorerUninstallW.

GameExplorerSetMSIProperties

Configura as propriedades CustomActionData para as ações de uma instalação personalizada adiada MSI. O uso dessa função é descrito em detalhes mais adiante neste artigo.

GameExplorerInstallUsingMSI

Adiciona um jogo ao Games Explorer; para uso durante uma instalação de ação personalizada MSI.

GameExplorerUninstallUsingMSI

Remover um jogo do Games Explorer; para uso durante uma instalação de ação personalizada MSI.

Essas funções são explicadas mais detalhadamente no cabeçalho GameUXInstallHelper.h.

Processo de integração

Uma vez que o GDF e arquivos relacionados foram adicionados a um recurso binário, é então possível integrar o jogo com o Games Explorer. O uso do GameUXInstallHelper simplificará o processo de integração. Para registrar o jogo no Games Explorer, chame o GameExplorerInstall com um caminho para o binário GDF, um caminho completo para a pasta onde o jogo está instalado e o escopo de instalação. Para remover o registro do jogo, chame GameExplorerUninstall com um caminho para o binário GDF.

Observe que o processo de remoção remove apenas uma instalação exclusiva. Se um jogo tiver sido instalado várias vezes, esse processo deverá ser repetido para cada instalação exclusiva.

Tarefas do Games Explorer

As tarefas do Games Explorer aparecerão no menu de contexto de um item no Games Explorer. As tarefas são divididas em tarefas de jogo e tarefas de suporte. As tarefas de jogo iniciam um jogo em um modo específico, enquanto as tarefas de suporte servem a qualquer outro propósito, incluindo links para sites.

No Windows Vista, as tarefas são simplesmente atalhos localizados em pastas específicas. As tarefas de reprodução e as tarefas de suporte são armazenadas em pastas com os nomes correspondentes PlayTasks e SupportTasks. GameUXInstallHelper pode ler as informações da tarefa do jogo a partir do arquivo binário GDF e criar todos os atalhos automaticamente.

No Windows 7, os atalhos para as tarefas não são necessários, porque o Games Explorer obtém todas as informações da tarefa diretamente do arquivo binário GDF.

Integrando ao InstallScript

Chamar APIs do Games Explorer a partir do InstallScript do InstallShield é facilitado usando o exemplo GameUXInstallHelper. As etapas necessárias para a integração com o InstallShield são as seguintes:

1. Abra um projeto InstallScript no editor do InstallShield.

2. Adicione o GameUXInstallHelper.dll ao projeto a ser instalado no diretório de destino.

   Para adicionar o GameUXInstallHelper.dll a um projeto InstallScript:

   1. Na guia Designer de Instalação clique em Dados do Aplicativo no painel de navegação à esquerda.

   2. Clique em Arquivos e pastas e navegue em Pastas do computador de origem para localizar GameUXInstallerHelper.dll em Arquivos do computador de origem.

      O local padrão para GameUXInstallerHelper.dll é DirectX SDK root\Samples\C++\Misc\Bin\x86.

   3. Em Pastas do computador de destino, clique em Pasta de destino do aplicativo.

   4. Arraste GameUXInstallerHelper.dll de Arquivos do computador de origem para Arquivos do computador de destino.

3. No explorador InstallScript, clique no arquivo InstallScript (geralmente setup.rul) que chama a função DLL.

4. Cole o seguinte InstallScript no arquivo:

   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;
   

Integrando-se a um pacote MSI

A seguir está uma descrição de alto nível das etapas necessárias para chamar as APIs do Games Explorer usando ações personalizadas MSI:

1. Adicione uma propriedade à tabela de propriedades MSI chamada "RelativePathToGDF" que contém o caminho relativo para o binário GDF.
2. Após a ação CostFinalize, chame a função DLL GameUXInstallHelper SetMSIGameExplorerProperties em uma ação personalizada imediata para definir as propriedades MSI apropriadas para as outras ações personalizadas.
3. Após a instalação, dispare uma ação personalizada adiada após a ação InstallFiles que chama a função DLL GameUXInstallHelper AddToGameExplorerUsingMSI. Se a instalação for para todos os usuários, a ação personalizada deverá definir o sinalizador msidbCustomActionTypeNoImpersonate; caso contrário, ele não deve definir esse sinalizador. Portanto, duas ações personalizadas quase idênticas são definidas: GameUXAddAsAdmin e GameUXAddAsCurUser.
4. Após a remoção da instalação, dispare uma ação personalizada adiada antes da ação RemoveFiles que chama a função DLL GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Se a instalação foi para todos os usuários, a ação personalizada deve definir o sinalizador msidbCustomActionTypeNoImpersonate; caso contrário, ele não deve definir esse sinalizador. Portanto, duas ações personalizadas quase idênticas são definidas: GameUXRemoveAsAdmin e GameUXRemoveAsCurUser.
5. Defina ações personalizadas de reversão para lidar com o caso em que o usuário cancela a instalação ou remoção depois que uma dessas ações personalizadas já tiver acontecido. Isso resulta em mais 4 ações personalizadas: GameUXRollBackAddAsAdmin, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAsAdmin e GameUXRollBackRemoveAsCurUser.

Esse procedimento é descrito em detalhes nas instruções a seguir, que descrevem um processo que pode ser feito usando um editor MSI, como o editor Orca encontrado no Platform SDK. Alguns editores MSI têm assistentes que simplificam algumas dessas etapas de configuração.

Para configurar um pacote MSI para integração com o Games Explorer

1. Abra o pacote MSI no Orca.

2. Adicione a linha mostrada na tabela a seguir à tabela Binary no pacote MSI.

   Nome	Dados
   GAMEUX	caminho do arquivo para a DLL\GameUXInstallHelper.dll

    

   Observação

   Esse arquivo será incorporado no pacote MSI, então você deve fazer esta etapa toda vez que recompilar GameUXInstallHelper.dll.

    

3. Adicione as linhas mostradas na tabela a seguir à tabela CustomAction no pacote MSI.

   Ação	Tipo	Origem	Destino
   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. Adicione os valores mostrados para Action, Condition e Sequence na tabela a seguir à tabela InstallExecuteSequence no pacote MSI.

   Ação	Condição	Sequência	Observações
   GameUXSetMSIProperties		1015	O número de sequência coloca a ação logo após CostFinalize.
   GameUXAddAsAdmin	NÃO instalado E ALLUSERS	4003	Essa ação personalizada só acontecerá durante uma nova instalação para todos os usuários. O número de sequência coloca a ação após InstallFiles e após as reversões.
   GameUXAddAsCurUser	NÃO instalado E NÃO ALLUSERS	4004	Essa ação personalizada só acontecerá durante uma nova instalação somente para o usuário atual. O número de sequência coloca a ação após InstallFiles e após as reversões.
   GameUXRollBackAddAsAdmin	NÃO instalado E ALLUSERS	4001	Essa ação personalizada só acontecerá quando uma nova instalação para todos os usuários for cancelada. O número de sequência coloca a ação após InstallFiles e antes da ação Adicionar personalizada.
   GameUXRollBackAddAsCurUser	NÃO instalado E NÃO ALLUSERS	4002	Essa ação personalizada só acontecerá quando uma nova instalação somente para o usuário atual for cancelada. O número de sequência coloca a ação após InstallFiles e antes da ação Adicionar personalizada.
   GameUXRemoveAsAdmin	REMOVE~="ALL" E ALLUSERS	3452	Essa ação personalizada só acontecerá durante a remoção para todos os usuários. O número de sequência coloca a ação diretamente antes de RemoveFiles e após as reversões.
   GameUXRemoveAsCurUser	REMOVE~="ALL" E NÃO ALLUSERS	3453	Essa ação personalizada só acontecerá durante a remoção para o usuário atual. O número de sequência coloca a ação diretamente antes de RemoveFiles e após as reversões.
   GameUXRollBackRemoveAsAdmin	REMOVE~="ALL" E ALLUSERS	3450	Essa ação personalizada só acontecerá quando a remoção para todos os usuários for cancelada. O número de sequência coloca a ação diretamente antes de RemoveFiles e antes da ação personalizada Remover.
   GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" E NÃO ALLUSERS	3451	Essa ação personalizada só acontecerá quando a remoção do usuário atual for cancelada. O número de sequência coloca a ação diretamente antes de RemoveFiles e antes da ação personalizada Remover.

    

5. Adicione a linha mostrada na tabela a seguir à tabela Property no pacote MSI.

   Propriedade	Valor
   RelativePathToGDF	caminho do arquivo relativo\nome do arquivo binário que contém o GDF

    

   Observação

   O local especificado pelo caminho é relativo ao local especificado pelo caminho de instalação. Por exemplo, bin\GDF.dll.

    

6. Salve o pacote MSI.

Para obter informações mais detalhadas sobre pacotes MSI e o Windows Installer, consulte Windows Installer.

Dicas de depuração

A seguir estão algumas dicas para ajudar a depurar problemas ao chamar APIs do Games Explorer:

Teste com código de exemplo

A criação da solução de exemplo GameUXInstallHelper criará um GameUXInstallHelper.dll e um GDFInstall.exe. O GDFInstall.exe é um aplicativo de exemplo que usa GameUXInstallHelper.dll. Executando GDFInstall.exe irá perguntar se você deseja instalar ou remover um binário GDF do explorador de jogos. Você pode testar seu arquivo binário GDF passando-o como a primeira linha de comando arg para GDFInstall.exe.

Se você não tiver um binário GDF ou se o seu não conseguir instalar, tente usar o GDF de exemplo no SDK do DirectX. O exemplo GDFExampleBinary é encontrado no SDK do DirectX e é apenas uma DLL que contém apenas um arquivo GDF. Também está incluído na fonte o projeto GDFMaker. Você pode compilá-lo e testá-lo usando GDFInstall.exe. Você também pode comparar seu XML com o seu para identificar exatamente onde está o problema.

Certifique-se de que o jogo foi removido corretamente

Se o jogo já estiver instalado no Games Explorer, as chamadas subsequentes para IGameExplorer::AddGame retornarão E_FAIL portanto, certifique-se de que o jogo não esteja instalado antes do teste. Isso também se aplica se você instalar o GDF apenas para o usuário atual e, em seguida, tentar instalar o GDF para todos os usuários. Você deve primeiro remover o jogo dos usuários atuais antes que IGameExplorer::AddGame tenha êxito.

Se você executar GDFInstall.exe enum, o aplicativo de exemplo entrará em um modo diferente que enumerará todos os jogos do Games Explorer instalados e solicitará que você os remova. Você também pode procurar e pesquisar o registro em HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX para garantir que seu jogo não esteja instalado para outro usuário no sistema. No entanto, não altere essas configurações do Registro para qualquer outra finalidade, pois não é garantido que permaneçam compatíveis em versões futuras do sistema operacional.

Certifique-se de assinar usando Authenticode

Se você forneceu uma classificação, mas não a está vendo no Games Explorer, verifique se você usou o Authenticode para assinar o arquivo executável ou DLL que contém a classificação. O Games Explorer ignora as informações de classificação em arquivos não assinados. Para obter mais informações sobre o Authenticode, consulte Assinatura de Authenticode para desenvolvedores de jogos.

Certifique-se de que os controles dos pais estão disponíveis

Verifique se você está testando os controle dos pais em uma edição do Windows Vista que fornece controle dos pais: Home Basic, Home Premium ou Ultimate. O Windows Vista Business e o Windows Vista Enterprise não fornecem controle dos pais, no entanto, se você estiver testando no Windows Vista Ultimate e o computador de teste estiver associado a um domínio, altere uma configuração de diretiva de grupo para tornar os controle dos pais visíveis. Para fazer isso, consulte Introdução ao Games Explorer.

Verifique se as tarefas são do tipo correto

Se você tiver especificado tarefas de suporte que não aparecem no Games Explorer, verifique se são todos links da Web. Quaisquer outras tarefas de atalho devem ser criadas como tarefas de reprodução. As tarefas são abordadas anteriormente neste artigo em Tarefas do Games Explorer.

Verifique os dados no binário GDF

GDFTrace.exe é uma ferramenta encontrada no SDK do DirectX. Você pode executar o GDFTrace.exe em seu binário GDF e ele produzirá todos os metadados GDF contidos no binário para cada idioma suportado para validação rápida. Ele também exibe quaisquer avisos sobre informações ausentes ou desatualizadas.

Resumo

O Games Explorer no Windows Vista fornece uma maneira fácil e personalizável de apresentar seu jogo aos usuários do Windows Vista, mas também requer que você registre o jogo no sistema durante o processo de instalação. O exemplo GameUXInstallHelper simplifica muito esse processo para desenvolvedores.