XGameSave API 使你能够管理 blob 和容器以管理游戏存档数据。我们推荐 Microsoft Game Development Kit (GDK) 标题的游戏存档使用 XGameSaveFiles。如果 XGameSaveFiles 不是一个选项，则使用 XGameSave。
有关 XGameSave 的系统 API 参考，请参阅 XGameSave (API 内容)。
以下术语在 XGameSave 中经常出现。
- 锁：一种在用户当前使用的设备上，为特定用户授予对标题游戏存档独占访问权的机制。它确保在锁被持有时，没有其他设备可以修改该用户的游戏存档。
- 例如，如果用户在设备 A 上玩标题 T，则 A 上具有该用户的标题 T 的锁。
- 提供程序：与游戏存档系统通信并负责管理标题数据的中介进程。该提供程序还管理设备上用户的锁。
- 容器：类似于文件夹。
- Blob：类似于单个文件。
提供程序管理
要获取存储空间，游戏必须初始化提供程序。连接后，标题通过调用XGameSaveInitializeProvider 或 XGameSaveInitializeProviderAsync 尝试获取标题云存储的锁。
如果标题因连接丢失而未能从云端同步，请确定用户是否可以在离线模式下继续游玩。
当标题挂起或终止时，标题必须使用 XGameSaveCloseProvider 关闭提供程序。该提供程序无法跨挂起-恢复边界重复使用。
此问题仅适用于
XGameSave。XGameSaveFiles 会自动关闭提供程序。容器管理
为避免访问容器时的数据丢失（例如在同步完成前创建容器），请调用XGameSaveEnumerateContainerInfo 或 XGameSaveEnumerateContainerInfoByName 以查看用户拥有的容器。
使用 XGameSaveCreateContainer 获取新的或现有容器的容器句柄。如果容器已存在，则提供其句柄。如果容器不存在，则创建新容器并提供其句柄。
使用 XGameSaveDeleteContainer 删除容器。该容器中的所有 blob 也会被删除。
为防止句柄泄漏，当容器不再使用时或标题挂起或终止时，使用 XGameSaveCloseContainer 关闭所有容器句柄。
Blob 管理
通过调用XGameSaveCreateUpdate 来操作容器内的数据。
以下详细信息概述了 XGameSaveUpdate 如何管理容器内的 blob 更改，以及每个更新如何被创建、修改和提交。
- 一个更新适用于一个容器。
- 一个更新最多可以写入 GS_MAX_BLOB_SIZE (16 MB)。
- 单个更新中可以修改多个 blob。
- 每个更新只能对单个 blob 进行一次修改。
-
提交更新会消耗
XGameSaveUpdate句柄。无论提交成功还是失败，都要关闭该句柄。 - 更新是原子的。如果其中任何部分失败，整个更新都会失败。
-
XGameSaveCreateUpdate创建一个更新上下文以存储所有的 blob 修改。 -
XGameSaveSubmitBlobWrite向新的或现有的 blob 写入数据，并且需要一个更新的上下文。 -
XGameSaveSubmitBlobDelete删除 blob。 -
XGameSaveSubmitUpdate提交更新上下文。 -
XGameSaveCloseUpdate关闭更新句柄。标题在每次提交后调用它以防止泄漏。 -
使用
XGameSaveEnumerateBlobInfo或XGameSaveEnumerateBlobInfoByName访问容器中的所有 blob。
当数据以 XML 导出时，写入 blob 的数据以
Base64 表示。实现
以下步骤显示了XGameSave 实现的一般流程。
- 在标题启动或恢复时，初始化提供程序。
- 枚举和创建容器句柄。
- 定期提交带有 blob 修改的
XGameSaveUpdates，并在提交时清理更新句柄。 - 在标题挂起或终止时关闭容器和提供程序句柄。
在标题启动和恢复时调用
XGameSaveInitializeProvider。此调用可确保提供程序正确初始化并在标题运行时保持活动状态。如果不调用它，标题的行为可能不可预测。代码示例
有关演示如何使用XGameSave API 的代码示例，请参阅 GameSaveCombo。
游戏存档流程
以下是简化游戏存档流程的流程图。其说明如下。标题启动
当用户启动或恢复标题时发生标题启动。用户登录
标题启动用户登录。此调用也是你调用XGameSaveInitializeProvider 的地方。
有关用户设置的更多信息，请参阅用户模型。
连接检查
标题确定它是否可以连接到 XBOX 网络。如果不能，则由你决定是否为标题启用离线模式。数据所有权检查
设备检查用户当前是否正在其他设备上游玩。对于特定标题，一次只能有一台设备访问该用户的数据。与云同步数据
设备将游戏存档本地存储数据与云端同步。如果存在冲突，系统会通过冲突解决对话框提示用户。 对话框：你想使用哪一个？ 当设备上的数据比云端数据更新时，标题会提示用户在使用本地数据或云端数据之间进行选择。游戏循环
标题可以自由地读写游戏存档本地存储。游戏会话结束
游戏会话结束时，系统会自动尝试将数据上传到云端。请确保标题在其退出流程中调用XGameSaveUninitializeProvider，以免留下已初始化的提供程序。有条不紊的关闭确保在退出之前干净地保存数据。
有关详细的同步信息，请参阅理解游戏存档同步流程。
限制和配额
限制
XGameSaveUpdate 将每个更新限制为 16 MB。因此，XGameSave 只能管理最大 16 MB 的单个文件更新。此限制与 XGameSaveFiles 不同，后者支持最大 64 MB 的文件。
配额
每个标题的用户最多可以保存 256 MB 的数据。使用 XGameSaveGetRemainingQuota 获取剩余配额。要为你的标题获取存储扩展，请联系你的开发者合作伙伴经理 (DPM)。最佳实践
- 不要保存数据后立即查询并请求相同的数据。
- 跨容器的数据依赖不可靠。每个
XGameSaveSubmitUpdate调用要么原子地应用所有更改，要么全部不应用。 - 每次更新调用中使用的 blob 越多，完成文件系统操作以存储数据所需的原子操作时间就越多。
常见问题解答
我正在升级我的游戏存档实现。正确的方法是什么？
使用 XGameSaveFiles。我可以将 XGameSave 与 XGameSaveFiles 一起使用吗？
可以。但是，仅用于迁移。有关详细信息，请参阅 XGameSave 与 XGameSaveFiles 之间的互操作性。XGameSave 保存到什么文件路径？
主机：标题活动时提供临时路径。主机文件无法通过文件资源管理器访问。 PC：%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
请注意，XGameSave 的 PC 路径与 XGameSaveFiles 不同。它使用 xgs。