> ## 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.

# XGameSaveFiles API 概述

> 涵盖 XGameSaveFilesGetFolderWithUIAsync、Win32 云同步行为、配额、调试和性能最佳实践的 XBOX XGameSaveFiles 参考。

本文介绍如何初始化 `XGameSaveFilesGetFolderWithUIAsync`。它还介绍了推荐的 Win32 自动云同步行为、调试步骤、配额和诊断指南、性能最佳实践以及常见问题的解答。

`XGameSaveFiles` 提供了使你的标题能够读取和写入用户数据、跨会话持久保存数据并将其无缝同步到云端的 API，使玩家可以在任何设备上使用其数据。在 Microsoft Game Development Kit (GDK) 标题中使用 `XGameSaveFiles` 进行游戏存档。仅当 `XGameSaveFiles` 不适用于你的场景时才使用 `XGameSave`。

有关 `XGameSaveFiles` 的系统 API 参考，请参阅 [XGameSaveFiles (API 内容)](/reference/system/xgamesavefiles/xgamesavefiles_members)。

以下术语在 `XGameSaveFiles` 中经常出现。

* **锁：** 一种在用户当前使用的设备上，为特定用户授予对标题游戏存档独占访问权的机制。它确保在锁被持有时，没有其他设备可以修改该用户的游戏存档。
  * 例如，如果用户在设备 A 上玩标题 T，则 A 上具有该用户的标题 T 的锁。
* **提供程序：** 与游戏存档系统通信并负责管理标题数据的中介进程。该提供程序还管理设备上用户的锁。
* **容器**：类似于文件夹。
* **Blob**：类似于单个文件。

## XGameSaveFiles 路径逻辑

`XGameSaveFiles` 提供了一个文件路径，你可以用它与游戏存档系统交互。该文件路径与云同步集成，因此保存到该路径的数据会自动同步到云端。在提供的路径上使用 Win32 `FileIO` API。对于 GDK 标题，使用 `XGameSaveFiles` 作为游戏存档的方法。`XGameSaveFiles` 将容器的概念映射到文件夹，将 blob 映射到文件。

虽然 `XGameSaveFiles` 隐藏了云存档系统的大部分复杂性，但由于该功能依赖于 Microsoft Azure Blob Storage，它仍然强制执行目录和文件名限制。请考虑以下标题可能用于其存档的示例代码。

```
[ROOT]/Save1/WingtipToys/state001.dat
```

* `XGameSaveFilesGetFolderWithUiAsync` 返回 \[ROOT]。
* \[ROOT] 之后到最后一个斜杠（包括）的所有内容都映射到容器。
  * 容器名称限于大写字母 (A-Z)、小写字母 (a-z)、数字 (0-9)、下划线 (\_)、句点 (.)、连字符 (-) 和斜杠 (/)。
  * 容器名称限于 256 个字符。
  * 容器名称不能以句点结尾、包含两个连续的句点或以句点或连字符开头。
* 文件名中最后一个斜杠之后的所有内容都映射到 blob。
* 文件名限于 65 个字符，但可以是 New Technology File System (NTFS) 支持的其他 Unicode 字符。
* 最终生成的完整路径（包括文件名，但不包括 \[ROOT]）必须小于 `MAX_PATH`（260 个字符）。

有关 Win32 和文件管理的更多信息，请参阅[文件管理（本地文件系统）](https://learn.microsoft.com/windows/win32/fileio/file-management)。

## XGameSaveFiles 的实现

以下步骤显示了 `XGameSaveFiles` 的一般实现。

1. 在标题启动或恢复时，调用 `XGameSaveFilesGetFolderWithUIAsync` 初始化提供程序并获取文件路径。
2. 在游戏过程中自由地读写文件路径。

`XGameSaveFilesGetFolderWithUIAsync` 自动管理游戏存档提供程序的生命周期并设置游戏存档本地存储空间。

<Info>在标题启动和恢复时调用 `XGameSaveFilesGetFolderWithUIAsync`。此调用初始化游戏存档提供程序，并使其在游戏会话运行期间保持活动状态。如果跳过此步骤，系统的行为可能不可预测。</Info>

### 代码示例

有关演示如何使用 `XGameSaveFiles` API 访问 XBOX 上文件夹的代码示例，请参阅 [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/)。

## 游戏存档流程

以下是简化游戏存档流程的流程图。

<img src="https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/simple-sync-overview.png?fit=max&auto=format&n=UZTRJSf0emX1fheE&q=85&s=98c2d4bdfc034fdd8340c67e10c4d5e7" alt="简化游戏存档同步过程的流程图。" width="530" height="572" data-path="images/gdk/features/common/simple-sync-overview.png" />

### 标题启动

当用户启动或恢复标题时发生标题启动。

### 用户登录

标题开始用户登录过程。此操作也是你调用 `XGameSaveFilesGetFolderWithUIAsync` 的地方。有关用户设置的更多信息，请参阅[用户模型](/build/core-features/common/game-save/game-saves-developer-guide#user-models)。

### 连接检查

标题确定它是否可以连接到 XBOX 网络。如果不能，你需要为该标题启用[离线模式](/build/core-features/common/game-save/game-saves-syncing#connection-check)。

### 数据所有权检查

设备检查用户当前是否正在其他设备上游玩。对于特定标题，一次只能有一台设备访问该用户的数据。

### 与云同步数据

设备将游戏存档本地存储数据与云端同步。如果存在冲突，系统会通过冲突解决对话框提示用户。

对话框：[你想使用哪一个？](/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use)

如果设备上的数据比云端数据更新，标题会提示用户在使用本地数据或云端数据之间进行选择。

### 游戏循环

标题可以自由读写由 `XGameSaveFilesGetFolderWithUIAsync` 提供的文件夹路径。

### 游戏会话结束

游戏会话结束时，系统会自动尝试将数据上传到云端。此过程大约在标题结束后 10 到 30 秒发生。

有关详细的同步信息，请参阅[理解游戏存档同步流程](/build/core-features/common/game-save/game-saves-syncing)。

## 限制和配额

### 限制

使用 `XGameSaveFiles` 可以保存的最大文件大小为 64 MB。这与 `XGameSave` 不同，`XGameSave` 将每个文件限制为 16 MB。

### 配额

每个标题的用户最多可以保存 256 MB 的数据。使用 [XGameSaveFilesGetRemainingQuota](/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) 获取剩余配额。要获取存储扩展以便你的标题拥有更大的每用户存储限制，请联系你的开发者项目经理 (DPM)。

## 常见问题解答

### 我可以将 XGameSaveFiles 与 XGameSave 一起使用吗？

可以。但是，仅在迁移时使用此方法。有关详细信息，请参阅 [XGameSave 与 XGameSaveFiles 之间的互操作性](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles)。

### XGameSaveFiles 保存到什么文件路径？

**主机**：标题在活动时提供临时路径。你无法使用文件资源管理器访问主机文件。

**PC**：`%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\`

`XGameSaveFiles` 的 PC 路径与 `XGameSave` 不同。它使用 `wgs`。

### 我可以指定保存数据的路径吗？

可以，但仅限 PC。仅当你从另一个标题移植解决方案时才建议这种方法。此解决方案使用[无代码云存档](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。

## 参考 API 文档

* [XGameSaveFiles (API 内容)](/reference/system/xgamesavefiles/xgamesavefiles_members)
  * 函数
    * [XGameSaveFilesGetRemainingQuota](/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota)

## 另请参阅

[游戏存档目录](/build/core-features/common/game-save/game-saves-toc)
可以，但仅限 PC。从另一个标题移植你的解决方案可能需要这种方法。此解决方案使用[无代码云存档](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。

<Note>无代码云存档要求使用 `wdapp install` 将标题作为打包构建启动。直接启动 .exe 不会激活云存档重定向。在打包启动和直接 .exe 启动之间切换可能会导致存档数据看起来丢失。有关更多信息，请参阅[使用无代码云存档将以前的标题移植到 PC 游戏存档](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。</Note>


## Related topics

- [游戏存档概述](/zh-CN/build/core-features/common/game-save/game-saves-overview.md)
- [XGameSaveFilesGetRemainingQuota](/zh-CN/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota.md)
- [XGameSaveFiles](/zh-CN/reference/system/xgamesavefiles/xgamesavefiles_members.md)
- [XGameSave API 概述](/zh-CN/build/core-features/common/game-save/xgamesave.md)
- [游戏存档演练与示例](/zh-CN/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md)