自定义安装操作

许多游戏会使用反作弊和其他中间件。当用户安装游戏时,这些组件通常会以链式安装的方式安装。用户可能通过 Microsoft Store 安装一款游戏,又通过其他分发渠道安装另一款游戏。平台会确保:即使两款游戏都链式安装同一个中间件包,也不会出现冲突。游戏可以在其包中包含一个或多个任意的 .exe 或 .msi 文件,并要求在完成应用安装时运行这些文件。自定义安装操作功能主要用于安装游戏反作弊软件或其他可再发行的中间件。通过这种方式,你可以在提交到 Microsoft Store 的 MSIX 中使用与通过其他分发渠道提交的 .msi 或 .exe 完全相同的链式安装程序 .exe 文件。在传统的 Win32 应用中,共享中间件通常通过独立的可再发行文件来安装,这些文件一般是可自解压的 .exe 或可与游戏一并打包的 .msi。Microsoft Store 应用将依赖建模为框架包,这些包并不与游戏打包在一起,而是通过 Microsoft Store 单独部署。在此模型中,使用方应用的清单声明对一个或多个框架包的依赖。然后 Microsoft Store 会负责链式安装依赖项。虽然许多可再发行组件在 Microsoft Store 中都以框架包的形式提供,但不可避免地会有一些可再发行组件无法以框架包形式提供。对于这些包,解决方案是允许游戏将可再发行组件捆绑在游戏包内。要包含 .exe 或 .msi 可再发行组件,你需要更新 MicrosoftGame.config 文件。这些更改包括声明要使用的自定义操作的类型及其在安装包内的位置。任何可再发行组件都必须包含在包中,并在 MicrosoftGame.config 中声明。声明中包含可执行文件的路径(相对于声明的 Folder 路径,而该路径又相对于包本身的根路径)。声明还包括运行时要传递给可执行文件的命令行参数。这通过在 MicrosoftGame.config 文件中包含 CustomInstallActions 元素来完成。

CustomInstallActions

CustomInstallActions 元素包含所有关于要运行哪些自定义安装操作以及何时运行的定义。你在 MicrosoftGame.config 文件中只能声明一个此元素实例。它有一个必需的子元素 Folder,它是一个字符串,指定包含所有自定义操作所需文件的文件夹。此文件夹可以包含子文件夹。你需要负责确保包中包含任何自定义操作可执行文件所需的依赖项,并且这些依赖项位于每个可执行文件的适当加载路径中。

当你打包游戏时,makepkg 会将此 CustomInstallActions 元素转换为生成的 appxmanifest.xml 中的 MSIX windows.customInstall 扩展,其中对应的元素是 <CustomInstall>,并将 Folder 表达为 属性(attribute)。你自己不需要编写那种 <CustomInstall> 形式 —— 在 MicrosoftGame.config 中,Folder 是 CustomInstallActions 的一个子 元素(element),如本文后面的 游戏配置文件更改 示例所示。

你不得将任何主游戏可执行文件或其他文件放入指定的 Folder 中。它明确仅用于自定义安装文件。

在 CustomInstallActions 元素内,应用可以声明 InstallActionList、RepairActionList 和 UninstallActionList 子元素。这些均为可选:你可以声明其中任何一个或全都不声明。在每个列表中,你可以指定一个或多个 InstallAction、RepairAction 或 UninstallAction 子项。平台会按你指定的顺序、使用你指定的命令行参数运行你指定的操作。

操作类型

自定义安装扩展的三个子节点规定了某些自定义操作何时运行。共有三种类型的自定义安装操作。

Install action: 平台在应用首次启动之前运行的操作
Repair action: 当用户选择“修复(Repair)”或“重置(Reset)”时运行的操作
Uninstall action: 当用户卸载应用时运行的操作

尽管名称如此,install 操作并不在安装包时运行。每种操作类型都在应用生命周期的特定时刻运行,而 InstallAction 只运行一次,在游戏 首次启动之前 立即运行(这是平台可以出示所需 UAC 提示的最早时刻)。“Install”、“Repair”和“Uninstall”命名的是操作所属的生命周期类别,而不是它运行的时刻。如果你需要在真正的包安装/下载时刻执行工作,自定义安装操作并不是相应的机制。有关完整流程,请参见自定义操作的用法。

通常,你会将链式安装某个可再发行组件指定为 InstallAction,然后将其卸载指定为 UninstallAction。不过,在某些情况下,你可能选择只安装而不进行匹配的卸载。在这种情况下,你的应用安装了某个组件,并在其被卸载时将其保留下来 —— 这对于被其他应用共享的可再发行组件可能是合适的。类似地,你的 RepairAction 可能只是重新声明你为 InstallAction 指定的相同可执行文件,这也很常见。你希望在安装/修复/卸载中执行的每个操作也可能需要不同的可执行文件。这个架构非常灵活:平台不要求必须包含任何一种操作。你可以自由地根据每款游戏的需要配置行为。

只有在已运行过 Install 或 Repair 操作时,Uninstall 操作才会被执行。系统使用 Name 属性来跟踪此状态。因此,Install/Repair/Uninstall 操作使用相同的 Name 非常重要。

操作的组成

File

对于每个操作,你必须指定要运行的文件,并且该文件必须位于你的包内。如果你指定了路径,它将隐式地相对于 CustomInstallActions 的 Folder 路径。你不能指定绝对路径。你的路径不能以反斜杠(\)开头。

Name

你必须为操作指定一个 Name。此 Name 在父 Actions 节点内必须唯一,但可以在不同的 Actions 节点之间共享。例如,你可以同时将 File=“MySetup.exe” 和 Name=“abc123” 指定为 InstallAction 和 RepairAction。另一方面,如果你有两个 InstallAction 元素,它们必须使用不同的 Name。只要可执行文件本身没有变化,你就应在各版本包中为同一个可执行文件使用相同的 Name。Name 用作操作的身份标识,允许平台跟踪哪些操作已成功运行,以及在更新包中是否需要重新运行。如果更新包指定了一个自定义操作,而其 Name 已经成功运行过,则平台在更新时会跳过此操作。

参数列表的不同不构成身份的不同。如果你想在更新的包中使用不同参数运行同一个可执行文件,必须提供不同的 Name。你负责合理配置声明的 Names,并在版本之间进行跟踪。

Arguments

每个自定义安装操作还有第三个元素 argument,允许你包含运行可再发行命令所需的任何参数。

自定义操作的用法

安装反作弊软件通常要求用户具有管理员权限。总的来说 —— 因为自定义操作是一项非常强大的功能 —— 平台对任何包含自定义操作的包都要求管理员权限。对于以管理员权限运行的操作,Windows 要求在应用首次运行时显示用户账户控制(UAC)提示。用户工作流程如下。

游戏的 Microsoft Store 页面会包含关于要求的说明,包括安装是否需要提升权限、安装是否会运行自定义操作,以及这可能对用户意味着什么。提供这些信息是为了让用户可以就购买游戏做出知情决定。
假设用户接受这些限制和影响,他们选择“安装”。
平台会检测到该包包含自定义操作,并记录需要运行自定义操作这一事实。但它不会在初始安装阶段运行自定义操作,而是在用户首次启动游戏时运行任何自定义操作。
游戏首次启动时,当平台即将运行自定义操作时,它会显示 UAC 提示。用户随后需要提供管理员凭据并接受提升权限。即使一个包中包含多个自定义操作,用户也只会看到一个 UAC 提示。除非有一个或多个自定义操作已更改,否则更新时不会再有 UAC 提示。卸载游戏时会出现 UAC 提示。

所有自定义操作必须返回零表示成功。如果任何自定义操作失败,平台会继续运行其余的自定义操作,并继续尝试启动应用。在此后的每次应用启动时,平台会继续重试任何失败/未完成的安装自定义操作,直到该操作成功。如果应用在自定义操作失败的情况下无法正确运行,用户始终可以进入该应用的“设置”页面,选择“修复”或“重置”。修复/重置不会重新下载游戏文件 —— 它只是重新注册该包。任何失败或未执行的自定义操作会重新注册以供运行。如果你的自定义安装程序在成功时返回某个非零值,可以将该安装程序包装在你自己创建的另一个可执行文件中,让它在成功时返回零。 Microsoft Store 政策包含关于允许链式安装何种中间件/可再发行软件的准则。总的来说,链式安装的目的是安装运行游戏所必需的共享软件,而不是安装不相关的应用或其他软件。

自定义安装操作仅在主 MSIXVC 包内受支持。它们在框架包、可选包、修改包或任何其他类型的包中都不受支持。

自定义 install、repair 和 uninstall 操作由零售 Microsoft Store 部署管道执行。当你在本地安装该包用于开发时(例如,使用 wdApp install 安装一个松散的 .msixvc,或使用 Add-AppxPackage 注册包),它们不会运行。本地开发安装仍可让你验证包是否正确地声明了这些操作(它们会作为 windows.customInstall 扩展出现在生成的 appxmanifest.xml 中),但自定义操作的可执行文件本身不会在这条路径上被调用。要端到端地验证操作运行,请通过 Store 或沙箱流程安装游戏。

将 MSI 作为自定义安装操作运行

对于 MSI,你需要提供 MSI 的名称,然后平台会在该文件上运行 msiexec.exe。不要提供 /i、/f 或 /x 参数,因为它们会根据声明操作的类型(install、repair 或 uninstall)推断出来。你不能为 /f 开关提供任何选项。不过,你可以提供任何其他通常传递给 msiexec.exe 的可选参数。这是命令行参数受限的唯一情况:对于非 MSI 操作,你可以随意提供参数。对于非 MSI 操作,平台不会解析或验证参数,只会将它们原样传给可执行文件。你需要负责确保参数正确。对 MSTs(MSI 变换)没有直接支持。如果你有 MSI/MST 的需求,一种可行的变通方案是构建一个独立的 .exe,让它包装 msiexec 来运行你的 MSI 并应用你的 MST。

游戏配置文件更改

以下 XML 示例演示了向 MicrosoftGame.config 文件中添加的合适内容,以允许自定义安装操作。

  <!-- Include CustomInstallActions element. Declare InstallActions, 
  RepairActions and/or UninstallActions as appropriate for your app. --> 
  <DesktopRegistration>
    <!-- ... --> 
    <!-- Other entries omitted for brevity. --> 
    <!-- ... --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /example" />
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /remove" />
        </UninstallActionList>
    </CustomInstallActions>
  </DesktopRegistration>

在上例中,所有可执行文件及任何依赖项都必须放在你在包根目录下指定的 MyInstallers 文件夹中。在该文件夹内,你可以创建任何适合你应用的子文件夹结构。在此示例中,MySetup.exe 的路径将为 <package root>\MyInstallers\Banana\MySetup.exe。如果该可执行文件有任何依赖项,也必须放在合适的文件夹或子文件夹中。以下序列显示了如何跨多个版本编写清单。

<!-- v1 of the game. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
      <InstallActionList>
        <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform records the successful install of TaskName_1. --> 
      </InstallActionList>
      <RepairActionList>
        <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
      </RepairActionList>
      <UninstallActionList>
        <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        <!-- The platform records the successful uninstall of TaskName_1. --> 
      </UninstallActionList>
    </CustomInstallActions>
      
<!-- v2 of the game, where the redist is NOT updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform detects that we've already installed TaskName_1, so we don't  
          run it again. Therefore, there's no UAC prompt. --> 
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
 
<!-- v2 of the game, where a redist IS updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_2" Arguments="/silent /example" />
          <!-- The platform detects that we haven't previously run TaskName_2, so we need 
          to run it this time and show a UAC prompt. -->  
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

CustomInstallActions

操作类型

操作的组成

File

Name

Arguments

自定义操作的用法

将 MSI 作为自定义安装操作运行

游戏配置文件更改

​CustomInstallActions

​操作类型

​操作的组成

​File

​Name

​Arguments

​自定义操作的用法

​将 MSI 作为自定义安装操作运行

​游戏配置文件更改

CustomInstallActions

操作类型

操作的组成

File

Name

Arguments

自定义操作的用法

将 MSI 作为自定义安装操作运行

游戏配置文件更改