> ## 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 概觀 > XBOX XGameSaveFiles 參考，涵蓋 XGameSaveFilesGetFolderWithUIAsync、Win32 雲端同步行為、配額、偵錯與效能最佳做法。 本文說明如何初始化 `XGameSaveFilesGetFolderWithUIAsync`。也會說明建議的 Win32 自動雲端同步行為、偵錯步驟、配額與診斷指引、效能最佳做法，以及常見問題的解答。 `XGameSaveFiles` 提供的 API 可讓您的遊戲讀取與寫入使用者資料、跨工作階段保存資料，並順暢地與雲端同步，讓玩家可以在任何裝置上使用其資料。請在 Microsoft Game Development Kit (GDK) 遊戲中使用 `XGameSaveFiles` 處理遊戲存檔。只有在 `XGameSaveFiles` 不適用於您的案例時，才使用 `XGameSave`。 如需 `XGameSaveFiles` 的系統 API 參考，請參閱 [XGameSaveFiles (API 內容)](/zh-TW/reference/system/xgamesavefiles/xgamesavefiles_members)。 下列詞彙經常出現在 `XGameSaveFiles` 中。 * **鎖定**：一種機制，可針對特定使用者在其目前使用的裝置上，授與對遊戲 Game Saves 的獨佔存取權。它可確保在持有鎖定期間，沒有其他裝置可以修改該使用者的遊戲存檔。 * 例如，如果使用者在裝置 A 上玩遊戲 T，裝置 A 就會為該使用者持有遊戲 T 的鎖定。 * **提供者**：與 Game Save 系統通訊並負責管理遊戲資料的中介處理程序。提供者也會管理使用者在裝置上的鎖定。 * **容器**：類似於資料夾。 * **Blob**：類似於個別檔案。 ## XGameSaveFiles 路徑邏輯 `XGameSaveFiles` 提供一個檔案路徑，您可以用來與 Game Saves 系統互動。此檔案路徑與雲端同步整合，因此儲存到該路徑的資料會自動同步到雲端。請在提供的路徑上使用 Win32 `FileIO` API。對於 GDK 遊戲，請使用 `XGameSaveFiles` 作為 Game Saves 方法。`XGameSaveFiles` 會將容器的概念對應到資料夾，並將 Blob 對應到檔案。 雖然 `XGameSaveFiles` 隱藏了雲端存檔系統大部分的複雜性，但由於此功能依賴 Microsoft Azure Blob 儲存體，因此仍會強制執行目錄與檔案名稱限制。請參考下列範例程式碼，了解遊戲可能用於其存檔的路徑。 ``` [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` 會自動管理 Game Saves 提供者的存留期，並設定 Game Saves 本機儲存空間。 請在遊戲啟動及繼續時呼叫 `XGameSaveFilesGetFolderWithUIAsync`。此呼叫會初始化 Game Saves 提供者，並在遊戲工作階段執行期間保持其作用中。如果您略過此步驟，系統的行為可能無法預測。 ### 程式碼範例 如需示範如何使用 `XGameSaveFiles` API 存取 XBOX 上資料夾的程式碼範例，請參閱 [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/)。 ## Game Saves 流程 以下是簡化 Game Saves 流程的流程圖。 簡化 Game Saves 同步程序的流程圖。 ### 遊戲啟動 使用者啟動或繼續遊戲時，即為遊戲啟動。 ### 使用者登入 遊戲會開始使用者登入程序。您也會在此作業中呼叫 `XGameSaveFilesGetFolderWithUIAsync`。如需使用者設定的詳細資訊，請參閱[使用者模型](/zh-TW/build/core-features/common/game-save/game-saves-developer-guide#user-models)。 ### 連線檢查 遊戲會判斷是否能連線到 XBOX 網路。如果無法連線，您需要為遊戲啟用[離線模式](/zh-TW/build/core-features/common/game-save/game-saves-syncing#connection-check)。 ### 資料擁有權檢查 裝置會檢查使用者目前是否正在其他裝置上遊玩。對於特定遊戲，一次只能有一部裝置存取使用者的資料。 ### 與雲端同步資料 裝置會將 Game Saves 本機儲存空間資料與雲端同步。如果發生衝突，系統會以衝突解決對話方塊提示使用者。 對話方塊：[您要使用哪一個？](/zh-TW/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) 如果裝置上的資料比雲端資料新，遊戲會提示使用者選擇使用本機資料或雲端資料。 ### 遊戲迴圈 遊戲可以自由讀取與寫入 `XGameSaveFilesGetFolderWithUIAsync` 提供的資料夾路徑。 ### 遊戲工作階段結束 遊戲工作階段結束時，系統會自動嘗試將資料上傳到雲端。此程序會在遊戲結束後約 10 到 30 秒進行。 如需詳細的同步資訊，請參閱[了解 Game Saves 同步流程](/zh-TW/build/core-features/common/game-save/game-saves-syncing)。 ## 限制與配額 ### 限制 使用 `XGameSaveFiles` 可儲存的檔案大小上限為 64 MB。此行為與將每個檔案限制為 16 MB 的 `XGameSave` 不同。 ### 配額 使用者可為每個遊戲儲存的資料上限為 256 MB。使用 [XGameSaveFilesGetRemainingQuota](/zh-TW/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) 取得剩餘配額。若要取得儲存空間擴充，讓您的遊戲擁有更大的每位使用者儲存空間上限，請連絡您的開發人員計畫經理 (DPM)。 ## 常見問題 ### 我可以將 XGameSaveFiles 與 XGameSave 搭配使用嗎？ 可以。不過，請僅在移轉時使用此方法。如需詳細資訊，請參閱 [XGameSave 與 XGameSaveFiles 之間的互通性](/zh-TW/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles)。 ### XGameSaveFiles 會儲存到哪個檔案路徑？ **主機**：遊戲在作用中時會提供暫存路徑。您無法使用檔案總管存取主機檔案。 **PC**：`%AppData%\Local\Packages\\SystemAppData\xgs\_\` `XGameSaveFiles` 的 PC 路徑與 `XGameSave` 不同。後者使用 `wgs`。 ### 我可以指定資料應儲存的路徑嗎？ 可以，但僅限 PC。我們只建議在您從另一個遊戲移植解決方案時使用此方法。此解決方案使用[無程式碼雲端存檔](/zh-TW/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 內容)](/zh-TW/reference/system/xgamesavefiles/xgamesavefiles_members) * 函式 * [XGameSaveFilesGetRemainingQuota](/zh-TW/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) ## 另請參閱 [Game Saves 目錄](/zh-TW/build/core-features/common/game-save/game-saves-toc) 可以，但僅限 PC。從另一個遊戲移植您的解決方案時，可能需要使用此方法。此解決方案使用[無程式碼雲端存檔](/zh-TW/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。 無程式碼雲端存檔需要使用 `wdapp install` 將遊戲以封裝組建的形式啟動。直接啟動 .exe 不會啟用雲端存檔重新導向。在封裝啟動與直接啟動 .exe 之間交替，可能會導致存檔資料看起來遺失了。如需詳細資訊，請參閱[使用無程式碼雲端存檔將先前的遊戲移植到 PC Game Saves](/zh-TW/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)。 ## Related topics - [XGameSaveFiles](/reference/system/xgamesavefiles/xgamesavefiles_members.md) - [XGameSaveFiles API overview](/build/core-features/common/game-save/xgamesavefiles.md) - [XGameSaveFiles API 概述](/zh-CN/build/core-features/common/game-save/xgamesavefiles.md) - [XGameSaveFiles API 개요](/ko/build/core-features/common/game-save/xgamesavefiles.md) - [XGameSaveFiles API の概要](/ja-jp/build/core-features/common/game-save/xgamesavefiles.md)