Esplora giochi di Windows per sviluppatori di giochi

Articolo
12/06/2023

Windows Vista migliora l'esperienza utente di gioco in Windows includendo Games Explorer. Games Explorer è esposto nel menu Start di Windows Vista come cartella Giochi e fornisce una posizione centrale per l'accesso ai giochi.

A partire dalla versione di marzo 2009 di DirectX SDK, viene usato un nuovo schema GDF (Game Definition File) per supportare le funzionalità nel feed Windows 7, Game Provider e RSS e IGameExplorer2. IGameExplorer2 è una nuova interfaccia di Windows 7 che semplifica il processo di integrazione di un gioco con Games Explorer.

Questo articolo illustra il processo di registrazione di un gioco con Games Explorer e i controlli genitori in Windows Vista e Windows 7 usando il nuovo schema GDF.

Nota

Game Explorer non è disponibile in Windows 10, versione 1803 e successive.

Contenuti:

Prerequisiti
Integrazione con un programma di installazione
Processo di integrazione
Attività di Games Explorer
Integrazione in InstallScript
Integrazione in un pacchetto MSI
Suggerimenti sul debug
Riepilogo

Prerequisiti

Prima di poter integrare un gioco in Games Explorer, devi creare un file di definizione del gioco (GDF). Un GDF è un file XML che contiene metadati che descrivono il gioco. Nella versione di marzo 2009 di DirectX SDK, è stata aggiunta una sezione per provider di giochi, feed RSS e attività di gioco allo schema GDF. Per usare le istruzioni contenute in questo articolo, è necessario usare questo nuovo formato GDF per creare il file GDF.

Microsoft offre uno strumento per la creazione di GDF in DirectX SDK, Game Definition File Editor, per semplificare questo processo di creazione. Questo strumento consente anche di creare versioni localizzate di un GDF.

Dopo aver creato e localizzato un GDF, deve essere incapsulato all'interno di una sezione della risorsa di un file binario (eseguibile o DLL), insieme all'anteprima e all'icona del gioco. La GDF contiene tutti i metadati associati al gioco, inclusa la classificazione del gioco. Windows Parental Controls usa la classificazione del gioco per consentire ai genitori di controllare l'accesso al gioco. Il file binario che contiene GDF deve essere firmato digitalmente con un certificato Authenticode valido; in caso contrario, Games Explorer e il sistema di controllo genitori ignora la classificazione del gioco, perché le informazioni sulla classificazione non possono essere considerate attendibili senza certificazione. Per altre informazioni sulla firma del codice con Authenticode, vedere Authenticode Signing for Game Developers (Firma authenticode per sviluppatori di giochi).

Integrazione con un programma di installazione

Per semplificare l'integrazione di Games Explorer, l'esempio GameUXInstallHelper fornisce un'API comune che può essere chiamata in Windows XP, Windows Vista e Windows 7. È progettato per lavorare con script per InstallShield e Wise Installation System, nonché azioni personalizzate MSI e strumenti di installazione personalizzati. Il rilevamento del sistema operativo viene gestito all'interno di questa DLL di esempio, quindi il chiamante non deve preoccuparsi se il client esegue Windows XP, Windows Vista o Windows 7.

Le funzioni esportate da questa DLL sono le seguenti:

GameExplorerInstallW: Registra un gioco con Games Explorer, dato un percorso al file binario GDF, un percorso completo della cartella in cui è installato il gioco e l'ambito di installazione.
GameExplorerInstallA: Registra un gioco con Games Explorer; Versione ANSI di GameExplorerInstallW.
GameExplorerUninstallW: Rimuove un gioco dalla registrazione con Games Explorer, dato un percorso al file binario GDF.
GameExplorerUninstallA: Rimuove un gioco dalla registrazione con Games Explorer; Versione ANSI di GameExplorerUninstallW.
GameExplorerSetMSIProperties: Configura le proprietà CustomActionData per le azioni di un'installazione personalizzata posticipata dell'identità del servizio gestito. L'utilizzo di questa funzione è descritto in dettaglio più avanti in questo articolo.
GameExplorerInstallUsingMSI: Aggiunge un gioco a Games Explorer; per l'uso durante l'installazione di un'azione personalizzata MSI.
GameExplorerUninstallUsingMSI: Rimuovi un gioco da Games Explorer; per l'uso durante l'installazione di un'azione personalizzata MSI.

Queste funzioni sono descritte ulteriormente nell'intestazione GameUXInstallHelper.h.

Processo di integrazione

Dopo aver aggiunto il GDF e i file correlati a una risorsa binaria, è possibile integrare il gioco con Games Explorer. L'uso di GameUXInstallHelper semplifica il processo di integrazione. Per registrare il gioco con Games Explorer, chiama GameExplorerInstall con un percorso del file binario GDF, un percorso completo della cartella in cui è installato il gioco e l'ambito di installazione. Per rimuovere la registrazione del gioco, chiama GameExplorerUninstall con un percorso al file binario GDF.

Si noti che il processo di rimozione rimuove solo un'installazione univoca. Se un gioco è stato installato più volte, questo processo deve essere ripetuto per ogni installazione univoca.

Attività di Games Explorer

Le attività di Games Explorer verranno visualizzate nel menu di scelta rapida di una voce in Games Explorer. Le attività sono suddivise in attività di riproduzione e attività di supporto. Le attività di gioco avviano un gioco in una particolare modalità, mentre le attività di supporto servono a qualsiasi altro scopo, incluso il collegamento ai siti Web.

In Windows Vista le attività sono semplicemente collegamenti che si trovano in cartelle specifiche. Le attività di riproduzione e le attività di supporto vengono archiviate in cartelle con i nomi corrispondenti PlayTasks e SupportTasks. GameUXInstallHelper può leggere le informazioni sulle attività del gioco dal file binario GDF e creare automaticamente tutti i collegamenti.

In Windows 7, i collegamenti alle attività non sono necessari, perché Games Explorer ottiene tutte le informazioni sulle attività direttamente dal file binario GDF.

Integrazione in InstallScript

La chiamata alle API di Games Explorer da InstallScript di InstallShield è semplificata usando l'esempio GameUXInstallHelper. I passaggi necessari per l'integrazione con InstallShield sono i seguenti:

Aprire un progetto InstallScript nell'editor InstallShield.
Aggiungere GameUXInstallHelper.dll al progetto da installare nella directory di destinazione.

Per aggiungere GameUXInstallHelper.dll a un progetto InstallScript:
1. Nella scheda Progettazione installazione fare clic su Dati applicazione nel riquadro di spostamento a sinistra.
2. Fare clic su File e cartelle e sfogliare nelle cartelle del computer di origine per individuare GameUXInstallerHelper.dll nei file del computer di origine.
  
  Il percorso predefinito per GameUXInstallerHelper.dll è DirectX SDK root\Samples\C++\Misc\Bin\x86.
3. In Cartelle del computer di destinazione fare clic su Cartella destinazione applicazione.
4. Trascinare GameUXInstallerHelper.dll dai file del computer di origine ai file del computer di destinazione.
In InstallScript Explorer fare clic sul file InstallScript (in genere setup.rul) che chiama la funzione DLL.

Incollare il codice InstallScript seguente nel file:

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;

Integrazione in un pacchetto MSI

Di seguito è riportata una descrizione generale dei passaggi necessari per chiamare le API di Games Explorer usando azioni personalizzate MSI:

Aggiungere una proprietà alla tabella delle proprietà MSI denominata "RelativePathToGDF" contenente il percorso relativo al file binario GDF.
Dopo l'azione CostFinalize, chiamare la funzione DLL GameUXInstallHelper SetMSIGameExplorerProperties in un'azione personalizzata immediata per impostare le proprietà MSI appropriate per le altre azioni personalizzate.
Dopo l'installazione, attivare un'azione personalizzata posticipata dopo l'azione InstallFiles che chiama la funzione DLL GameUXInstallHelper AddToGameExplorerUsingMSI. Se l'installazione è per tutti gli utenti, l'azione personalizzata deve impostare il flag msidbCustomActionTypeNoImpersonate; in caso contrario, non deve impostare questo flag. Pertanto, vengono definite due azioni personalizzate quasi identiche: GameUXAddAs Amministrazione e GameUXAddAsCurUser.
Dopo la rimozione dell'installazione, attivare un'azione personalizzata posticipata prima dell'azione RemoveFiles che chiama la funzione DLL GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Se l'installazione era per tutti gli utenti, l'azione personalizzata deve impostare il flag msidbCustomActionTypeNoImpersonate; in caso contrario, non deve impostare questo flag. Pertanto, vengono definite due azioni personalizzate quasi identiche: GameUXRemoveAs Amministrazione e GameUXRemoveAsCurUser.
Definire azioni personalizzate di rollback per gestire il caso in cui l'utente annulla l'installazione o la rimozione dopo che una di queste azioni personalizzate è già avvenuta. Ciò comporta altre 4 azioni personalizzate: GameUXRollBackAddAs Amministrazione, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAs Amministrazione e GameUXRollBackRemoveAsCurUser.

Questa procedura è descritta in dettaglio nelle istruzioni seguenti, che descrivono un processo che può essere eseguito usando un editor MSI, ad esempio l'editor Orca disponibile in Platform SDK. Alcuni editor msi hanno procedure guidate che semplificano alcuni di questi passaggi di configurazione.

Per configurare un pacchetto MSI per l'integrazione con Games Explorer

Aprire il pacchetto MSI in Orca.
Aggiungere la riga illustrata nella tabella seguente alla tabella Binary nel pacchetto MSI.

Nome Dati

GAMEUX percorso del file della DLL\GameUXInstallHelper.dll

Nota

Questo file verrà incorporato nel pacchetto MSI, quindi è necessario eseguire questo passaggio ogni volta che si ricompila GameUXInstallHelper.dll.

Nome	Dati
GAMEUX	percorso del file della DLL\GameUXInstallHelper.dll

Aggiungere le righe illustrate nella tabella seguente alla tabella CustomAction nel pacchetto MSI.

Azione	Type	Source	Target
GameUXSetMSIProperties	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue = 65	GAMEUX	SetMSIGameExplorerProperties
GameUXAddAs Amministrazione	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	AddToGameExplorerUsingMSI
GameUXAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	AddToGameExplorerUsingMSI
GameUXRollBackAddAs Amministrazione	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRollBackAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRemoveAs Amministrazione	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRollBackRemoveAs Amministrazione	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	AddToGameExplorerUsingMSI
GameUXRollBackRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	AddToGameExplorerUsingMSI

Aggiungere i valori visualizzati per Action, Condition e Sequence nella tabella seguente alla tabella InstallExecuteSequence nel pacchetto MSI.

Azione	Condizione	Sequence	Note
GameUXSetMSIProperties		1015	Il numero di sequenza inserisce l'azione subito dopo CostFinalize.
GameUXAddAs Amministrazione	NOT Installed AND ALLU edizione Standard RS	4003	Questa azione personalizzata verrà eseguita solo durante una nuova installazione per tutti gli utenti. Il numero di sequenza inserisce l'azione dopo InstallFiles e dopo il rollback.
GameUXAddAsCurUser	NOT Installed AND NOT ALLU edizione Standard RS	4004	Questa azione personalizzata verrà eseguita solo durante una nuova installazione per l'utente corrente. Il numero di sequenza inserisce l'azione dopo InstallFiles e dopo il rollback.
GameUXRollBackAddAs Amministrazione	NOT Installed AND ALLU edizione Standard RS	4001	Questa azione personalizzata verrà eseguita solo quando viene annullata una nuova installazione per tutti gli utenti. Il numero di sequenza inserisce l'azione dopo InstallFiles e prima dell'azione Aggiungi personalizzata.
GameUXRollBackAddAsCurUser	NOT Installed AND NOT ALLU edizione Standard RS	4002	Questa azione personalizzata verrà eseguita solo quando viene annullata una nuova installazione per l'utente corrente. Il numero di sequenza inserisce l'azione dopo InstallFiles e prima dell'azione Aggiungi personalizzata.
GameUXRemoveAs Amministrazione	REMOVE~="ALL" AND ALLU edizione Standard RS	3452	Questa azione personalizzata verrà eseguita solo durante la rimozione per tutti gli utenti. Il numero di sequenza inserisce l'azione direttamente prima di RemoveFiles e dopo il rollback.
GameUXRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLU edizione Standard RS	3453	Questa azione personalizzata verrà eseguita solo durante la rimozione per l'utente corrente. Il numero di sequenza inserisce l'azione direttamente prima di RemoveFiles e dopo il rollback.
GameUXRollBackRemoveAs Amministrazione	REMOVE~="ALL" AND ALLU edizione Standard RS	3450	Questa azione personalizzata verrà eseguita solo quando la rimozione per tutti gli utenti viene annullata. Il numero di sequenza inserisce l'azione direttamente prima di RemoveFiles e prima dell'azione Personalizzata Rimuovi.
GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLU edizione Standard RS	3451	Questa azione personalizzata verrà eseguita solo quando la rimozione per l'utente corrente viene annullata. Il numero di sequenza inserisce l'azione direttamente prima di RemoveFiles e prima dell'azione Personalizzata Rimuovi.

Aggiungere la riga illustrata nella tabella seguente alla tabella Property nel pacchetto MSI.

Proprietà valore

RelativePathToGDF percorso file relativo\nome del file binario che contiene GDF

Nota

Il percorso specificato dal percorso è relativo al percorso specificato dal percorso di installazione. Ad esempio, bin\GDF.dll.
Salvare il pacchetto MSI.

Proprietà	valore
RelativePathToGDF	percorso file relativo\nome del file binario che contiene GDF

Per informazioni più dettagliate sui pacchetti MSI e Windows Installer, vedere Windows Installer.

Suggerimenti sul debug

Di seguito sono riportati alcuni suggerimenti che consentono di eseguire il debug dei problemi quando si chiamano le API di Games Explorer:

Eseguire test con codice di esempio

La compilazione della soluzione di esempio GameUXInstallHelper creerà un GameUXInstallHelper.dll e un GDFInstall.exe. GDFInstall.exe è un'applicazione di esempio che usa GameUXInstallHelper.dll. L'esecuzione di GDFInstall.exe richiederà se si vuole installare o rimuovere un file binario GDF da Esplora giochi. È possibile testare il file binario GDF passandolo come primo arg della riga di comando a GDFInstall.exe.

Se non si dispone di un file binario GDF o l'installazione non riesce, provare a usare GDF di esempio in DirectX SDK. L'esempio GDFExampleBinary è disponibile in DirectX SDK ed è solo una DLL che contiene solo un file GDF. Incluso anche nell'origine è il progetto GDFMaker. È possibile compilarlo e testarlo usando GDFInstall.exe. È anche possibile confrontare il codice XML con il proprio per individuare esattamente dove si trova il problema.

Assicurarsi che il gioco sia stato rimosso correttamente

Se il gioco è già installato in Games Explorer, le chiamate successive a IGameExplorer::AddGame restituiranno E_FAIL quindi assicurarsi che il gioco non sia installato prima del test. Questo vale anche se si installa GDF solo per l'utente corrente e quindi si tenta di installare GDF per tutti gli utenti. Devi prima rimuovere il gioco dagli utenti correnti prima che IGameExplorer::AddGame abbia esito positivo .

Se si esegue l'enumerazione GDFInstall.exe, l'applicazione di esempio passerà a una modalità diversa che enumererà tutti i giochi di Games Explorer installati e chiederà di rimuoverli. È anche possibile esplorare e cercare il Registro di sistema in HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX per assicurarsi che il gioco non sia installato per un altro utente nel sistema. Tuttavia, non modificare queste impostazioni del Registro di sistema per altri scopi, perché non sono garantiti per rimanere compatibili nelle versioni future del sistema operativo.

Assicurarsi di firmare con Authenticode

Se hai fornito una classificazione, ma non la vedi in Games Explorer, assicurati di aver usato Authenticode per firmare il file eseguibile o DLL che contiene la classificazione. Games Explorer ignora le informazioni sulle classificazioni nei file non firmati. Per altre informazioni su Authenticode, vedere Authenticode Signing for Game Developers (Firma authenticode per sviluppatori di giochi).

Assicurarsi che i controlli genitori siano disponibili

Assicurarsi di testare i controlli genitori in un'edizione di Windows Vista che fornisce i controlli genitori: Home Basic, Home Premium o Ultimate. Windows Vista Business e Windows Vista Enterprise non forniscono controlli genitori, ma se si esegue il test in Windows Vista Ultimate e il computer di test viene aggiunto a un dominio, è necessario modificare un'impostazione di criteri di gruppo per rendere visibili i controlli genitori. A tale scopo, vedere Introduzione a Games Explorer.

Verificare che le attività siano del tipo corretto

Se sono state specificate attività di supporto che non vengono visualizzate in Games Explorer, verificare che siano tutti i collegamenti Web. Tutte le altre attività di collegamento devono essere create come attività di riproduzione. Le attività sono descritte in precedenza in questo articolo in Attività di Games Explorer.

Verificare i dati nel file binario GDF

GDFTrace.exe è uno strumento disponibile in DirectX SDK. È possibile eseguire GDFTrace.exe nel file binario GDF e restituirà tutti i metadati GDF contenuti nel file binario per ogni linguaggio supportato per la convalida rapida. Vengono inoltre visualizzati avvisi relativi a informazioni mancanti o obsolete.

Riepilogo

Games Explorer in Windows Vista offre un modo semplice e personalizzabile per presentare il gioco agli utenti di Windows Vista, ma richiede anche di registrare il gioco con il sistema durante il processo di installazione. L'esempio GameUXInstallHelper semplifica notevolmente questo processo per gli sviluppatori.

Condividi tramite