Visual Studio를 사용한 XBOX 프로젝트 디버깅

Visual Studio 내에서 XBOX Microsoft Game Development Kit(GDK) 프로젝트를 디버깅하는 기능은 Microsoft Game Development Kit(GDK) 설치의 일부로 설치되는 XBOX Debugger 구성 요소에 의해 활성화됩니다. Visual Studio 2019 및 2022가 지원됩니다. XBOX Debugger는 플랫폼이 Gaming.Xbox.One.x64 또는 Gaming.Xbox.Scarlett.x64인 모든 프로젝트의 기본 디버거이며, 아래 스크린샷과 같습니다.

​

Visual Studio 디버거 구성

Visual Studio 내에서 F5로 디버거를 실행하면 기본적으로 XBOX Manager나 xbConnect 같은 다른 Microsoft Game Development Kit(GDK) 도구를 사용해 설정한 기본 콘솔이 사용됩니다. 이 동작을 재정의하려면 다음 스크린샷과 같이 프로젝트 속성 페이지의 XBOX One 섹션 아래에 있는 Remote IP Address 속성을 사용해 콘솔을 지정하세요. Visual Studio의 디버깅 도구 모음에는 F5나 Ctrl-F5로 실행할 때 타이틀이 배포될 콘솔을 나타내는 드롭다운이 포함되어 있습니다. 드롭다운에는 대상 콘솔을 변경해야 할 때 프로젝트 속성 페이지에 빠르게 액세스할 수 있는 버튼이 있습니다. 디버거는 XBOX Gaming Explorer에서도 실행할 수 있습니다. 이 경우 사용되는 콘솔은 다음 스크린샷과 같이 XBOX Gaming Explorer 상단의 연결 리본에 식별된 콘솔입니다.

​

심볼 경로

Visual Studio로 디버깅할 때 사용할 수 있는 여러 Game OS 구성 요소의 Program Database(.pdb) 파일이 있습니다. Visual Studio가 이러한 심볼을 사용하도록 구성하면 예를 들어 디버거로 중단되었을 때 더 완전한 호출 스택을 제공합니다. 일부 Game OS 심볼은 Microsoft Game Development Kit(GDK) 설치 시 개발 PC에 설치되고, 그 외에는 Microsoft 공용 심볼 서버에서 사용할 수 있습니다. 설치 프로그램에서 설치된 Game OS 심볼은 개발 PC의 C:\Program Files (x86)\Microsoft GDK<edition number>\GXDK\gameKit\symbols 에 위치합니다. 플랫폼과 무관한 .pdb는 심볼 폴더의 루트에 있습니다. 플랫폼별 .pdb는 Xbox Series X|S 및 XboxOne 하위 디렉터리에 있습니다. 로컬 PC의 Game OS 심볼 디렉터리 경로를 추가하려면 다음 스크린샷과 같이 Visual Studio 옵션 대화 상자의 디버깅 섹션 아래에 있는 Symbols 설정을 사용하세요. Microsoft 공용 심볼 서버에서 사용할 수 있는 Game OS 심볼에 액세스하려면 Symbols 대화 상자에서 Microsoft Symbol Servers 확인란을 선택하세요. Microsoft 심볼 서버를 심볼 파일 위치로 추가하면 Visual Studio가 타이틀이 로드하는 모든 바이너리에 대해 심볼 서버를 검색하도록 합니다. 광범위한 심볼 검색은 시간이 오래 걸릴 수 있습니다. 타이틀이 사용하는 특정 바이너리 집합에 대해서만 .pdb를 찾도록 Visual Studio를 구성하여 이 검색 시간을 줄일 수 있습니다. .pdb를 찾아야 할 바이너리 집합을 지정하려면 옵션 대화 상자의 Load only specified modules 옵션을 사용하세요. 다음 스크린샷은 선택된 몇 개의 바이너리에 대해서만 공용 심볼 서버에서 심볼을 로드하도록 구성된 Visual Studio를 보여줍니다.

​

디버깅 관련 속성

디버거는 프로젝트 속성 대화 상자와 XBOX Gaming Explorer의 Settings 탭에 노출된 속성 세트를 통해 추가로 구성할 수 있습니다. 이러한 속성에는 예를 들어 타이틀에 명령줄 인수를 전달하고 로그 모듈 로딩을 켜는 기능이 포함됩니다. 사용 가능한 속성에 대한 자세한 내용은 XBOX 개발용 Visual Studio 속성 및 XBOX Gaming Explorer를 참조하세요.

​

실행 중인 타이틀에 연결

XBOX 메뉴와 XBOX Gaming Explorer에는 콘솔에서 실행 중인 게임에 디버거를 연결하는 메뉴 옵션이 포함되어 있습니다. 기본 콘솔에서 현재 실행 중인 게임에 연결하려면 XBOX 메뉴의 Attach to Running Game을 사용하세요. XBOX 메뉴는 다음 스크린샷과 같이 Visual Studio 메뉴 표시줄에서 액세스할 수 있습니다. XBOX Gaming Explorer로 추가한 모든 콘솔에서 실행 중인 게임에도 연결할 수 있습니다. Home 탭의 Game Processes 및 Titles 섹션의 컨텍스트 메뉴에는 다음 스크린샷과 같이 실행 중인 게임에 연결하는 메뉴 항목이 포함되어 있습니다. Consoles 탭의 특정 콘솔에 대한 컨텍스트 메뉴는 다음 스크린샷과 같이 해당 콘솔에서 실행 중인 게임에 연결합니다. Visual Studio의 디버그 메뉴에 있는 Attach 대화 상자를 사용해 실행 중인 타이틀에 연결할 수도 있습니다. Visual Studio 2022를 사용할 때는 Connection Type 드롭다운에서 XBOX Direct Connection을 선택하고 Connection Target 텍스트 상자에 콘솔의 Host IP 주소 또는 System IP 주소를 입력하세요. Host IP 및 System IP 주소는 xbconnect 명령줄 도구를 사용해 확인할 수 있습니다. Visual Studio 2019를 사용할 때는 Connection Type 드롭다운에서 Remote No Authentication을 선택하고 Connection Target 텍스트 상자에 콘솔의 Host IP 주소를 입력하세요.

​

Visual Studio 2022를 사용한 XBOX 프로젝트 디버깅

Visual Studio 2022로 디버깅하려면 디버깅 대상 타이틀이 2021년 10월(또는 이후) Microsoft Game Development Kit(GDK)로 빌드되어야 합니다. 이러한 버전의 Microsoft Game Development Kit(GDK)에 포함된 Game OS에는 Visual Studio 2022로 디버깅하는 데 필요한 바이너리가 포함되어 있어 2021년 10월(또는 이후) Microsoft Game Development Kit(GDK) 의존성이 있습니다. 이전 Game OS에 대해 Visual Studio 2022로 디버깅을 시도하면 다음 오류가 표시됩니다.

​

패키지 빌드 디버깅

XBOX Gaming Explorer에서 디버거로 타이틀을 실행하거나 실행 중인 타이틀에 연결하는 컨텍스트 메뉴 옵션은 느슨한 파일 배포와 마찬가지로 패키지 빌드에서도 잘 작동합니다. 스트리밍 설치 패키지는 다음 스크린샷과 같이 XBOX Gaming Explorer의 Install 배포 유형과 아이콘으로 식별됩니다.

​

Game Lifecycle 상태 간 전환 디버깅

Game Lifecycle을 제대로 지원하려면 full, suspended, constrained 라이프사이클 상태 간 전환에 대한 이벤트 핸들러를 작성해야 합니다. Visual Studio는 타이틀이 Game Lifecycle 상태 전환을 성공적으로 통과하는 데 필요한 견고한 이벤트 핸들러를 작성하는 데 도움이 되는 여러 기능을 제공합니다. XBOX Gaming Explorer의 컨텍스트 메뉴에는 개발 키트에서 핸들러를 디버그할 수 있도록 타이틀을 Suspend, Resume, Constrain할 수 있는 옵션이 포함되어 있습니다. XBOX Manager와 xbApp 명령줄 도구에서 이러한 상태 전환을 수동으로 트리거할 수도 있습니다. 상태 전환이 어떻게 트리거되든, 전환을 설명하는 진단 메시지와 실패 내용은 xbWatson과 Visual Studio 내의 XBOX System Monitor 창에서 확인할 수 있습니다. 리테일 환경에서 Suspend 이벤트 핸들러는 1초 이내에 완료되어야 하며, 그렇지 않으면 시스템이 타이틀을 종료합니다. 이 suspend 시간 제한은 개발 키트나 Suspend 핸들러 디버깅 시 항상 강제되어서는 안 됩니다. 그렇지 않으면 디버깅이 거의 불가능해집니다. 기본적으로 Visual Studio 디버거(또는 다른 사용자 모드 디버거)가 연결되면 1초 suspend 시간 초과가 비활성화되어 디버깅 작업을 완료하는 데 필요한 시간을 사용할 수 있습니다. Visual Studio 디버거는 연결된 상태에서도 suspend 시간 초과를 다시 활성화하도록 구성할 수 있습니다. 이 모드에서 Suspend 핸들러가 1초 제한 내에 완료되지 않으면 디버거가 강제로 중단하여 시간 제한이 만료되었을 때 Suspend 핸들러의 어디에 있었는지 확인할 수 있습니다. 이 모드에서 디버거를 실행하면 Suspend 핸들러가 얼마나 자주 시간 제한을 초과하는지, 그리고 그 이유가 무엇인지 파악하는 데 도움이 됩니다. suspend 시간 초과가 활성화된 모드로 디버거를 설정하려면 Visual Studio에서 Break On Suspend Timeout 속성을 설정하세요. 이 모드에서 발생하는 디버그 중단은 디버거가 프로세스에 주입하는 새 스레드에서 수행됩니다. 디버깅을 시작하려면 Suspend 핸들러가 포함된 스레드로 이동하세요. suspend 시간 초과가 발생했을 때 디버거가 타이틀에 연결되어 있지 않으면 시스템이 quiesce 크래시 덤프를 생성합니다. 이러한 덤프는 xbWatson의 Memory Dump 패널을 사용해 액세스할 수 있습니다.

​

Visual Studio 2022의 C++ Dynamic Debugging

C++ Dynamic Debugging은 성능을 손상시키지 않고 최적화된 코드에 대해 완전한 디버깅 경험을 제공하는 새 디버깅 기능입니다. 온디맨드 함수 최적화 해제를 통해 어디에서나 최적화 해제된 브레이크포인트를 배치하고 스텝인할 수 있습니다. C++ Dynamic Debugging을 활성화하려면 프로젝트에서 마우스 오른쪽 버튼을 클릭 후 속성 > 구성 속성 > 고급 > 고급 속성 > Use C++ Dynamic Debugging (preview)를 선택하세요. 동적 디버깅 기능을 사용하려면 Visual Studio 2022의 17.14 Preview 2 이상 버전이 필요합니다. 자세한 내용은 https://aka.ms/dynamicdebugging을 참조하세요.

​

참고

XBOX Gaming Explorer Visual Studio