XGameSave API 可讓您管理 Blob 與容器，以管理 Game Saves 資料。對於 Microsoft Game Development Kit (GDK) 遊戲的 Game Saves，我們建議使用 XGameSaveFiles。如果無法使用 XGameSaveFiles，請使用 XGameSave。
如需 XGameSave 的系統 API 參考，請參閱 XGameSave (API 內容)。
下列詞彙經常出現在 XGameSave 中。
- 鎖定：一種機制，可針對特定使用者在其目前使用的裝置上，授與對遊戲 Game Saves 的獨佔存取權。它可確保在持有鎖定期間，沒有其他裝置可以修改該使用者的 Game Saves。
- 例如，如果使用者在裝置 A 上玩遊戲 T，裝置 A 就會為該使用者持有遊戲 T 的鎖定。
- 提供者：與 Game Save 系統通訊並負責管理遊戲資料的中介處理程序。提供者也會管理使用者在裝置上的鎖定。
- 容器：類似於資料夾。
- 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。
Game Saves 流程
以下是簡化 Game Saves 流程的流程圖。說明如下。
遊戲啟動
使用者啟動或繼續遊戲時，即為遊戲啟動。使用者登入
遊戲會起始使用者登入。您也會在此呼叫中叫用XGameSaveInitializeProvider。
如需使用者設定的詳細資訊，請參閱使用者模型。
連線檢查
遊戲會判斷是否能連線到 XBOX 網路。如果無法連線，則由您決定是否為遊戲啟用離線模式。資料擁有權檢查
裝置會檢查使用者目前是否正在其他裝置上遊玩。對於特定遊戲，一次只能有一部裝置存取使用者的資料。與雲端同步資料
裝置會將 Game Saves 本機儲存空間資料與雲端同步。如果發生衝突，系統會以衝突解決對話方塊提示使用者。 對話方塊：您要使用哪一個？ 當裝置上的資料比雲端資料新時，遊戲會提示使用者選擇使用本機資料或雲端資料。遊戲迴圈
遊戲可以自由讀取與寫入 Game Saves 本機儲存空間。遊戲工作階段結束
遊戲工作階段結束時，系統會自動嘗試將資料上傳到雲端。請確保您的遊戲在結束流程中呼叫XGameSaveUninitializeProvider，以避免讓提供者保持初始化狀態。結構化的關機可確保資料在結束前完整儲存。
如需詳細的同步資訊，請參閱了解 Game Saves 同步流程。
限制與配額
限制
XGameSaveUpdate 將每個更新限制為 16 MB。因此，XGameSave 只能管理最多 16 MB 的個別檔案更新。此限制與支援最多 64 MB 檔案的 XGameSaveFiles 不同。
配額
使用者可為每個遊戲儲存的資料上限為 256 MB。使用 XGameSaveGetRemainingQuota 取得剩餘配額。若要為您的遊戲取得儲存空間擴充，請連絡您的開發人員合作夥伴經理 (DPM)。最佳做法
- 請勿在儲存資料後立即查詢並要求取回相同的資料。
- 跨容器的資料相依性並不可靠。每個
XGameSaveSubmitUpdate呼叫都會以不可部分完成的方式套用所有變更，或完全不套用。 - 每次更新呼叫使用的 Blob 越多，完成儲存資料所需檔案系統作業之不可部分完成作業的時間就越長。
常見問題
我正在升級我的 Game Saves 實作。正確的方法是什麼？
使用 XGameSaveFiles。我可以將 XGameSave 與 XGameSaveFiles 搭配使用嗎？
可以。不過，請僅在移轉時這麼做。如需詳細資訊，請參閱 XGameSave 與 XGameSaveFiles 之間的互通性。XGameSave 會儲存到哪個檔案路徑？
主機：遊戲作用中時會提供暫存路徑。無法使用檔案總管存取主機檔案。 PC：%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
請注意，XGameSave 的 PC 路徑與 XGameSaveFiles 不同。後者使用 xgs。