> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 排查 XStore 开发问题

> 在 XBOX 游戏开发和测试期间排查常见的 XStore API 问题，包括权益、沙盒和 PC 登录问题。

## 权益

当权益与玩家的购买活动不匹配时，请检查以下情况：

* 如果你在 PC 上的开发沙盒中测试，XBOX 测试账号必须先登录 XBOX 应用，然后再登录 Microsoft Store。如果测试账号先登录 Microsoft Store，Microsoft Store 默认使用 RETAIL 环境。
* 预购权益在其发布日期之前处于非活跃状态，且不会通过基于客户端的权益查询返回。
* 确保测试账号仅限于在单个沙盒中购买。如果账号在多个沙盒中拥有权益，collections 服务可能会返回无效结果。
* 如果你在主机上的开发沙盒中测试，当在 Microsoft Store 的产品详情页上选择 **Get** 按钮或当游戏调用 [XStoreShowPurchaseUIAsync](/reference/system/xstore/xstore_members) 时，会立即为免费产品授予权益。即使购买中止，也会授予权益。为避免这种自动权益授予的发生，请在沙盒中发布非零价格的附加内容。

有关权益的更多信息，请参阅[为玩家授予对附加内容的访问权限](/publishing/xstore-commerce/xstore-granting-access)。

## 授权

当为玩家不拥有的内容获取许可证时，请验证设备上是否未发生许可证共享或缓存。

* 许可证共享和缓存可能会使测试机器处于不干净的状态。
  * 从设备移除账号并不会移除它们的“offline”指定。具有离线能力的许可证会继续与其他账号共享，直到该指定被更改或许可证过期。
  * 当向 PC 添加新账号时，可能会自动为该账号启用 “Offline permissions” 设置，这可能导致意外的许可证共享。
* 若要确保 PC 环境干净，请始终在新的虚拟机中进行测试。
* 若要将主机恢复到干净状态，请尝试以下步骤：
  * 在从设备移除每个测试账号之前，为其禁用 “Home XBOX”（Settings > General > Personalization > My home XBOX）。
  * 多次运行（15 次以上）“Reset home XBOX”（Settings > Developer > Developer Settings）以移除旧账号的设备指定，然后重启主机。
  * 如果许可证仍然被共享，可能需要执行出厂重置。

有关授权的更多信息，请参阅[为玩家授予对附加内容的访问权限](/publishing/xstore-commerce/xstore-granting-access)。

## 安装 DLC（带包耐用品）时 `XPackageRegisterPackageInstalled` 分配的回调未被触发

如果 DLC 的安装状态不明显，请先检查 `xbapp listdlc` 或 `wdapp listdlc` 以验证预期的 DLC 是否已列出。

然后检查 DLC 的 microsoftgame.config 中的 `AllowedProduct` 是否与基础游戏 microsoftgame.config 中 `StoreId` 节点的值匹配。

如果此 DLC 是 Smart Delivery 产品，且 XBOX Series X/S 基础游戏使用的是 ERA DLC 包，并且 ERA DLC 的 appxmanifest 中的 `AllowedProduct` 与分配给 XBOX Series X/S 基础游戏（`xbapp list /d`）的 product ID 不同，则可能需要覆盖 product ID。仅打包构建支持此覆盖：

```cmd theme={null}
makepkg pack /d <dir> /pd <dir> /contentid <contentid> /productid <product ID of ERA product> /productidoverride
```

这种情况可能出现在从已停用的 XBOX Developer Portal 站点迁移的 XBOX One 基础游戏上。

## PC 上的 `XStoreShowPurchaseUIAsync` 短暂显示购买对话框然后返回 `E_ABORT`

以下情况可能会发生此问题：

* 从提升权限（Administrator）的进程调用 XStoreShowPurchaseUIAsync。
* 你在 Visual Studio 中以管理员权限进行调试，或从设置为“以管理员身份运行”的任何进程中调试。解决方案是避免以管理员身份运行时调用此 API。
* UAC（用户账户控制）被设置为不向交互用户桌面显示确认提示。

UAC 由以下注册表值控制：

`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA` `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\PromptOnSecureDesktop`

`EnableLUA` 应为 `1`。在某些情况下，将 `PromptOnSecureDesktop` 切换为 `0` 也可能有效。

有关此项和其他相关控制项的更多信息，请参阅此[页面](https://learn.microsoft.com/windows/security/identity-protection/user-account-control/user-account-control-group-policy-and-registry-key-settings)。

## XStore 相关错误代码

| 十六进制值      | 错误                                      | 说明                   |
| ---------- | --------------------------------------- | -------------------- |
| 0x803F6300 | `XSTORE_E_NULL_LICENSE_SERVICE_CONTEXT` | 授权服务上下文不可用。          |
| 0x803F6301 | `XSTORE_E_NULL_STORE_CONTEXT`           | 商店上下文对象为 null 或未初始化。 |
| 0x803F6302 | `XSTORE_E_INVALID_ID`                   | 传入的 ID 无效或未知。        |
| 0x803F6303 | `XSTORE_E_INVALID_REQUEST`              | 请求具有无效的参数或格式。        |
| 0x803F6304 | `XSTORE_E_INVALID_RESPONSE`             | 商店服务的响应意外或无效。        |
| 0x803F6305 | `XSTORE_E_ZERO_RESULTS`                 | 在期望非零结果时返回了零结果。      |
| 0x803F6306 | `XSTORE_E_NULL_INPUT_PARAMETER`         | 提供的必需参数为 null。       |
| 0x803F6307 | `XSTORE_E_INVALID_INPUT_PARAMETER`      | 提供的输入参数无效。           |
| 0x803F6308 | `XSTORE_E_INVALID_VERSION`              | 发起请求的客户端不满足所需的最低版本。  |
| 0x803F6309 | `XSTORE_E_BAD_CONVERSION`               | 无法正确转换必需参数或响应。       |

## 参考 API 文档

* [XStore（API 内容）](/reference/system/xstore/xstore_members)
  * 函数
    * [XStoreShowPurchaseUIAsync](/reference/system/xstore/xstore_members)

## 另请参阅

[商务概述](/publishing/xstore-commerce/xstore-commerce-overview)

[启用 XStore 开发与测试](/publishing/xstore-commerce/xstore-product-testing-setup)

[XStore API 参考](/reference/system/xstore/xstore_members)


## Related topics

- [为玩家授予对附加内容的访问权限](/zh-CN/publishing/xstore-commerce/xstore-granting-access.md)
- [开发](/zh-CN/services/xbox-services/develop/index.md)
- [正确切换沙盒以进行 Store 操作](/zh-CN/publishing/xstore-commerce/xstore-switching-sandbox.md)
- [在开发 PC 上测试包](/zh-CN/build/core-features/common/packaging/packaging-testing-PC-install.md)
- [在 PC 上排查 XBOX 服务流量问题](/zh-CN/build/gdk-and-engines/guides/troubleshoot-xbox-services-traffic.md)