Información general sobre almacenamiento conectado
El almacenamiento conectado le permite a su título guardar datos de juego y otros datos de estado pertinentes que deberían moverse entre los dispositivos.
La API de almacenamiento conectado permite que los títulos de Xbox One (o posterior) y la plataforma universal de Windows (UWP) guarden, carguen y eliminen los datos de título que se almacenan localmente y que también se sincronizan con la nube siempre que el título de Xbox o UWP esté conectado a Internet. Los datos guardados estarán disponibles en cualquier otro dispositivo que ejecute su título después de que se produzca la sincronización.
Se recomienda a los programadores que guarden el estado de título de la manera más exacta posible para ofrecer la mejor experiencia de cara a casa. El almacenamiento conectado te permite progresar en un juego en tu casa y luego retoma tu juego en cualquier otro dispositivo que sea compatible con el mismo juego.
Características de almacenamiento conectado
La API de almacenamiento conectado ofrece las siguientes características:
- Las aplicaciones pueden guardar rápidamente hasta 16 MB de datos a la vez en un búfer de memoria, que el sistema almacena en la caché local en el disco duro y se carga en la nube.
- Para socios administrados:
- 256 MB por usuario/aplicación de almacenamiento en la nube.
- Para los programadores de programas de creadores:
- 64 MB por usuario/aplicación de almacenamiento en la nube.
- Respuesta sólida a los errores de energía: las aplicaciones no tienen que tratar con los datos parciales que se guardan.
- Los datos se cargan automáticamente en la nube, incluso cuando la aplicación no se está ejecutando.
- Los datos están disponibles en dispositivos Xbox o UWP que están conectados a Xbox Live.
- Xbox Live controla la sincronización de dispositivos cruzados y la administración de conflictos sin requerir la implicación de la aplicación.
El sistema de almacenamiento conectado se asegura de que todos los cambios se hagan en su totalidad o no. Esto significa que, como desarrollador, nunca tendrá que preocuparse de los datos guardados parcialmente que afecten a su estado de juego en caso de que se produzca un corte de alimentación o que el usuario cierre la aplicación repentinamente, ya sea de forma manual o abriendo otra aplicación o juego en la consola.
Esto también garantiza una experiencia de juego más fluida para los usuarios de tu título, ya que el almacenamiento conectado es una parte importante de lo que permite a los usuarios cambiar entre juegos y aplicaciones de forma rápida y gratuita, pero seguir regresando al juego original en el estado en el que lo dejaron.
Para implementar estas características en su propio título, tendrá que comprender las API de almacenamiento conectados.
Estructura de almacenamiento conectado
El sistema de almacenamiento conectado permite a las aplicaciones almacenar datos como uno o más blobs en contenedores. En un nivel alto, todos los datos del sistema de almacenamiento conectado están asociados con un usuario o un usuario o equipo en el caso del kit de desarrollo de Xbox desarrollado títulos.
Todos los datos guardados por una aplicación para un usuario o equipo en particular se almacenan en un espacio de almacenamiento conectado.
Cada usuario de la aplicación obtiene un espacio de almacenamiento conectado con un límite de 256 o 64 MB de almacenamiento total. Este almacenamiento está dedicado solo a tu aplicación; no se comparte con otras aplicaciones.
Contenedores y blobs
El contenedor de almacenamiento conectado, o contenedor de corto, es la unidad básica de almacenamiento. Cada espacio de almacenamiento conectado puede contener varios contenedores, como se muestra en el siguiente diagrama.
Espacio de almacenamiento conectado (por puesto/equipo o por título/usuario)
Los datos se almacenan en contenedores como uno o más búferes denominados BLOB.
En el siguiente diagrama se muestra la representación interna del sistema de contenedores en el disco. Para cada contenedor, hay un archivo contenedor que contiene referencias al archivo de datos para cada BLOB del contenedor.
Diagrama de un contenedor
Para almacenar datos en un contenedor, llama al método de contenedor de API correspondiente SubmitUpdatesAsync, proporcionando un mapa de nombres y BLOB (objetos de búfer). Todos los cambios descritos en una llamada de SubmitUpdatesAsync se aplican de forma atómica, es decir, se actualizan todos los blobs solicitados o se finaliza toda la operación, y el contenedor permanece en su estado anterior a la llamada.
Las operaciones de guardado individuales que usan SubmitUpdatesAsync se limitan a 16 MB de datos a la vez.
API de almacenamiento conectado
El almacenamiento conectado tiene APIs independientes para las aplicaciones para UWP y XDK.
Afortunadamente, estas API se parecen muy estrechamente. Las dos API se diferencian principalmente en el espacio de nombres y los nombres de clase.
Las funciones necesarias para Guardar, cargary eliminar datos con la API tienen el mismo nombre.
En la sección almacenamiento conectado de la migración del código de Xbox Live de XDK a UWPse detallan las diferencias adicionales entre las dos API de almacenamiento conectados.
Referencia de API almacenamiento XDK connected
Puede encontrar las API de almacenamiento conectado XDK documentadas en XboxOneXDK.chm el archivo en la ruta de acceso:
La API de Xbox One XDK >> referencia de la API de >> Platform >> referencia de la API del sistema >> Windows. xbox. almacenamiento
Las API de XDK también están documentadas en el sitio de developer.Microsoft.com. El vínculo a las API de XDK requiere que tenga una cuenta de Microsoft (MSA) que se haya habilitado para obtener acceso al kit para desarrolladores de Xbox (XDK).
Windows.Xbox.Storage es el nombre del espacio de nombres de almacenamiento conectado para consolas Xbox.
Referencia de API de almacenamiento conectado por UWP
Puede encontrar las API de almacenamiento conectado a UWP documentadas en el archivo. chm del SDK de Xbox Live en la ruta de acceso:
API de Xbox Live >> referencia de la API del SDK de las extensiones de plataformas para Xbox Live >> Windows. Gaming. XboxLive. Storage
Las API de almacenamiento conectado a UWP también se documentan en línea: Windows. Gaming. XboxLive. Storage namespace Reference
Windows.Gaming.XboxLive.Storage es el nombre del espacio de nombres de almacenamiento conectado para aplicaciones para UWP.
Adquisición de un espacio de almacenamiento conectado
Para empezar a usar almacenamiento conectado, tendrá que adquirir un espaciode almacenamiento conectado. Un espacio de almacenamiento conectado está asociado con un usuario o equipo y contiene todos los datos de almacenamiento conectados asociados con ese usuario o equipo en forma de contenedores y blobs.
La adquisición de un espacio de almacenamiento conectado para un equipo o usuario le dará acceso para leer y escribir en los datos almacenados de las entidades.
Para adquirir un espacio de almacenamiento conectado, tanto los títulos de XDK como GetForUserAsync los de UWP llaman al método.
Los títulos de XDK (no UWP) también pueden GetForMachineAsync llamar al método.
- En la XDK,
GetForUserAsyncyGetForMachineAsyncse incluyen en laConnectedStorageSpaceclase. - En la UWP
GetForUserAsync, está contenido enGameSaveProviderla clase.
Estos métodos son operaciones de ejecución prolongada, especialmente si el usuario ha guardado datos en un dispositivo y va a reanudar el juego por primera vez en otro dispositivo.
GetForUserAsync Recupera un espacio de almacenamiento conectado para un usuario que puede usar para crear, acceder y eliminar contenedores.
Crear un contenedor o acceder a él
Para crear un contenedor o tener acceso a un contenedor creado previamente, llama CreateContainer a la función ConnectedStorageSpace de GameSaveProvider tu clase o.
Esto le dará acceso a un contenedor con nombre para el usuario o equipo que está asociado con el ConnectedStorageSpace o GameSaveProvider que se usó para crear el contenedor.
Las ConnectedStorageSpace clases GameSaveProvider y también incluyen la DeleteContainerAsync función, que permite eliminar un contenedor por nombre.
Actualización de blobs en un contenedor
Para actualizar los blobs del contenedor, SubmitUpdatesAsyncllama, que se encuentra ConnectedStorageContainer en la clase de la XDK, y GameSaveContainer en la clase de la API de UWP.
SubmitUpdatesAsync permite proporcionar una lista de nombres y búferes como datos para escribir en el BLOB, una lista de nombres de los blobs que se van a eliminar y un nombre para mostrar para el contenedor de la llamada.
Esta es la función que, en última instancia, necesitarás llamar para actualizar los datos del espacio de almacenamiento conectado.
Ejemplos de uso de la API de almacenamiento conectado
Para ver ejemplos de las API de almacenamiento conectados en uso, consulte los siguientes artículos de almacenamiento conectados:
Nota
Una nota sobre seguridad:
Las aplicaciones de la plataforma universal de Windows (UWP) que se ejecutan en equipos informáticos guardan los datos locales en una ubicación accesible para el usuario local y no están protegidos de forma inherente contra la manipulación de usuarios. Debe considerar la posibilidad de aplicar sus propias comprobaciones de cifrado y de validez a los datos del juego, para evitar que los usuarios modifiquen el juego en el exterior del juego.
Por el mismo motivo, debes decidir si deseas permitir que las versiones de PC y Xbox de tu juego compartan las acciones de guardar o mantenerlas separadas.
Administrar almacenamiento local
Al probar el almacenamiento conectado en el kit de desarrollo de Xbox o la aplicación para UWP, es posible que necesites manipular los datos almacenados de forma local en el dispositivo de desarrollo.
- La herramienta xbstorage se incluye con el XDK y es una herramienta de línea de comandos que le permitirá manipular el almacenamiento local en su consola de desarrollo.
- Para los desarrolladores de UWP, hay una herramienta idéntica para el
gamesaveutil.exePC a la que se le llama, que se incluye con el SDK de Windows 10 para la actualización de otoño de los creadores (10.0.16299.91) y versiones posteriores.
Estas dos herramientas le permiten manipular el almacenamiento local en su dispositivo con estos comandos:
| Mando | Descripción |
|---|---|
| restablecer | Realiza un restablecimiento de fábrica en el almacenamiento conectado. |
| mesa | Importa los datos del archivo XML especificado a un espacio de almacenamiento conectado. |
| Portada | Exporta datos de un espacio de almacenamiento conectado al archivo XML especificado. |
| eliminar | Elimina datos de un espacio de almacenamiento conectado. |
| crea | Genera datos ficticios y guarda en el archivo XML especificado. |
| simular | Simula las condiciones de espacio de almacenamiento. |
Para obtener más información sobre las funciones disponibles en xbstorage la herramienta xbstorage gamesaveutils.exey consulte Managing local Connected Storage.
Información general técnica
Para obtener más información detallada sobre cómo funciona el almacenamiento conectado en la XDK, consulta la Descripción técnica de almacenamiento conectado. La descripción técnica ha sido escrita específicamente para desarrolladores de XDK, pero los conceptos que se incluyen en se aplican al almacenamiento conectado en general.