> ## 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. # Visão geral da API XGameSaveFiles > Referência do XGameSaveFiles do XBOX que aborda XGameSaveFilesGetFolderWithUIAsync, o comportamento de sincronização na nuvem do Win32, cotas, depuração e práticas recomendadas de desempenho. Este artigo explica como inicializar `XGameSaveFilesGetFolderWithUIAsync`. Ele também descreve o comportamento recomendado de sincronização automática na nuvem do Win32, as etapas de depuração, as orientações sobre cota e diagnóstico, as práticas recomendadas de desempenho e as respostas a perguntas comuns. O `XGameSaveFiles` fornece APIs que permitem que seu título leia e grave dados do usuário, mantenha-os entre sessões e os sincronize perfeitamente com a nuvem para que os jogadores possam usar seus dados em qualquer dispositivo. Use `XGameSaveFiles` para jogos salvos em títulos do Microsoft Game Development Kit (GDK). Use `XGameSave` somente quando `XGameSaveFiles` não estiver disponível para o seu cenário. Para a referência da API do sistema para `XGameSaveFiles`, consulte [XGameSaveFiles (conteúdo da API)](/pt-BR/reference/system/xgamesavefiles/xgamesavefiles_members). Os termos a seguir aparecem com frequência no `XGameSaveFiles`. * **Bloqueio:** um mecanismo que concede acesso exclusivo ao Game Saves de um título para um usuário específico no dispositivo que ele está usando ativamente. Ele garante que nenhum outro dispositivo possa modificar os jogos salvos do usuário enquanto o bloqueio estiver mantido. * Por exemplo, se um usuário jogar o Título T no dispositivo A, esse dispositivo terá um bloqueio do Título T para o usuário. * **Provedor:** o processo intermediário que se comunica com o sistema Game Save e é responsável por gerenciar os dados do título. O provedor também gerencia o bloqueio de um usuário em um dispositivo. * **Contêineres**: análogos a pastas. * **Blobs**: análogos a arquivos individuais. ## Lógica de caminho do XGameSaveFiles O `XGameSaveFiles` fornece um caminho de arquivo que você pode usar para interagir com o sistema Game Saves. O caminho de arquivo se integra à sincronização na nuvem, de modo que os dados salvos no caminho são sincronizados automaticamente com a nuvem. Use as APIs `FileIO` do Win32 no caminho fornecido. Para títulos do GDK, use `XGameSaveFiles` como a abordagem do Game Saves. O `XGameSaveFiles` mapeia os conceitos de contêineres para pastas e de blobs para arquivos. Embora o `XGameSaveFiles` oculte a maior parte da complexidade do sistema de salvamento na nuvem, ele ainda impõe limites de diretório e de nome de arquivo porque o recurso depende do Armazenamento de Blobs do Microsoft Azure. Considere o código de exemplo a seguir do que um título poderia usar para seu salvamento. ``` [ROOT]/Save1/WingtipToys/state001.dat ``` * `XGameSaveFilesGetFolderWithUiAsync` retorna o \[ROOT]. * Tudo o que vem depois de \[ROOT], até a barra final inclusive, é mapeado para um contêiner. * Os nomes de contêiner são limitados a letras maiúsculas (A-Z), letras minúsculas (a-z), números (0-9), sublinhados (\_), pontos (.), hifens (-) e barras (/). * Os nomes de contêiner são limitados a 256 caracteres. * Os nomes de contêiner não podem terminar com um ponto, conter dois pontos consecutivos nem começar com um ponto ou hífen. * Tudo o que vem depois da barra final no nome do arquivo é mapeado para um blob. * Os nomes de arquivo são limitados a 65 caracteres, mas, fora isso, podem conter quaisquer caracteres Unicode compatíveis com o New Technology File System (NTFS). * O caminho completo resultante, incluindo o nome do arquivo (mas não o \[ROOT]), deve ter menos que `MAX_PATH` (260 caracteres). Para obter mais informações sobre Win32 e gerenciamento de arquivos, consulte [Gerenciamento de arquivos (sistemas de arquivos locais)](https://learn.microsoft.com/windows/win32/fileio/file-management). ## Implementação do XGameSaveFiles As etapas a seguir mostram a implementação geral do `XGameSaveFiles`. 1. No início ou na retomada do título, chame `XGameSaveFilesGetFolderWithUIAsync` para inicializar o provedor e obter o caminho do arquivo. 2. Leia e grave livremente no caminho do arquivo durante o jogo. `XGameSaveFilesGetFolderWithUIAsync` gerencia automaticamente o tempo de vida do provedor do Game Saves e configura o espaço de armazenamento local do Game Saves. Chame `XGameSaveFilesGetFolderWithUIAsync` quando o título for iniciado e quando for retomado. Essa chamada inicializa o provedor do Game Saves e o mantém ativo enquanto a sessão de jogo é executada. Se você ignorar esta etapa, o sistema poderá se comportar de forma imprevisível. ### Exemplo de código Para obter um exemplo de código que mostra como usar as APIs do `XGameSaveFiles` para acessar pastas no XBOX, consulte [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/). ## Fluxo do Game Saves Aqui está um fluxograma do fluxo simplificado do Game Saves. Fluxograma do processo simplificado de sincronização do Game Saves. ### Início do título O início do título ocorre quando o usuário inicia ou retoma o título. ### Entrada do usuário O título inicia o processo de entrada do usuário. Essa operação também é onde você chama `XGameSaveFilesGetFolderWithUIAsync`. Para obter mais informações sobre a configuração do usuário, consulte [Modelos de usuário](/pt-BR/build/core-features/common/game-save/game-saves-developer-guide#user-models). ### Verificação de conexão O título determina se pode se conectar à rede XBOX. Se não puder, você precisará habilitar o [modo offline](/pt-BR/build/core-features/common/game-save/game-saves-syncing#connection-check) para o título. ### Verificação de propriedade dos dados O dispositivo verifica se o usuário está jogando atualmente em outros dispositivos. Apenas um dispositivo por vez pode acessar os dados do usuário para um título específico. ### Sincronizar dados com a nuvem O dispositivo sincroniza os dados do armazenamento local do Game Saves com a nuvem. Se houver um conflito, o sistema exibirá ao usuário uma caixa de diálogo de resolução de conflitos. Caixa de diálogo: [Qual você deseja usar?](/pt-BR/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) Se os dados no dispositivo forem mais recentes que os dados na nuvem, o título solicitará que o usuário escolha entre usar os dados locais ou os dados da nuvem. ### Loop de jogo O título pode ler e gravar livremente no caminho da pasta fornecido por `XGameSaveFilesGetFolderWithUIAsync`. ### Fim da sessão de jogo Quando a sessão de jogo termina, o sistema tenta carregar automaticamente os dados para a nuvem. Esse processo ocorre cerca de 10 a 30 segundos após o término do título. Para obter informações detalhadas sobre sincronização, consulte [Noções básicas sobre o fluxo de sincronização do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-syncing). ## Limites e cotas ### Limites O tamanho máximo de arquivo que você pode salvar usando `XGameSaveFiles` é 64 MB. Esse comportamento é diferente do `XGameSave`, que limita cada arquivo a 16 MB. ### Cotas O máximo de dados que um usuário pode salvar por título é 256 MB. Use [XGameSaveFilesGetRemainingQuota](/pt-BR/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) para obter a cota restante. Para obter uma extensão de armazenamento para que seu título tenha um limite de armazenamento por usuário maior, entre em contato com o Gerente de Programa de Desenvolvedor (DPM). ## Perguntas frequentes ### Posso usar XGameSaveFiles com XGameSave? Sim. No entanto, use essa abordagem somente para migrações. Para obter informações detalhadas, consulte [Interoperabilidade entre XGameSave e XGameSaveFiles](/pt-BR/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles). ### Em qual caminho de arquivo o XGameSaveFiles salva? **Console**: o título fornece um caminho temporário enquanto está ativo. Não é possível acessar os arquivos do console pelo Explorador de Arquivos. **PC**: `%AppData%\Local\Packages\\SystemAppData\xgs\_\` O caminho no PC para `XGameSaveFiles` é diferente do de `XGameSave`. Ele usa `wgs`. ### Posso especificar o caminho em que os dados devem ser salvos? Sim, mas somente no PC. Recomendamos essa abordagem apenas se você estiver portando sua solução de outro título. Essa solução usa [salvamentos na nuvem sem código](/pt-BR/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves). ## Documentação de referência da API * [XGameSaveFiles (conteúdo da API)](/pt-BR/reference/system/xgamesavefiles/xgamesavefiles_members) * Funções * [XGameSaveFilesGetRemainingQuota](/pt-BR/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) ## Confira também [Sumário do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-toc) Sim, mas somente no PC. Portar sua solução de outro título pode exigir essa abordagem. Essa solução usa [salvamentos na nuvem sem código](/pt-BR/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves). Os salvamentos na nuvem sem código exigem que o título seja iniciado como um build empacotado usando `wdapp install`. Iniciar o .exe diretamente não ativa o redirecionamento de salvamento na nuvem. Alternar entre inicializações empacotadas e inicializações diretas do .exe pode fazer com que os dados salvos pareçam estar ausentes. Para obter mais informações, consulte [Portando títulos anteriores para o Game Saves do PC com salvamentos na nuvem sem código](/pt-BR/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 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) - [Visão geral de Godot e engines da comunidade](/pt-BR/paths/community-engines/overview.md) - [Visão geral de portabilidade](/pt-BR/paths/porting/overview.md)