面向游戏开发人员的 Windows 游戏资源管理器

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)。 GDF 是一个 XML 文件，其中包含描述游戏的元数据。 在 DirectX SDK 2009 年 3 月版中，部分游戏提供程序、RSS 源和游戏任务已添加到 GDF 架构中。 若要使用本文中的说明，必须使用这一新的 GDF 格式来创建 GDF 文件。

Microsoft 提供了一个在 DirectX SDK 中创作 GDF 的工具 Game Definition File Editor，以便更轻松地完成此创建过程。 此工具还可帮助创建 GDF 的本地化版本。

在 GDF 创作和本地化之后，它必须与游戏的缩略图和图标一起封装到二进制文件（可执行文件或 DLL）的资源部分中。 GDF 包含与游戏关联的所有元数据，包括游戏分级。 借助游戏分级，Windows 家长控制功能使家长能够控制孩子对游戏的访问。 包含 GDF 的二进制文件必须使用有效的验证码证书进行数字签名；否则，游戏资源管理器和家长控制系统将忽略游戏分级，因为分级信息在未经认证的情况下无法获得信任。 有关使用验证码对代码进行签名的更多详细信息，请参阅面向游戏开发人员的验证码签名。

与安装程序集成

为了简化游戏资源管理器集成，GameUXInstallHelper 示例提供了一个可在 Windows XP、Windows Vista 和 Windows 7 上调用的通用 API。 它适用于 InstallShield 和 Wise Installation System 的脚本，以及 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 可以简化集成过程。 若要向游戏资源管理器注册游戏，请调用 GameExplorerInstall，并提供 GDF 二进制文件的路径、安装游戏的文件夹的完整路径以及安装范围。 若要删除游戏的注册，请调用 GameExplorerUninstall 并提供 GDF 二进制文件的路径。

请注意，删除过程只会删除一个唯一的安装。 如果游戏已安装多次，则必须为每个唯一安装重复此过程。

游戏资源管理器任务

游戏资源管理器任务将显示在游戏资源管理器中项的上下文菜单中。 任务分为播放任务和支持任务。 播放任务将以特定模式启动游戏，而支持任务用于任何其他目的，包括链接到网站。

在 Windows Vista 中，任务只是位于特定文件夹中的快捷方式。 播放任务和支持任务存储在名称为 PlayTasks 和 SupportTasks 的相应文件夹中。 GameUXInstallHelper 可以从 GDF 二进制文件中读取游戏的任务信息，并自动创建所有快捷方式。

在 Windows 7 中，不需要任务快捷方式，因为游戏资源管理器会直接从 GDF 二进制文件获取所有任务信息。

集成到 InstallScript 中

通过使用 GameUXInstallHelper 示例，可以轻松地从 InstallShield 的 InstallScript 调用游戏资源管理器 API。 与 InstallShield 集成所需的步骤如下所示：

1. 在 InstallShield 编辑器中打开 InstallScript 项目。

2. 将 GameUXInstallHelper.dll 添加到要安装到目标目录的项目。

   要将 GameUXInstallHelper.dll 添加到 InstallScript 项目：

   1. 在“安装设计器”选项卡上，单击左侧导航窗格中的“应用程序数据”。

   2. 单击“文件和文件夹”并在源计算机的文件夹中浏览，以在源计算机的文件中查找 GameUXInstallerHelper.dll。

      GameUXInstallerHelper.dll 的默认位置为 DirectX SDK root\Samples\C++\Misc\Bin\x86。

   3. 在目标计算机的文件夹下，单击应用程序目标文件夹。

   4. 将 GameUXInstallerHelper.dll 从源计算机的文件拖动到目标计算机的文件。

3. 在 InstallScript 资源管理器中，单击调用 DLL 函数的 InstallScript 文件（通常是 setup.rul）。

4. 将以下 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 所需步骤的简要说明：

1. 将属性添加到名为“RelativePathToGDF”的 MSI 属性表中，该表包含 GDF 二进制文件的相对路径。
2. 在 CostFinalize 操作之后，在即时自定义操作中调用 GameUXInstallHelper DLL 函数 SetMSIGameExplorerProperties 以设置其他自定义操作的相应 MSI 属性。
3. 安装后，在调用 GameUXInstallHelper DLL 函数 AddToGameExplorerUsingMSI 的 InstallFiles 操作后触发延迟的自定义操作。 如果安装针对的是所有用户，则自定义操作必须设置标志 msidbCustomActionTypeNoImpersonate；否则，不得设置此标志。 因此，定义了两个几乎相同的自定义操作：GameUXAddAsAdmin 和 GameUXAddAsCurUser。
4. 删除安装后，在调用 GameUXInstallHelper DLL 函数 RemoveFromGameExplorerUsingMSI 的 RemoveFiles 操作之前触发延迟的自定义操作。 如果安装针对的是所有用户，则自定义操作必须设置标志 msidbCustomActionTypeNoImpersonate；否则，不得设置此标志。 因此，定义了两个几乎相同的自定义操作：GameUXRemoveAsAdmin 和 GameUXRemoveAsCurUser。
5. 定义回滚自定义操作来处理用户在已执行某一自定义操作后取消或删除安装的情况。 这会导致其他 4 个自定义操作：GameUXRollBackAddAsAdmin、GameUXRollBackAddAsCurUser、GameUXRollBackRemoveAsAdmin 和 GameUXRollBackRemoveAsCurUser。

此过程在以下作了详细介绍，其中说明了可以使用 MSI 编辑器（如平台 SDK 中包含的 Orca 编辑器）完成的流程。 某些 MSI 编辑器具有向导，可简化其中一些配置步骤。

配置 MSI 包以与游戏资源管理器集成

1. 在 Orca 中打开 MSI 包。

2. 将下表中显示的行添加到 MSI 包中的 Binary 表。

   名称	数据
   GAMEUX	DLL\GameUXInstallHelper.dll 的文件路径

    

   注意

   此文件将嵌入到 MSI 包中，因此每次重新编译 GameUXInstallHelper.dll 时都必须执行此步骤。

    

3. 将下表中显示的行添加到 MSI 包中的 CustomAction 表。

   操作	类型	Source	目标
   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. 将下表中针对 Action、Condition 和 Sequence 显示的值添加到 MSI 包中的 InstallExecuteSequence 表。

   操作	条件	序列	说明
   GameUXSetMSIProperties		1015	次序号会将该操作直接置于 CostFinalize 之后。
   GameUXAddAsAdmin	NOT Installed AND ALLUSERS	4003	此自定义操作只能在全新安装期间针对所有用户执行。 次序号会将该操作置于 InstallFiles 之后和回滚之后。
   GameUXAddAsCurUser	NOT Installed AND NOT ALLUSERS	4004	此自定义操作仅在全新安装期间针对当前用户执行。 次序号会将该操作置于 InstallFiles 之后和回滚之后。
   GameUXRollBackAddAsAdmin	NOT Installed AND ALLUSERS	4001	此自定义操作仅在取消所有用户的全新安装时执行。 次序号会将该操作置于 InstallFiles 之后和 Add 自定义操作之前。
   GameUXRollBackAddAsCurUser	NOT Installed AND NOT ALLUSERS	4002	此自定义操作仅在取消当前用户的全新安装时执行。 次序号会将该操作置于 InstallFiles 之后和 Add 自定义操作之前。
   GameUXRemoveAsAdmin	REMOVE~="ALL" AND ALLUSERS	3452	此自定义操作仅在删除期间针对所有用户执行。 次序号会将该操作直接置于 RemoveFiles 之前和回滚之后。
   GameUXRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLUSERS	3453	此自定义操作仅在删除期间针对当前用户执行。 次序号会将该操作直接置于 RemoveFiles 之前和回滚之后。
   GameUXRollBackRemoveAsAdmin	REMOVE~="ALL" AND ALLUSERS	3450	此自定义操作仅在取消所有用户的删除时执行。 次序号会将该操作直接置于 RemoveFiles 之前和 Remove 自定义操作之前。
   GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" AND NOT ALLUSERS	3451	此自定义操作仅在取消当前用户的删除时执行。 次序号会将该操作直接置于 RemoveFiles 之前和 Remove 自定义操作之前。

    

5. 将下表中显示的行添加到 MSI 包中的 Property 表。

   属性	Value
   RelativePathToGDF	相对文件路径\包含 GDF 的二进制文件的名称

    

   注意

   路径指定的位置相对于安装路径指定的位置。 例如 bin\GDF.dll。

    

6. 保存 MSI 包。

有关 MSI 包和 Windows Installer 的更多详细信息，请参阅 Windows Installer。

调试提示

以下是在调用游戏资源管理器 API 时帮助你调试问题的一些提示：

使用示例代码进行测试

生成 GameUXInstallHelper 示例解决方案将创建 GameUXInstallHelper.dll 和 GDFInstall.exe。 GDFInstall.exe 是一个使用 GameUXInstallHelper.dll 的示例应用程序。 运行 GDFInstall.exe 时，系统会提示是否要从游戏资源管理器安装或删除 GDF 二进制文件。 可以通过将 GDF 二进制文件作为第一个命令行参数传递给 GDFInstall.exe 来测试该文件。

如果没有 GDF 二进制文件或安装失败，请尝试使用 DirectX SDK 中的示例 GDF。 GDFExampleBinary 示例位于 DirectX SDK 中，就是一个仅包含 GDF 文件的 DLL。 源中还包括其 GDFMaker 项目。 可以使用 GDFInstall.exe 来生成并测试它。 还可以将它的 XML 与你的 XML 进行比较，以准确查明造成问题的原因。

确保游戏已正确删除

如果游戏已在游戏资源管理器中安装，则后续调用 IGameExplorer::AddGame 将返回 E_FAIL，因此请确保在测试之前未安装相关游戏。 如果仅为当前用户安装了 GDF，然后要尝试为所有用户安装 GDF，这一点也适用。 必须先从当前用户中删除游戏，然后 IGameExplorer::AddGame 才会调用成功。

如果运行 GDFInstall.exe 枚举，示例应用程序将进入另一种模式，该模式将枚举所有已安装的游戏资源管理器游戏并提示删除它们。 还可以在 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX 中浏览和搜索注册表，以确保系统上的其他用户没有安装您的游戏。 但是，请勿出于任何其他目的更改这些注册表设置，因为不能保证它们在未来版本的操作系统中保持兼容。

请务必使用验证码进行签名

如果已提供分级，但在游戏资源管理器中未看到分级，请确保已使用验证码对包含该分级的可执行文件或 DLL 文件进行签名。 游戏资源管理器会忽略未签名文件中的分级信息。 有关验证码的详细信息，请参阅游戏开发人员的验证码签名。

确保家长控制功能可用

确保在提供家长控制功能的 Windows Vista 版本上测试该功能：家庭普通版、家庭高级版或旗舰版。 Windows Vista 商用版和 Windows Vista 企业版不提供家长控制功能，但如果在 Windows Vista 旗舰版上进行测试且测试计算机已加入域，则必须更改组策略设置，使家长控制功能可见。 要执行此操作，请参阅游戏资源管理器入门。

验证任务的类型是否正确

如果指定了不在游戏资源管理器中显示的支持任务，请验证它们是否都是 Web 链接。 任何其他快捷任务都必须创建为播放任务。 任务在本文前面的游戏资源管理器任务中作了介绍。

验证 GDF 二进制文件中的数据

GDFTrace.exe 是 DirectX SDK 中的工具。 可以在 GDF 二进制文件上运行 GDFTrace.exe，这将为每种受支持的语言输出二进制文件中包含的所有 GDF 元数据，以便进行快速验证。 该操作还会显示有关缺失或过时信息的所有警告。

总结

Windows Vista 中的游戏资源管理器提供了一种简单、可自定义的方式来向 Windows Vista 用户展示你的游戏，但这也需要在安装过程中将游戏注册到系统中。 GameUXInstallHelper 示例极大地简化了开发人员执行此过程的难度。