Depurar projetos XBOX usando o Visual Studio

A depuração de projetos XBOX do Microsoft Game Development Kit (GDK) no Visual Studio é habilitada pelo componente XBOX Debugger, instalado como parte do Microsoft Game Development Kit (GDK). Há suporte para o Visual Studio 2019 e 2022. O XBOX Debugger é o depurador padrão para todos os projetos cuja plataforma é Gaming.Xbox.One.x64 ou Gaming.Xbox.Scarlett.x64, conforme mostrado na captura de tela a seguir.

​

Configurar o depurador do Visual Studio

Quando o depurador é iniciado usando F5 no Visual Studio, o console padrão que você definiu usando outras ferramentas do Microsoft Game Development Kit (GDK), como o XBOX Manager ou o xbConnect, é usado por padrão. Para substituir esse comportamento, especifique um console usando a propriedade Remote IP Address na seção XBOX One da página de propriedades do projeto, conforme mostrado na captura de tela a seguir. A barra de ferramentas de depuração do Visual Studio inclui uma lista suspensa que indica em qual console o título será implantado quando iniciado por F5 ou Ctrl-F5. A lista suspensa tem um botão que pode ser usado para acessar rapidamente a página de propriedades do projeto caso o console de destino precise ser alterado. O depurador também pode ser iniciado no XBOX Gaming Explorer. Nesse caso, o console usado é o identificado na faixa de conexão na parte superior do XBOX Gaming Explorer, conforme mostrado na captura de tela a seguir.

​

Caminhos de símbolos

Os arquivos Program Database (.pdb) de vários componentes do Game OS estão disponíveis para uso ao depurar com o Visual Studio. Configurar o Visual Studio para usar esses símbolos fornece, por exemplo, pilhas de chamadas mais completas quando a execução é interrompida no depurador. Alguns dos símbolos do Game OS são instalados no seu PC de desenvolvimento pela instalação do Microsoft Game Development Kit (GDK), enquanto outros estão disponíveis nos servidores de símbolos públicos da Microsoft. Os símbolos do Game OS instalados pela instalação ficam localizados no PC de desenvolvimento em C:\Program Files (x86)\Microsoft GDK<edition number>\GXDK\gameKit\symbols. Os .pdbs independentes de plataforma ficam na raiz da pasta de símbolos. Os .pdbs específicos de plataforma ficam nos subdiretórios Xbox Series X|S e XboxOne. Para adicionar o caminho do diretório de símbolos do Game OS no seu PC local, use a configuração Symbols na seção Debugging da caixa de diálogo Options do Visual Studio, conforme mostrado na captura de tela a seguir. Para acessar os símbolos do Game OS disponíveis no servidor de símbolos públicos da Microsoft, marque a caixa de seleção Microsoft Symbol Servers na caixa de diálogo Symbols. Adicionar os servidores de símbolos da Microsoft como local de arquivos de símbolos fará o Visual Studio pesquisar no servidor de símbolos todos os binários carregados pelo seu título. Uma pesquisa exaustiva de símbolos pode ser demorada. Você pode reduzir esse tempo de pesquisa configurando o Visual Studio para procurar .pdbs apenas de um conjunto específico de binários que o seu título usa. Para especificar o conjunto de binários para os quais o Visual Studio deve procurar .pdbs, use a opção Load only specified modules na caixa de diálogo Options. A captura de tela a seguir mostra o Visual Studio configurado para carregar os símbolos do servidor de símbolos público apenas para alguns binários selecionados.

​

Propriedades relacionadas à depuração

O depurador pode ser configurado ainda mais por meio de um conjunto de propriedades expostas na caixa de diálogo de propriedades do projeto e na guia Settings do XBOX Gaming Explorer. Essas propriedades incluem, por exemplo, a capacidade de passar argumentos de linha de comando para o seu título e de ativar o registro em log do carregamento de módulos. Para obter detalhes sobre as propriedades disponíveis, veja Propriedades do Visual Studio para desenvolvimento para XBOX e XBOX Gaming Explorer.

​

Anexar a um título em execução

O menu XBOX e o XBOX Gaming Explorer incluem opções de menu para anexar o depurador a um jogo em execução em um console. Para anexar ao jogo em execução no seu console padrão, use Attach to Running Game no menu XBOX. O menu XBOX pode ser acessado na barra de menus do Visual Studio, conforme mostrado na captura de tela a seguir. Você também pode anexar a um jogo em execução em qualquer console que tenha adicionado com o XBOX Gaming Explorer. Os menus de contexto das seções Game Processes e Titles da guia Home incluem itens de menu para anexar a um jogo em execução, conforme mostrado na captura de tela a seguir. O menu de contexto de um console específico na guia Consoles anexa ao jogo em execução nesse console, conforme mostrado na captura de tela a seguir. A caixa de diálogo Attach, no menu Debug do Visual Studio, também pode ser usada para anexar a um título em execução. Ao usar o Visual Studio 2022, selecione XBOX Direct Connection na lista suspensa Connection Type e insira o endereço IP do host ou o endereço IP do sistema do console na caixa de texto Connection Target. Os endereços IP do host e do sistema podem ser determinados usando a ferramenta de linha de comando xbconnect. Ao usar o Visual Studio 2019, selecione Remote No Authentication na lista suspensa Connection Type e insira o endereço IP do host do console na caixa de texto Connection Target.

​

Depurar projetos XBOX usando o Visual Studio 2022

A depuração com o Visual Studio 2022 requer que o título depurado seja compilado com o Microsoft Game Development Kit (GDK) de outubro de 2021 (ou mais recente). A dependência do Microsoft Game Development Kit (GDK) de outubro de 2021 (ou mais recente) existe porque o Game OS fornecido nessas versões do Microsoft Game Development Kit (GDK) contém binários necessários para a depuração com o Visual Studio 2022. O erro a seguir é exibido se houver uma tentativa de depurar com o Visual Studio 2022 em um Game OS mais antigo.

​

Depurar builds empacotados

As opções de menu de contexto do XBOX Gaming Explorer para iniciar um título no depurador ou anexar a um título em execução funcionam tão bem para builds empacotados quanto para implantações de arquivos soltos. Os pacotes de instalação por streaming são identificados pelo tipo de implantação Install e pelo ícone no XBOX Gaming Explorer, conforme mostrado na captura de tela a seguir.

​

Depurar transições entre estados do ciclo de vida do jogo

Dar suporte adequado ao ciclo de vida do jogo exige que você escreva manipuladores de eventos para as transições entre os estados de ciclo de vida completo, suspenso e restrito. O Visual Studio oferece vários recursos para ajudar você a escrever os manipuladores de eventos robustos necessários para que o seu título passe com êxito pelas transições de estado do ciclo de vida do jogo. Os menus de contexto do XBOX Gaming Explorer incluem opções para Suspend, Resume e Constrain o seu título, para que você possa depurar seus manipuladores em um dev kit. Observe que você também pode disparar essas transições de estado manualmente pelo XBOX Manager e pela ferramenta de linha de comando xbApp. Independentemente de como uma transição de estado é disparada, as mensagens de diagnóstico que descrevem a transição, junto com quaisquer falhas, ficam visíveis no xbWatson e na janela XBOX System Monitor do Visual Studio. Em um ambiente de varejo, os manipuladores do evento Suspend precisam ser concluídos em menos de 1 segundo; caso contrário, o sistema encerrará o seu título. Obviamente, esse limite de tempo de suspensão nem sempre deve ser aplicado em kits de desenvolvimento, ou seria quase impossível depurar um manipulador de Suspend. Por padrão, quando o depurador do Visual Studio (ou outro depurador de modo de usuário) está anexado, o tempo limite de suspensão de 1 segundo é desabilitado, permitindo que você use o tempo necessário para concluir sua tarefa de depuração. O depurador do Visual Studio também pode ser configurado para reabilitar o tempo limite de suspensão quando anexado. Nesse modo, se o seu manipulador de Suspend não for concluído dentro do limite de 1 segundo, o depurador forçará uma interrupção para que você veja em que ponto do manipulador de Suspend você estava quando o limite de tempo expirou. Executar o depurador nesse modo ajuda a ter uma noção da frequência com que o seu manipulador de Suspend excede o limite de tempo e por quê. Defina a propriedade Break On Suspend Timeout no Visual Studio para colocar o depurador em um modo em que o tempo limite de suspensão está habilitado. A interrupção de depuração que ocorre nesse modo é feita em uma nova thread que o depurador injeta no processo. Navegue até a thread que contém o manipulador de Suspend para começar a depurar. Se nenhum depurador estiver anexado ao seu título quando ocorrer um tempo limite de suspensão, o sistema criará um despejo de falha de quiesce. Esses despejos podem ser acessados usando o painel Memory Dump no xbWatson.

​

Depuração dinâmica do C++ no Visual Studio 2022

A depuração dinâmica do C++ é um novo recurso de depuração que oferece uma experiência completa de depuração para código otimizado sem comprometer o desempenho. Coloque pontos de interrupção desotimizados e entre em qualquer lugar com a desotimização de funções sob demanda. Para ativar a depuração dinâmica do C++: clique com o botão direito do mouse no seu projeto, Properties > Configuration Properties > Advanced > Advanced Properties > Use C++ Dynamic Debugging (preview). A versão 17.14 Preview 2 ou mais recente do Visual Studio 2022 é necessária para usar o recurso de depuração dinâmica. Acesse https://aka.ms/dynamicdebugging para saber mais.

​

Veja também

XBOX Gaming Explorer Visual Studio