適用於遊戲開發人員的 Windows 遊戲總管

發行項
12/21/2023

Windows Vista 可藉由包含遊戲總管來改善 Windows 上遊戲的用戶體驗。遊戲總管會在 Windows Vista [開始] 選單中公開為 [遊戲] 資料夾，並提供存取遊戲的中央位置。

從 DirectX SDK 的 2009 年 3 月版本開始，新的遊戲定義檔（GDF）架構可用來支援 Windows 7、遊戲提供者和 RSS 摘要和 IGameExplorer2 中的功能。 IGameExplorer2 是 Windows 7 上的新介面，可簡化遊戲與遊戲總管整合的程式。

本文概述使用新的 GDF 架構，在 Windows Vista 和 Windows 7 上使用遊戲總管和家長控制來註冊遊戲的程式。

注意

Windows 10 版本 1803 和更新版本中無法使用遊戲總管。

內容：

先決條件
與安裝程式整合
整合程式
遊戲總管工作
整合至 InstallScript
整合到 MSI 套件中
偵錯提示
摘要

必要條件

您必須先建立遊戲定義檔（GDF）才能將遊戲整合到遊戲總管中。 GDF 是一個 XML 檔案，其中包含描述遊戲的元數據。在 DirectX SDK 2009 年 3 月版本中，遊戲提供者、RSS 摘要和遊戲工作的區段已新增至 GDF 架構。若要使用本文中的指示，您必須使用此新的 GDF 格式來建立 GDF 檔案。

Microsoft 提供一個工具，可在 DirectX SDK、遊戲定義檔案編輯器中撰寫 GDF，以簡化此建立程式。此工具也可協助您建立 GDF 的當地語系化版本。

一旦撰寫並當地語系化 GDF，它就必須封裝在二進位檔的資源區段中（可執行檔或 DLL），以及遊戲的縮圖和圖示。 GDF 包含與遊戲相關聯的所有元數據，包括遊戲的評等。 Windows 家長監護會使用遊戲的評等，讓家長控制遊戲的存取權。包含 GDF 的二進位文件必須使用有效的 Authenticode 憑證進行數字簽署;否則，遊戲總管和家長控制系統會忽略遊戲的評等，因為沒有認證就無法信任評等資訊。如需使用 Authenticode 簽署程式代碼的詳細資訊，請參閱 Game 開發人員的 Authenticode 簽署。

與安裝程式整合

為了簡化遊戲總管整合，GameUXInstallHelper 範例提供可在 Windows XP、Windows Vista 和 Windows 7 上呼叫的常見 API。其設計目的是使用 InstallShield 和 Wise 安裝系統的腳本，以及 MSI 自定義動作和自定義安裝工具。此範例 DLL 內會處理作業系統的偵測，因此呼叫端不需要擔心用戶端是否執行 Windows XP、Windows Vista 或 Windows 7。

此 DLL 匯出的函式如下：

GameExplorerInstallW: 向遊戲總管註冊遊戲，並提供 GDF 二進位檔的路徑、安裝遊戲所在資料夾的完整路徑，以及安裝範圍。
GameExplorerInstallA: 向遊戲總管註冊遊戲;GameExplorerInstallW 的 ANSI 版本。
GameExplorerUninstallW: 在 GDF 二進位檔的路徑下，從遊戲總管的註冊中移除遊戲。
GameExplorerUninstallA: 從遊戲總管的註冊中移除遊戲;GameExplorerUninstallW 的 ANSI 版本。
GameExplorerSetMSIProperties: 設定 MSI 延後自定義安裝動作的 CustomActionData 屬性。本文稍後會詳細說明此函式的使用方式。
GameExplorerInstallUsingMSI: 將遊戲新增至遊戲總管;用於 MSI 自定義動作安裝期間。
GameExplorerUninstallUsingMSI: 從遊戲總管移除遊戲;用於 MSI 自定義動作安裝期間。

這些函式會在 GameUXInstallHelper.h 標頭中進一步說明。

整合程式

將 GDF 和相關檔案新增至二進位資源之後，就可以將遊戲與遊戲總管整合。使用 GameUXInstallHelper 可簡化整合程式。若要向遊戲總管註冊遊戲，請使用 GDF 二進位檔的路徑呼叫 GameExplorerInstall 、遊戲安裝所在資料夾的完整路徑，以及安裝範圍。若要移除遊戲的註冊，請使用 GDF 二進位檔的路徑呼叫 GameExplorerUninstall 。

請注意，移除程式只會移除一個唯一的安裝。如果遊戲已安裝多次，則必須針對每個唯一安裝重複此程式。

遊戲總管工作

遊戲總管工作會出現在遊戲總管中項目的內容功能表中。工作分為播放工作和支援工作。播放工作會將遊戲啟動為特定模式，而支援工作則提供任何其他用途，包括連結至網站。

在 Windows Vista 中，工作只是位於特定資料夾中的快捷方式。播放工作和支援工作會儲存在具有對應名稱 PlayTasks 和 SupportTasks 的資料夾中。 GameUXInstallHelper 可以從 GDF 二進位檔讀取遊戲的工作資訊，並自動建立所有快捷方式。

在 Windows 7 中，不需要工作的快捷方式，因為遊戲總管會直接從 GDF 二進位檔取得所有工作資訊。

整合至 InstallScript

使用 GameUXInstallHelper 範例，即可從 InstallShield 的 InstallScript 呼叫遊戲總管 API。與 InstallShield 整合所需的步驟如下：

在 InstallShield 編輯器中開啟 InstallScript 專案。
將 GameUXInstallHelper.dll 新增至要安裝至目標目錄的專案。

若要將 GameUXInstallHelper.dll 新增至 InstallScript 專案：
1. 在 [ 安裝設計工具] 索引卷標上，按下左側瀏覽窗格中的 [ 應用程式數據 ]。
2. 按兩下 [檔案和資料夾]，然後流覽來源電腦資料夾中的 GameUXInstallerHelper.dll。
  
  GameUXInstallerHelper.dll 的預設位置是 DirectX SDK root\Samples\C++\Misc\Bin\x86。
3. 在 [目的地計算機的資料夾] 下，按兩下 [ 應用程式目標資料夾]。
4. 將 GameUXInstallerHelper.dll 從 來源電腦的檔案 拖曳至 目的地電腦的檔案。
在 InstallScript 總管中，按兩下呼叫 DLL 函式的 InstallScript 檔案（通常是 setup.rul）。

將下列 InstallScript 貼到檔案中：

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;

整合到 MSI 套件中

以下是使用 MSI 自訂動作呼叫遊戲總管 API 所需步驟的高階描述：

將屬性新增至名為「RelativePathToGDF」的 MSI 屬性數據表，其中包含 GDF 二進位檔的相對路徑。
在 CostFinalize 宏指令之後，在立即自定義動作中呼叫 GameUXInstallHelper DLL 函 式 SetMSIGameExplorerProperties ，以設定其他自定義動作的適當 MSI 屬性。
安裝時，請在呼叫 GameUXInstallHelper DLL 函式 AddToGameExplorerUsingMSI 的 InstallFiles 動作之後觸發延後自定義動作。如果安裝適用於所有使用者，則自定義動作必須設定 msidbCustomActionTypeNoImpersonate 旗標;否則，它不得設定此旗標。因此，定義了兩個幾乎完全相同的自定義動作：GameUXAddAs 管理員和 GameUXAddAsCurUser。
拿掉安裝之後，請在呼叫 GameUXInstallHelper DLL 函式 RemoveFromGameExplorerUsingMSI 的 RemoveFiles 動作之前觸發延後自定義動作。如果安裝適用於所有使用者，則自定義動作必須設定 msidbCustomActionTypeNoImpersonate 旗標;否則，它不得設定此旗標。因此，定義了兩個幾乎完全相同的自定義動作：GameUXRemoveAs 管理員和 GameUXRemoveAsCurUser。
定義復原自定義動作，以處理使用者在其中一個自定義動作發生之後取消安裝或移除的情況。這會產生額外的 4 個自定義動作：GameUXRollBackAddAs 管理員、GameUXRollBackAddAsCurUser、GameUXRollBackRemoveAs 管理員和 GameUXRollBackRemoveAsCurUser。

下列指示會詳細說明此程式，其描述可使用 MSI 編輯器完成的程式，例如平臺 SDK 中找到的 Orca 編輯器。有些 MSI 編輯器有精靈，可簡化其中一些設定步驟。

設定 MSI 套件以與遊戲總管整合

在 Orca 中開啟 MSI 套件。
將下表中顯示的數據列新增至 MSI 套件中的二進位 數據表。

名稱資料

GAMEUX DLL\GameUXInstallHelper.dll 的檔案路徑

注意

此檔案會內嵌在 MSI 套件中，因此每次重新編譯 GameUXInstallHelper.dll 時，都必須執行此步驟。

名稱	資料
GAMEUX	DLL\GameUXInstallHelper.dll 的檔案路徑

將下表中顯示的數據列新增至 MSI 套件中的 CustomAction 數據表。

動作	類型	來源	Target
GameUXSetMSIProperties	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue = 65	GAMEUX	SetMSIGameExplorerProperties
GameUXAddAs 管理員	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	AddToGameExplorerUsingMSI
GameUXAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	AddToGameExplorerUsingMSI
GameUXRollBackAddAs 管理員	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRollBackAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRemoveAs 管理員	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	RemoveFromGameExplorerUsingMSI
GameUXRollBackRemoveAs 管理員	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	AddToGameExplorerUsingMSI
GameUXRollBackRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	AddToGameExplorerUsingMSI

將下表中針對 Action、Condition 和 Sequence 顯示的值新增至 MSI 套件中的 InstallExecuteSequence 數據表。

動作	Condition	序列	備註
GameUXSetMSIProperties		1015	序號會在 CostFinalize 之後不久放置動作。
GameUXAddAs 管理員	未安裝且 ALLUSERS	4003	此自定義動作只會在所有使用者的全新安裝期間發生。序號會將動作放在 InstallFiles 之後和復原之後。
GameUXAddAsCurUser	未安裝且未安裝 ALLUSERS	4004	此自定義動作只會在目前使用者的全新安裝期間發生。序號會將動作放在 InstallFiles 之後和復原之後。
GameUXRollBackAddAs 管理員	未安裝且 ALLUSERS	4001	只有在取消所有使用者的全新安裝時，才會發生此自定義動作。序號會將動作放在 InstallFiles 之後，以及 [新增自定義動作] 之前。
GameUXRollBackAddAsCurUser	未安裝且未安裝 ALLUSERS	4002	只有在取消目前使用者的全新安裝時，才會發生此自定義動作。序號會將動作放在 InstallFiles 之後，以及 [新增自定義動作] 之前。
GameUXRemoveAs 管理員	REMOVE~=“ALL” AND ALLUSERS	3452	此自定義動作只會在移除所有用戶期間發生。序號會將動作直接放在 RemoveFiles 和復原之後。
GameUXRemoveAsCurUser	REMOVE~=“ALL” AND NOT ALLUSERS	3453	此自定義動作只會在移除目前用戶期間發生。序號會將動作直接放在 RemoveFiles 和復原之後。
GameUXRollBackRemoveAs 管理員	REMOVE~=“ALL” AND ALLUSERS	3450	只有在取消所有使用者的移除時，才會發生此自定義動作。序號會將動作直接放在 RemoveFiles 之前，以及 Remove 自定義動作之前。
GameUXRollBackRemoveAsCurUser	REMOVE~=“ALL” AND NOT ALLUSERS	3451	只有在取消目前使用者的移除時，才會發生此自定義動作。序號會將動作直接放在 RemoveFiles 之前，以及 Remove 自定義動作之前。

將下表中顯示的數據列新增至 MSI 套件中的 Property 數據表。

屬性值

RelativePathToGDF 包含 GDF 之二進位檔的相對檔案路徑\名稱

注意

路徑所指定的位置相對於安裝路徑所指定的位置。例如 bin\GDF.dll。
儲存 MSI 套件。

屬性	值
RelativePathToGDF	包含 GDF 之二進位檔的相對檔案路徑\名稱

如需 MSI 套件和 Windows Installer 的詳細資訊，請參閱 Windows Installer。

偵錯提示

以下是呼叫遊戲總管 API 時協助偵錯問題的一些秘訣：

使用範例程式代碼進行測試

建置 GameUXInstallHelper 範例解決方案將會建立 GameUXInstallHelper.dll 和 GDFInstall.exe。 GDFInstall.exe 是使用 GameUXInstallHelper.dll 的範例應用程式。如果您想要從遊戲總管安裝或移除 GDF 二進位檔，執行 GDFInstall.exe 將會提示您。您可以將 GDF 二進位檔當做第一個命令行 arg 傳遞至 GDFInstall.exe，以測試 GDF 二進位檔。

如果您沒有 GDF 二進位檔或無法安裝，請嘗試在 DirectX SDK 中使用範例 GDF。 GDFExampleBinary 範例位於 DirectX SDK 中，而且只是只包含 GDF 檔案的 DLL。來源中也包含其 GDFMaker 專案。您可以使用 GDFInstall.exe 來建置並進行測試。您也可以比較其 XML 與，以精確找出問題所在位置。

請確定您的遊戲已正確移除

如果遊戲已安裝在遊戲總管中，則後續呼叫 IGameExplorer：：AddGame 將會傳回E_FAIL，因此在測試之前，請確定未安裝您的遊戲。如果您只為目前使用者安裝 GDF，然後嘗試為所有使用者安裝 GDF，也會套用此動作。您必須先從目前的使用者移除遊戲，IGameExplorer ：：AddGame 才會成功。

如果您執行 GDFInstall.exe 列舉，範例應用程式會進入不同的模式，以列舉所有已安裝的遊戲總管遊戲，並提示您移除它們。您也可以在 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX 中瀏覽並搜尋登錄，以確定您的遊戲未針對系統上的另一位使用者安裝。不過，請勿針對任何其他用途改變這些登錄設定，因為它們不保證在未來版本的操作系統中保持相容。

請務必使用 Authenticode 簽署

如果您已提供評等，但在遊戲總管中看不到該評等，請確定您已使用 Authenticode 簽署包含評等的可執行檔或 DLL 檔案。遊戲總管會忽略未簽署檔案中的評等資訊。如需 Authenticode 的詳細資訊，請參閱遊戲開發人員的 Authenticode 簽署。

請確定家長監護功能可供使用

請確定您在提供家長監護的 Windows Vista 版本上測試家長控制：家用基本版、家庭進階版或 Ultimate。 Windows Vista Business 和 Windows Vista Enterprise 不會提供家長監護，不過，如果您要在 Windows Vista Ultimate 上進行測試，而且測試計算機已加入網域，您必須變更組策略設定，讓家長監護保持可見。若要這樣做，請參閱開始使用遊戲總管。

確認工作類型正確

如果您指定的支援工作未出現在 [遊戲總管] 中，請確認它們是所有網頁連結。任何其他快捷方式工作都必須建立為播放工作。本文稍早在遊戲總管工作中涵蓋工作。

確認 GDF 二進位檔中的數據

GDFTrace.exe 是在 DirectX SDK 中找到的工具。您可以在 GDF 二進位檔上執行 GDFTrace.exe，它會針對每個支援的語言輸出二進位檔中包含的所有 GDF 元數據，以進行快速驗證。它也會顯示任何有關遺失或過時資訊的警告。

摘要

Windows Vista 中的遊戲總管提供簡單、可自定義的方式，將遊戲呈現給 Windows Vista 的使用者，但也要求您在安裝程式期間向系統註冊遊戲。 GameUXInstallHelper 範例可大幅簡化開發人員的此程式。

共用方式為