Unity에서 C# 코드 디버그
애플리케이션이 실행되는 동안 디버거를 사용하여 소스 코드를 검사할 수 있습니다. Unity에서는 다음의 코드 에디터를 사용하여 C# 코드를 디버그할 수 있습니다.
- Visual Studio(Unity용 Visual Studio Tools 플러그인 사용)
- Mac용 Visual Studio
- Jetbrains Rider
- Visual Studio Code(실험 단계)
각 코드 에디터에서 지원되는 디버깅 기능은 약간 다를 수 있으나 중단점, 싱글 스테핑, 변수 검사와 같은 기본 기능은 공통적으로 제공됩니다. Unity 에디터나 Unity 플레이어에 코드 에디터를 연결하여 코드를 디버그할 수 있습니다.
Unity의 관리되는 코드 디버깅은 WebGL을 제외한 모든 플랫폼에서 작동하며, Mono 및 IL2CPP 스크립팅 백엔드와 함께 작동합니다.
코드 에디터 설정
Visual Studio(Windows)
Unity 에디터 설치 프로그램은 Visual Studio Tools for Unity 플러그인을 사용하여 Visual Studio를 설치할 수 있는 옵션을 포함합니다. 이 옵션은 Unity에서 디버깅을 위해 Visual Studio를 설정하는 경우 권장되는 방법입니다.
컴퓨터에 이미 Visual Studio가 설치되어 있으면 Visual Studio를 열고 Tools > Get Tools and Features…로 이동하여 Visual Studio Tools for Unity 플러그인을 찾아 설치합니다.
Mac용 Visual Studio
Unity 에디터 설치 프로그램은 Mac용 Visual Studio를 설치할 수 있는 옵션을 포함합니다. 이 옵션은 Unity에서 디버깅을 위해 Mac용 Visual Studio를 설정하는 경우 권장되는 방법입니다.
컴퓨터에 이미 Mac용 Visual Studio가 설치되어 있으면 Visual Studio을 열고 Visual Studio > Extensions > Install from file…로 이동하여 Visual Studio Tools for Unity 플러그인을 설치합니다.
Jetbrains Rider
JetBrains Rider의 기본 설치 버전을 이용하여 Windows 또는 Mac용 Unity에서 코드를 디버그할 수 있습니다. JetBrains 웹사이트를 방문하여 설치하십시오.
Visual Studio Code
Unity에서 Visual Studio Code를 사용하여 디버그하려면 확장을 설치해야 합니다. Visual Studio Code의 Unity 프로젝트의 코드 에디터로 Visual Studio Code 구성에 대한 문서를 참조하십시오. Visual Studio Code의 Debugger for Unity extension 관련 지침에 따라 설치합니다. Debugger for Unity extension을 공식적으로 지원하지 않기 때문에 Visual Studio Code에 대한 Unity의 지원은 실험 단계입니다.
Unity에서 외부 스크립트 에디터 지정
코드 에디터를 설치했으면 Unity를 열고 Preferences > External Tools로 이동하여 External Script Editor를 코드 에디터로 설정합니다.
중단점
중단점을 사용하여 코드 실행을 일시 중지하려는 지점을 지정할 수 있습니다. 외부 코드 에디터에서 디버거를 중지하려는 코드 줄에 중단점을 설정할 수 있습니다. 코드 에디터가 중단점에 있을 때에는 변수의 콘텐츠를 단계별로 확인할 수 있습니다.
Unity 에디터에 코드 에디터를 연결한 경우(Unity 에디터에 코드 에디터 연결 참조) Unity 에디터는 코드 에디터에서 Continue 옵션을 선택하거나 디버깅 모드를 중지할 때까지 반응하지 않습니다.
Visual Studio에서 중단점을 설정하는 방법을 알아보려면 Visual Studio에서 중단점 설정을 참조하십시오.
Unity 에디터에서 디버그
Unity 에디터가 플레이 모드인 동안 Unity 에디터에서 실행되는 C# 코드를 디버그할 수 있습니다.
에디터에서 디버그하려면 에디터의 코드 최적화 모드를 디버그 모드로 설정한 후 디버깅 기능이 있는 코드 에디터를 연결할 수 있습니다.
코드 최적화 모드를 변경하려면 Unity 에디터 상태 표시줄의 오른쪽 하단에 있는 디버그 버튼을 선택합니다.
Unity의 코드 최적화 설정에는 두 가지 모드가 있습니다.
- 디버그 모드: 외부 디버거 소프트웨어를 연결하는 데 사용할 수 있지만 에디터에서 플레이 모드로 프로젝트를 실행할 때 C# 성능이 느려집니다.
- 릴리스 모드: 에디터에서 플레이 모드로 프로젝트를 실행할 때 더 빠른 C# 성능을 제공하지만 외부 디버거를 연결할 수 없습니다.
상태 표시줄에서 디버그 버튼을 클릭하면 모드를 전환하는 데 사용할 수 있는 버튼을 포함한 작은 팝업 창이 열립니다. 이 창은 현재 모드에 대한 정보를 표시하고 모드를 전환하면 어떻게 되는지 설명합니다.
- Unity 에디터가 시작하는 모드를 변경하려면 Edit (macOS: Unity) > Preferences > General > Code Optimization On Startup으로 이동합니다.
스크립트를 사용하여 이러한 설정을 제어하려면 다음 API를 사용합니다.
또한 에디터가 시작할 때 사용하는 모드를 오버라이드하거나, 디버거 리스닝 소켓을 비활성화할 수도 있습니다. 이렇게 하려면 에디터를 시작할 때 다음 커맨드 라인 인자를 사용하십시오.
-
-releaseCodeOptimization. 릴리스 코드 최적화 모드에서 에디터를 시작합니다. -
-debugCodeOptimization. 디버그 코드 최적화 모드에서 에디터를 시작합니다. -
-disableManagedDebugger. 디버거 리스닝 소켓이 비활성화된 상태에서 에디터를 시작합니다.
Unity 에디터에 코드 에디터 연결
Unity 에디터에 코드 에디터를 연결하는 방법은 사용하는 코드 에디터에 따라 다르며 코드 에디터의 일반적인 디버깅 프로세스와 다른 옵션인 경우가 많습니다. 일부 코드 에디터를 사용하면 디버그할 Unity 인스턴스를 선택할 수 있습니다. 코드 에디터에 대한 지침은 코드 에디터 외부 문서를 참조하십시오. Visual Studio에서 연결하는 방법을 보려면 Unity 에디터에 Visual Studio 연결을 참조하십시오.
코드 에디터를 Unity 에디터에 연결한 후 디버깅할 준비가 되면 Unity 에디터로 돌아가 플레이 모드로 진입합니다.
Unity 플레이어에서 디버그
디버그할 Unity 플레이어를 컴파일하려면 다음 단계를 따르십시오.
- File > Build Settings로 이동합니다.
- 플레이어를 빌드하기 전에 Development Build 및 Script Debugging 옵션을 활성화합니다. 플레이어가 스크립트 코드를 실행하기 전에 디버거가 연결되기를 기다리게 하려면 Wait For Managed Debugger 옵션을 활성화합니다.
- Build And Run을 선택합니다.
Unity 플레이어에 코드 에디터 연결
Unity 플레이어에 코드 에디터를 연결하려면 코드 에디터에서 플레이어의 IP 주소(또는 컴퓨터 이름)와 포트를 선택합니다. Visual Studio에서 이 정보를 찾을 수 있는 위치 예시는 Unity 에디터에 Visual Studio 연결을 참조하십시오.
참고: 코드 에디터는 디버그할 수 있는 모든 Unity 인스턴스를 표시합니다. 코드 에디터를 Unity 플레이어의 올바른 인스턴스에 연결하고 둘 다 실행 중인 경우에는 Unity 에디터에 연결하지 않습니다.
디버거를 연결했으면 정상적으로 디버깅을 시작할 수 있습니다. 특정 코드 에디터에 Unity 플레이어를 연결하는 방법은 코드 에디터 외부 문서를 참조하십시오. 모바일 디바이스에서 실행되는 Unity 플레이어를 Visual Studio에 연결하는 방법의 예는 Visual Studio로 Android와 iOS 기기 디버그를 참조하십시오.
Visual Studio에서 중단점 설정
Visual Studio에서 중단점을 설정하려면 코드 왼쪽의 디버거를 중지할 행에서 열을 클릭합니다. 그러면 행 번호 옆에 빨간색 원이 표시되며 행이 강조 표시됩니다.
Unity 에디터에 Visual Studio 연결
Unity 에디터를 Visual Studio 스크립트에 연결하려면 Visual Studio를 열고 Debug > Attach Unity Debugger로 이동한 다음 디버그하려는 Unity 에디터의 인스턴스를 선택합니다.
다음 예시 이미지에는 에디터에서 실행 중인 Unity 인스턴스 하나와 Android Player로 실행 중인 Unity 인스턴스 하나가 있습니다.
Visual Studio를 사용한 Android 기기와 iOS 기기 디버그
Android
Android 기기에서 실행 중인 Unity 플레이어를 디버깅하려면 USB나 TCP를 사용하여 기기에 연결합니다. 예를 들어 Visual Studio에서 Android 기기에 연결하려면 Debug > Attach Unity Debugger 옵션을 선택합니다. 플레이어 인스턴스를 실행하는 기기 리스트가 표시됩니다.
이 예시에서 android 기기는 USB와 Wi-Fi를 사용하여 Unity 에디터와 Visual Studio를 실행하는 워크스테이션과 동일한 네트워크에 연결되어 있습니다.
Chrome OS를 탑재한 Android
Unity는 Chrome OS 기기를 자동으로 검색할 수 없습니다. 연결을 시작하려면 Android 디버그 브리지(adb)를 통해 기기에 연결합니다. adb 사용 방법에 대한 자세한 내용은 Android Studio 사용자 가이드를 참조하십시오.
iOS
iOS 기기에서 실행되는 Unity 플레이어를 디버그하려면 TCP를 사용하여 기기에 연결합니다. 예를 들어 Mac용 Visual Studio에서 iOS 기기에 연결하려면 Debug > Attach Unity Debugger를 선택합니다. 플레이어 인스턴스를 실행하는 기기 리스트가 표시됩니다.
기기에서 활성화된 네트워크 인터페이스가 하나뿐이며(Wi-Fi 권장, 셀룰러 데이터 끌 것) IDE와 기기 간 TCP 포트를 차단하는 방화벽이 없는지 확인하십시오(위 스크린샷의 포트 번호 56000).
중요: iOS는 USB를 통한 디버깅을 지원하지 않습니다.
디버거 문제 해결
디버거에 관한 대부분의 문제는 코드 에디터가 Unity 에디터나 Unity 플레이어를 찾을 수 없어서 발생합니다. 즉 Unity 에디터 또는 Unity 플레이어가 디버거를 제대로 연결할 수 없습니다. 디버거는 에디터나 플레이어에 대해 TCP 연결을 사용하므로, 대부분의 경우 네트워크가 연결 문제의 원인입니다. 다음은 기본적인 연결 문제를 해결할 수 있는 몇 가지 조치입니다.
올바른 Unity 인스턴스에 디버거를 연결했는지 확인
디버깅이 활성화된 로컬 네트워크의 Unity 에디터나 Unity 플레이어의 모든 인스턴스에 코드 에디터를 연결할 수 있습니다. 디버거를 연결할 때에는 올바른 Unity 인스턴스에 연결했는지 확인합니다. Unity 플레이어를 실행 중인 기기의 IP 주소나 컴퓨터 이름을 알면 올바른 인스턴스를 찾는 데 도움이 됩니다.
Unity 인스턴스에 대한 네트워크 연결 확인
코드 에디터는 Unity 프로파일러와 동일한 메커니즘을 사용하여 디버깅할 Unity 인스턴스를 찾습니다. 코드 에디터가 예상한 Unity 인스턴스를 찾지 못하는 경우 Unity 프로파일러를 해당 인스턴스에 연결해 봅니다. Unity 프로파일러가 Unity 인스턴스를 찾지 못하면 코드 에디터 또는 Unity 인스턴스를 실행 중인 컴퓨터에 방화벽이 있을 수 있습니다. 방화벽이 있는 경우 방화벽 설정 확인을 참조하십시오.
기기에서 네트워크 인터페이스가 한 개만 활성화되었는지 확인
많은 기기에는 여러 개의 네트워크 인터페이스가 있습니다. 예를 들어 휴대폰에는 활성화된 셀룰러 연결과 활성화된 Wi-Fi 연결이 모두 있을 수 있습니다. TCP를 사용하여 디버거를 Unity 인스턴스에 올바르게 연결하려면 IDE가 기기의 올바른 인터페이스에 네트워크를 통해 연결해야 합니다. 예를 들어 Wi-Fi를 통해 디버깅하려는 경우 기기에 에어플레인 모드를 설정하여 다른 모든 인터페이스를 비활성화한 다음 Wi-Fi를 활성화하십시오.
플레이어 로그에서 Unity 플레이어가 IDE에 사용하도록 명령하는 IP 주소를 지정할 수 있습니다. 다음 로그 부분을 확인하십시오.
Multi-casting "[IP] 10.0.1.152 [Port] 55000 [Flags] 3 [Guid] 2575380029 [EditorId] 4264788666 [Version] 1048832 [Id] iPhonePlayer(Example-iPhone):56000 [Debug] 1 [PackageName] iPhonePlayer" to [225.0.0.222:54997]...
이 메시지는 IDE가 IP 주소 10.0.1.152와 포트 56000을 사용하여 기기 연결을 시도함을 나타냅니다. 이 IP 주소와 포트는 IDE를 실행하는 컴퓨터에서 도달할 수 있어야 합니다.
방화벽 설정 확인
Unity 인스턴스는 TCP 연결을 통해 코드 에디터와 통신합니다. 대다수 Unity 플랫폼의 경우 이 TCP 연결은 임의로 선택된 포트에서 진행됩니다. 보통 코드 에디터가 포트를 자동으로 감지하므로 이 포트를 알아두어야 할 필요는 없습니다. 이 프로세스가 제대로 작동하지 않는 경우 네트워크 분석 툴을 사용하여 코드 에디터를 실행한 컴퓨터나 Unity 인스턴스를 실행한 컴퓨터 또는 기기에서 차단된 포트를 확인하십시오. 포트를 찾았다면 방화벽이 코드 에디터를 실행하는 컴퓨터와 Unity 인스턴스를 실행하는 컴퓨터의 모든 포트에 대한 액세스를 허용하는지 확인하십시오.
관리되는 디버깅 정보를 사용할 수 있는지 확인
디버거가 Unity 인스턴스에 연결되지만 중단점이 로드되지 않는 경우 디버거는 코드의 관리되는 디버깅 정보를 찾지 못할 수 있습니다. 관리되는 코드 디버깅 정보는 디스크의 관리되는 어셈블리(.dll 파일) 옆의 확장자가 .pdb인 파일에 저장됩니다.
올바른 환경 설정과 빌드 옵션이 활성화되면(코드 에디터 설정 참조) Unity는 이러한 디버깅 정보를 자동으로 생성합니다. 단, Unity는 프로젝트의 관리되는 플러그인을 위해 이러한 디버깅 정보를 생성하지 못합니다. 연결된 .pdb 파일이 디스크의 Unity 프로젝트에 포함된 관리되는 플러그인 옆에 있는 경우, 관리되는 플러그인에서 코드를 디버깅할 수 있습니다.
기기 잠금 방지
애플리케이션을 디버그하기 위해 사용하는 기기의 모든 화면 잠금을 비활성화합니다. 화면 잠금은 디버거의 연결을 해제하고 재연결을 막습니다. 따라서 관리되는 코드 디버깅이 진행되는 동안에는 화면을 잠그지 않습니다. 화면이 잠긴 경우 기기의 애플리케이션을 재시작해야 디버거가 재연결을 시도할 수 있습니다.
코드 에디터 외부 문서
- Visual Studio - Visual Studio Tools for Unity (Windows) 사용
- Mac용 Visual Studio - Visual Studio Tools for Unity (macOS) 사용
- Jetbrains Rider - Debug Unity Applications