Depuración de proyectos de XBOX con Visual Studio

La depuración de proyectos de XBOX de Microsoft Game Development Kit (GDK) desde Visual Studio se habilita mediante el componente XBOX Debugger, que se instala como parte de Microsoft Game Development Kit (GDK). Se admiten Visual Studio 2019 y 2022. XBOX Debugger es el depurador predeterminado para todos los proyectos cuya plataforma sea Gaming.Xbox.One.x64 o Gaming.Xbox.Scarlett.x64, como se muestra en la siguiente captura de pantalla.

​

Configuración del depurador de Visual Studio

Cuando el depurador se inicia con F5 desde Visual Studio, se usa de forma predeterminada la consola predeterminada que estableció mediante otras herramientas de Microsoft Game Development Kit (GDK), como XBOX Manager o xbConnect. Para invalidar este comportamiento, especifique una consola mediante la propiedad Remote IP Address en la sección XBOX One de la página de propiedades de un proyecto, como se muestra en la siguiente captura de pantalla. La barra de herramientas de depuración de Visual Studio incluye una lista desplegable que indica en qué consola se implementará el título cuando se inicie con F5 o Ctrl-F5. La lista desplegable tiene un botón que puede usarse para acceder rápidamente a la página de propiedades del proyecto si es necesario cambiar la consola de destino. El depurador también puede iniciarse desde XBOX Gaming Explorer. En este caso, la consola que se usa es la que se identifica en la cinta de conexión de la parte superior de XBOX Gaming Explorer, como se muestra en la siguiente captura de pantalla.

​

Rutas de acceso de símbolos

Los archivos de base de datos de programa (.pdb) de varios componentes de Game OS están disponibles para usarse al depurar con Visual Studio. Configurar Visual Studio para usar estos símbolos proporciona, por ejemplo, pilas de llamadas más completas al entrar en el depurador. Algunos de los símbolos de Game OS se instalan en su equipo de desarrollo con el programa de instalación de Microsoft Game Development Kit (GDK), mientras que otros están disponibles en los servidores de símbolos públicos de Microsoft. Los símbolos de Game OS instalados por el programa de instalación se encuentran en el equipo de desarrollo en C:\Program Files (x86)\Microsoft GDK<edition number>\GXDK\gameKit\symbols. Los archivos .pdb independientes de la plataforma están en la raíz de la carpeta de símbolos. Los archivos .pdb específicos de cada plataforma están en los subdirectorios Xbox Series X|S y XboxOne. Para agregar la ruta de acceso al directorio de símbolos de Game OS en su equipo local, use la configuración Symbols en la sección Debugging del cuadro de diálogo Options de Visual Studio, como se muestra en la siguiente captura de pantalla. Para acceder a los símbolos de Game OS que están disponibles en el servidor de símbolos públicos de Microsoft, active la casilla Microsoft Symbol Servers en el cuadro de diálogo Symbols. Agregar los servidores de símbolos de Microsoft como ubicación de archivos de símbolos hará que Visual Studio busque en el servidor de símbolos todos los binarios que cargue su título. Una búsqueda exhaustiva de símbolos puede llevar mucho tiempo. Puede reducir este tiempo de búsqueda configurando Visual Studio para que solo busque archivos .pdb de un conjunto específico de binarios que use su título. Para especificar el conjunto de binarios en los que Visual Studio debe buscar archivos .pdb, use la opción Load only specified modules en el cuadro de diálogo Options. La siguiente captura de pantalla muestra Visual Studio configurado para cargar desde el servidor de símbolos públicos los símbolos de solo unos pocos binarios seleccionados.

​

Propiedades relacionadas con la depuración

El depurador puede configurarse aún más mediante un conjunto de propiedades expuestas en el cuadro de diálogo de propiedades del proyecto y en la pestaña Settings de XBOX Gaming Explorer. Estas propiedades incluyen, por ejemplo, la capacidad de pasar argumentos de línea de comandos al título y de activar el registro de la carga de módulos. Para obtener más información sobre las propiedades disponibles, consulte Propiedades de Visual Studio para el desarrollo en XBOX y XBOX Gaming Explorer.

​

Asociación a un título en ejecución

El menú XBOX y XBOX Gaming Explorer incluyen opciones de menú para asociar el depurador a un juego que se está ejecutando en una consola. Para asociarse al juego que se está ejecutando actualmente en su consola predeterminada, use Attach to Running Game en el menú XBOX. El menú XBOX es accesible desde la barra de menús de Visual Studio, como se muestra en la siguiente captura de pantalla. También puede asociarse a un juego que se esté ejecutando en cualquier consola que haya agregado con XBOX Gaming Explorer. Los menús contextuales de las secciones Game Processes y Titles de la pestaña Home incluyen elementos de menú para asociarse a un juego en ejecución, como se muestra en la siguiente captura de pantalla. El menú contextual de una consola específica en la pestaña Consoles permite asociarse al juego que se ejecuta en esa consola, como se muestra en la siguiente captura de pantalla. El cuadro de diálogo Attach del menú Debug de Visual Studio también puede usarse para asociarse a un título en ejecución. Cuando use Visual Studio 2022, seleccione XBOX Direct Connection en la lista desplegable Connection Type y escriba la dirección Host IP o System IP de la consola en el cuadro de texto Connection Target. Las direcciones Host IP y System IP pueden determinarse con la herramienta de línea de comandos xbconnect. Cuando use Visual Studio 2019, seleccione Remote No Authentication en la lista desplegable Connection Type y escriba la dirección Host IP de la consola en el cuadro de texto Connection Target.

​

Depuración de proyectos de XBOX con Visual Studio 2022

La depuración con Visual Studio 2022 requiere que el título que se depura esté compilado con la versión de octubre de 2021 (o posterior) de Microsoft Game Development Kit (GDK). La dependencia de la versión de octubre de 2021 (o posterior) de Microsoft Game Development Kit (GDK) existe porque el Game OS incluido en esas versiones de Microsoft Game Development Kit (GDK) contiene binarios necesarios para la depuración con Visual Studio 2022. Se muestra el siguiente error si se intenta depurar con Visual Studio 2022 en un Game OS más antiguo.

​

Depuración de compilaciones empaquetadas

Las opciones de menú contextual de XBOX Gaming Explorer para iniciar un título con el depurador o para asociarse a un título en ejecución funcionan igual de bien con compilaciones empaquetadas que con implementaciones de archivos sueltos. Los paquetes de instalación por streaming se identifican mediante el tipo de implementación Install y su icono en XBOX Gaming Explorer, como se muestra en la siguiente captura de pantalla.

​

Depuración de las transiciones entre los estados del ciclo de vida del juego

Para admitir correctamente el ciclo de vida del juego es necesario escribir controladores de eventos para las transiciones entre los estados de ciclo de vida completo, suspendido y restringido. Visual Studio proporciona varias características que le ayudan a escribir los controladores de eventos sólidos necesarios para que su título supere correctamente las transiciones de estado del ciclo de vida del juego. Los menús contextuales de XBOX Gaming Explorer incluyen opciones para aplicar Suspend, Resume y Constrain a su título, de modo que pueda depurar sus controladores en un kit de desarrollo. Tenga en cuenta que también puede desencadenar manualmente estas transiciones de estado desde XBOX Manager y la herramienta de línea de comandos xbApp. Independientemente de cómo se desencadene una transición de estado, los mensajes de diagnóstico que describen la transición, junto con los posibles errores, son visibles en xbWatson y en la ventana XBOX System Monitor de Visual Studio. En un entorno comercial, los controladores del evento Suspend deben completarse en menos de 1 segundo, o el sistema finalizará el título. Este límite de tiempo de suspensión claramente no debería aplicarse siempre en los kits de desarrollo, o depurar un controlador de Suspend sería casi imposible. De forma predeterminada, cuando el depurador de Visual Studio (u otro depurador de modo usuario) está asociado, el tiempo de espera de suspensión de 1 segundo está deshabilitado, lo que le permite tomarse el tiempo necesario para completar su tarea de depuración. El depurador de Visual Studio también puede configurarse para volver a habilitar el tiempo de espera de suspensión mientras está asociado. En este modo, si su controlador de Suspend no se completa dentro del límite de 1 segundo, el depurador forzará una interrupción para que pueda ver en qué punto de su controlador de Suspend se encontraba cuando expiró el límite de tiempo. Ejecutar con el depurador en este modo resulta útil para hacerse una idea de con qué frecuencia su controlador de Suspend supera el límite de tiempo y por qué. Establezca la propiedad Break On Suspend Timeout en Visual Studio para poner el depurador en un modo en el que el tiempo de espera de suspensión esté habilitado. La interrupción de depuración que se produce en este modo se realiza en un subproceso nuevo que el depurador inserta en el proceso. Vaya al subproceso que contiene el controlador de Suspend para comenzar a depurar. Si no hay un depurador asociado a su título cuando se produce un tiempo de espera de suspensión, el sistema creará un volcado de memoria de inmovilización (quiesce). Puede acceder a estos volcados mediante el panel Memory Dump de xbWatson.

​

Depuración dinámica de C++ en Visual Studio 2022

La depuración dinámica de C++ es una nueva característica de depuración que ofrece una experiencia de depuración completa para código optimizado sin comprometer el rendimiento. Coloque puntos de interrupción desoptimizados y depure paso a paso en cualquier punto con la desoptimización de funciones a petición. Para activar la depuración dinámica de C++: haga clic con el botón derecho en su proyecto, Properties > Configuration Properties > Advanced > Advanced Properties > Use C++ Dynamic Debugging (preview). Se requiere la versión 17.14 Preview 2 o posterior de Visual Studio 2022 para usar la característica de depuración dinámica. Vaya a https://aka.ms/dynamicdebugging para obtener más información.

​

Consulte también

XBOX Gaming Explorer Visual Studio