XGameSaveFilesGetFolderWithUIAsync。也會說明建議的 Win32 自動雲端同步行為、偵錯步驟、配額與診斷指引、效能最佳做法，以及常見問題的解答。
XGameSaveFiles 提供的 API 可讓您的遊戲讀取與寫入使用者資料、跨工作階段保存資料，並順暢地與雲端同步，讓玩家可以在任何裝置上使用其資料。請在 Microsoft Game Development Kit (GDK) 遊戲中使用 XGameSaveFiles 處理遊戲存檔。只有在 XGameSaveFiles 不適用於您的案例時，才使用 XGameSave。
如需 XGameSaveFiles 的系統 API 參考，請參閱 XGameSaveFiles (API 內容)。
下列詞彙經常出現在 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 儲存體，因此仍會強制執行目錄與檔案名稱限制。請參考下列範例程式碼，了解遊戲可能用於其存檔的路徑。
XGameSaveFilesGetFolderWithUiAsync會傳回 [ROOT]。- [ROOT] 之後到最後一個斜線 (含) 為止的所有內容，都會對應到一個容器。
- 容器名稱僅限使用大寫字母 (A-Z)、小寫字母 (a-z)、數字 (0-9)、底線 (_)、句點 (.)、連字號 (-) 與斜線 (/)。
- 容器名稱上限為 256 個字元。
- 容器名稱不能以句點結尾、不能包含兩個連續的句點，也不能以句點或連字號開頭。
- 檔案名稱中最後一個斜線之後的所有內容，都會對應到一個 Blob。
- 檔案名稱上限為 65 個字元，除此之外可以是 New Technology File System (NTFS) 支援的任何 Unicode 字元。
- 包含檔案名稱 (但不含 [ROOT]) 的完整結果路徑必須小於
MAX_PATH(260 個字元)。
XGameSaveFiles 的實作
下列步驟顯示XGameSaveFiles 的一般實作。
- 在遊戲啟動或繼續時，呼叫
XGameSaveFilesGetFolderWithUIAsync以初始化提供者並取得檔案路徑。 - 在遊玩期間自由讀取與寫入該檔案路徑。
XGameSaveFilesGetFolderWithUIAsync 會自動管理 Game Saves 提供者的存留期，並設定 Game Saves 本機儲存空間。
請在遊戲啟動及繼續時呼叫
XGameSaveFilesGetFolderWithUIAsync。此呼叫會初始化 Game Saves 提供者，並在遊戲工作階段執行期間保持其作用中。如果您略過此步驟，系統的行為可能無法預測。程式碼範例
如需示範如何使用XGameSaveFiles API 存取 XBOX 上資料夾的程式碼範例，請參閱 GameSaveFilesCombo。
Game Saves 流程
以下是簡化 Game Saves 流程的流程圖。
遊戲啟動
使用者啟動或繼續遊戲時，即為遊戲啟動。使用者登入
遊戲會開始使用者登入程序。您也會在此作業中呼叫XGameSaveFilesGetFolderWithUIAsync。如需使用者設定的詳細資訊，請參閱使用者模型。
連線檢查
遊戲會判斷是否能連線到 XBOX 網路。如果無法連線，您需要為遊戲啟用離線模式。資料擁有權檢查
裝置會檢查使用者目前是否正在其他裝置上遊玩。對於特定遊戲，一次只能有一部裝置存取使用者的資料。與雲端同步資料
裝置會將 Game Saves 本機儲存空間資料與雲端同步。如果發生衝突，系統會以衝突解決對話方塊提示使用者。 對話方塊：您要使用哪一個？ 如果裝置上的資料比雲端資料新，遊戲會提示使用者選擇使用本機資料或雲端資料。遊戲迴圈
遊戲可以自由讀取與寫入XGameSaveFilesGetFolderWithUIAsync 提供的資料夾路徑。
遊戲工作階段結束
遊戲工作階段結束時，系統會自動嘗試將資料上傳到雲端。此程序會在遊戲結束後約 10 到 30 秒進行。 如需詳細的同步資訊，請參閱了解 Game Saves 同步流程。限制與配額
限制
使用XGameSaveFiles 可儲存的檔案大小上限為 64 MB。此行為與將每個檔案限制為 16 MB 的 XGameSave 不同。
配額
使用者可為每個遊戲儲存的資料上限為 256 MB。使用 XGameSaveFilesGetRemainingQuota 取得剩餘配額。若要取得儲存空間擴充，讓您的遊戲擁有更大的每位使用者儲存空間上限，請連絡您的開發人員計畫經理 (DPM)。常見問題
我可以將 XGameSaveFiles 與 XGameSave 搭配使用嗎？
可以。不過，請僅在移轉時使用此方法。如需詳細資訊，請參閱 XGameSave 與 XGameSaveFiles 之間的互通性。XGameSaveFiles 會儲存到哪個檔案路徑？
主機：遊戲在作用中時會提供暫存路徑。您無法使用檔案總管存取主機檔案。 PC：%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
XGameSaveFiles 的 PC 路徑與 XGameSave 不同。後者使用 wgs。
我可以指定資料應儲存的路徑嗎？
可以，但僅限 PC。我們只建議在您從另一個遊戲移植解決方案時使用此方法。此解決方案使用無程式碼雲端存檔。參考 API 文件
另請參閱
Game Saves 目錄 可以，但僅限 PC。從另一個遊戲移植您的解決方案時，可能需要使用此方法。此解決方案使用無程式碼雲端存檔。無程式碼雲端存檔需要使用
wdapp install 將遊戲以封裝組建的形式啟動。直接啟動 .exe 不會啟用雲端存檔重新導向。在封裝啟動與直接啟動 .exe 之間交替，可能會導致存檔資料看起來遺失了。如需詳細資訊，請參閱使用無程式碼雲端存檔將先前的遊戲移植到 PC Game Saves。