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

# XR-074 与 XBOX 和合作伙伴服务的连接断开

> 游戏如何处理与 XBOX 和合作伙伴服务的连接中断，包括重试策略、用户友好的错误消息以及 RequireXboxLive 标志。

版本 2.0，2025/11/1

游戏必须妥善处理与 XBOX 和合作伙伴服务连接相关的错误。在发生故障后尝试重试对 XBOX 服务的请求时，游戏必须遵守 XBOX 设置的重试策略。当服务不可用时，游戏必须适当地向用户显示消息。如果合作伙伴服务不可用，游戏不得指示 XBOX 网络存在问题。如果网络服务速度变慢或间歇性可用，游戏不得崩溃或停止响应。

## 更多信息

游戏应根据自身网络操作的性能做出反应，和/或使用 **Windows.XBOX.Networking** 网络质量 API 来确定当前的网络状况。游戏还应通过减少传输的数据、选择适当的用户角色或使用云服务来实现平稳降级。

### 处理非 XBOX 服务的问题

如果游戏在使用合作伙伴服务时遇到影响用户体验的问题（例如非暂时性超时、网络 API 错误或缺少服务配置），应提醒用户具体哪项功能或服务不可用。在用户排查问题期间，游戏应妥善地回退到安全状态，或回退到用户可以手动重试的状态。

用户友好消息的示例如下：

> “抱歉，*非 Microsoft 服务* 当前不可用。请稍后重试。有关详细信息，请联系 *非 Microsoft 支持联系信息*。”

### 处理 XBOX 服务的问题

如果与 XBOX 服务的连接断开，某些功能可能会变得不可用。在这种情况下，游戏应使用清晰、用户友好的消息将此情况告知用户。

如果服务不可用，游戏可以重试其请求，但只能在 XBOX 允许的参数范围内重试。有关 XBOX 主机游戏的服务复原能力的详细信息（包括所需的 HTTP 重试和退避逻辑，以及各项服务的用户交互指南），请参阅[游戏的服务中断复原能力](https://docs.xbox.com/zh-CN/services/xbox-services/develop/best-practices/live-best-practices-calling-xbl.md)

### 要求 XBOX 连接

在为 XBOX 主机进行开发时，如果游戏的大部分功能需要连接到 Internet（尤其是 XBOX），可能需要在其 AppX 清单中包含布尔标志 `RequireXboxLive`。这样，当 XBOX 不可用时，将阻止游戏在 XBOX 主机上启动；如果连接断开，则会挂起游戏，随后终止游戏。

有关使用 GDK 进行联网的信息，请阅读[网络部分](https://docs.xbox.com/zh-CN/build/console-features/networking/gc-networking-toc.md)。

## 认证测试用例

### 074-01 与 XBOX 服务的 WAN 连接断开

**测试步骤**

1. 登录 XBOX 个人资料。
2. 在执行以下操作时，断开 WAN 网络。如果使用以太网交换机/集线器，请从网络设备上拔下上行链路电缆。如果设备通过 Wifi 连接，请从无线接入点连接上拔下上行链路电缆：
   * 创建新的保存点
   * 加载保存点
   * 到达自动保存点
   * 枚举已保存游戏的列表
   * 搜索并加入在线会话
   * 尝试创建在线会话
   * 查看排行榜（如果适用）
   * 离线玩游戏

**预期结果**\
如果主机无法访问 XBOX 服务，游戏应以用户友好的错误消息做出响应。

**通过示例**

1. 游戏显示错误消息，指示与 XBOX 服务的网络连接已断开。
2. 在玩不需要 XBOX 服务的本地游戏模式时，游戏不显示错误消息。
3. 在 AppX 清单中包含 `RequireXboxLive` 的游戏在连接断开时挂起，然后终止。

**失败示例**

1. 用户无法完成非在线 XBOX 游戏会话。
2. 游戏进入无响应或不稳定状态。

### 074-02 直接断开连接

**测试步骤**

1. 启动游戏并登录 XBOX 个人资料。
2. 在游戏中执行以下操作时，从设备上拔下网络电缆，或关闭 WAP 或无线路由器的电源：
   * 创建新的保存点。
   * 加载保存点。
   * 到达自动保存点。
   * 枚举已保存游戏的列表。
   * 搜索并加入在线会话。
   * 尝试创建在线会话。
   * 查看排行榜（如果适用）。
   * 离线玩游戏。

**预期结果**\
如果设备与 XBOX 服务的连接断开，游戏应以用户友好的错误消息做出响应。

**通过示例**

1. 在在线游戏模式下，游戏显示用户友好的消息。
2. 在离线游戏模式下，游戏不会中断游戏过程。
3. 在 AppX 清单中包含 `RequireXboxLive` 的游戏在连接断开时挂起，然后终止。

**失败示例**

1. 在离线游戏模式下显示错误消息。
2. 游戏进入无响应或不稳定状态。
3. 网络离线后，用户仍能查看在线菜单或查看已缓冲的媒体。

### 074-03 挂起期间与 XBOX 服务断开连接

在零售版主机上，游戏会在以下情况下被挂起：

* 在电源模式设置为“即时启动”时关闭主机，使主机进入联网待机状态。
* 游戏保持非焦点状态十分钟。例如，启动“设置”等应用程序并使其保持焦点状态十分钟。

在本测试用例中，应在步骤 3 中验证这两种方法。

**测试步骤**

1. 在主机电源模式设置为“即时启动”的情况下，登录 XBOX 个人资料。
2. 启动游戏并进入游戏过程。
3. 在游戏中的各个时间点挂起游戏。
4. 恢复游戏，并验证游戏能够妥善处理连接断开。
5. 在整个游戏过程中重复步骤 3-4。

**预期结果**\
如果主机在挂起后无法访问 XBOX 服务，游戏必须成功恢复，妥善处理这种情况，并在适当时以用户友好的错误消息做出响应。

**通过示例**

1. 在在线 XBOX 多人游戏会话期间，游戏显示错误消息，指示与 XBOX 服务的网络连接已断开。
2. 在玩不需要 XBOX 服务的本地游戏模式时，游戏不显示错误消息。

**失败示例**

1. 用户无法完成非在线 XBOX 游戏会话。
2. 游戏进入无响应或不稳定状态。
3. 恢复后，游戏显示误导性或不正确的错误消息。

### 074-04 挂起期间重新连接到 XBOX 服务

在零售版主机上，游戏会在以下情况下被挂起：

* 在电源模式设置为“即时启动”时关闭主机，使主机进入联网待机状态。
* 游戏保持非焦点状态十分钟。例如，启动“设置”等应用程序并使其保持焦点状态十分钟。

在本测试用例中，应在步骤 3 中验证这两种方法。

**测试步骤**

1. 在主机电源模式设置为“即时启动”的情况下登录 XBOX 个人资料，并确保主机处于主页。
2. 在未连接到 XBOX 但保留本地网络连接的情况下，启动游戏。
   * 如果使用以太网交换机或集线器，请从网络设备上拔下上行链路电缆。
   * 如果设备通过 Wifi 连接，请从无线接入点上拔下上行链路电缆。
3. 在游戏中的各个时间点挂起游戏。
4. 重新连接上行链路电缆，并等待主机重新连接到 XBOX 服务。
5. 恢复游戏，并验证游戏能够妥善处理重新连接。
6. 在整个游戏过程中重复步骤 2-5。

**预期结果**\
如果主机在挂起后无法访问 XBOX 服务，游戏必须成功恢复，妥善处理这种情况，并在适当时以用户友好的错误消息做出响应。

**通过示例**

1. 用户能够恢复游戏，并在不中断的情况下完成离线 XBOX 游戏会话。
2. 游戏保持稳定，不会崩溃。

**失败示例**

1. 用户无法完成非在线 XBOX 游戏会话。
2. 游戏进入无响应或不稳定状态。
3. 恢复后，游戏显示误导性或不正确的错误消息。

### 074-07 动态连接断开

**所需工具：**

* [XBOX Multiplayer Analysis Tool (XMAT) 文档](https://github.com/microsoft/xbox-multiplayer-analysis-tool/blob/main/README.md)和[最新的 XMAT 版本](https://github.com/microsoft/xbox-multiplayer-analysis-tool/releases)。

**配置 XMAT 以阻止合作伙伴服务**

有关安装、捕获设置和脚本编写说明，请参阅[使用 XBOX Multiplayer Analysis Tool 检查和修改网络流量](https://docs.xbox.com/zh-CN/tools/tools-services/live-xbox-multiplayer-analysis-tool.md)。

1. 以管理员身份启动 XMAT，并为受测设备添加 **Web Proxy** 捕获。
   * 在 XBOX 开发主机上，选择 **Enable XBOX Proxy**，然后等待主机重启。
   * 在 Windows 上，选择 **Start Capture**。
2. 在 XMAT 捕获期间，启动游戏并浏览所有菜单，完成一个多人游戏会话，加载每种游戏模式，并浏览游戏的所有区域，包括：
   * 菜单。
   * 排行榜。
   * 服务器（创建一个服务器并加入其他人的服务器）。
   * 好友列表。
   * 游戏内商店。
   * 限时活动。
3. 使用 **Host** 筛选器识别正常游戏过程中联系的合作伙伴服务主机。在阻止所选主机之前，请确认它们不属于 Microsoft、XBOX 或 PlayFab。
4. 打开 **Script Editor**，选择 **SSL Connection Request** 事件，并创建一个脚本，为每个合作伙伴服务主机将 `Params.Continue` 设置为 `false`。
5. 启用该脚本并验证其编译成功。然后禁用该脚本，以便在测试开始时合作伙伴服务仍然可用。保持 XMAT 捕获处于运行状态。

**测试步骤**

1. 在禁用 XMAT 阻止脚本的情况下，登录 XBOX 个人资料并启动游戏。
2. 导航到使用合作伙伴托管服务的游戏功能，并确认该功能可用。
3. 在不关闭游戏的情况下，启用 XMAT 阻止脚本。
4. 继续游戏并试用所有适用的区域，包括：
   * 菜单
   * 排行榜
   * 服务器（创建一个服务器并加入其他人的服务器）
   * 好友列表
   * 游戏内商店
   * 限时活动
5. 验证游戏未显示指示 XBOX 网络存在问题的错误消息。

**预期结果**\
游戏能够妥善处理与非 Microsoft 服务的连接断开。

**通过示例**

1. 与合作伙伴托管服务的连接断开时，游戏不会停止响应或崩溃。

**失败示例**

1. 显示的消息暗示 Microsoft 服务存在问题。
2. 显示描述不明确的错误消息。
3. 游戏崩溃、变得不稳定或导致主机重新启动。

### 074-08 发布前停机

**所需工具：**

* GDK/XDK 中的 *xbstress.exe*
* 适用于 Windows 的 [XBOX Multiplayer Analysis Tool (XMAT)](https://docs.xbox.com/zh-CN/tools/tools-services/live-xbox-multiplayer-analysis-tool.md)。

**测试步骤**

1. 在主机上，使用以下命令通过 *xbstress.exe* 为非 Microsoft 流量创建中断的网络通道：

`xbstress set channel=0 network=broken addresses=[semicolon delimited list of addresses]`

2. 使用以下命令启动网络模拟：`xbstress simulate network=channels`。
3. 如果在 Windows 上进行测试，请在启动游戏之前配置 XMAT Web 代理捕获，并启用用于阻止适用合作伙伴服务主机的脚本。
4. 登录 XBOX 个人资料。
5. 启动游戏。
6. 访问非 Microsoft 在线功能。

**预期结果**\
游戏应提供用户友好的错误消息，指示访问非 Microsoft 服务时出现问题，并应提供重试连接的机会。

**通过示例**

1. 与合作伙伴托管服务的连接断开时，游戏不会停止响应或崩溃。

**失败示例**

1. 显示的错误暗示 Microsoft 服务存在问题。
2. 显示描述不明确的错误消息。
3. 游戏崩溃、变得不稳定或导致主机重新启动。


## Related topics

- [XR074 与 XBOX 和合作伙伴服务的连接中断](https://docs.xbox.com/zh-CN/publishing/certification/fma/xr-074.md)
- [XBOX 游戏的 XBOX 要求](https://docs.xbox.com/zh-CN/publishing/certification/xbox-requirements.md)
- [经测试的 XBOX 要求](https://docs.xbox.com/zh-CN/publishing/certification/console-cert-tested-requirements.md)
- [XBOX 要求和政策支持内容](https://docs.xbox.com/zh-CN/publishing/certification/xr/overview.md)
- [Xbox 服务用户权限的服务器端处理](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-server.md)