Unity에서 C# 코드 디버깅

디버거를 사용하면 애플리케이션이나 게임 실행 중 소스 코드를 검사할 수 있습니다. Unity에서는 다음의 코드 에디터를 사용하여 C# 코드를 디버깅할 수 있습니다.

• Visual Studio(Unity용 Visual Studio Tools 플러그인 사용)

• Mac용 Visual Studio

• Jetbrains Rider

• Visual Studio Code

각 코드 에디터에서 지원되는 디버거 기능은 약간 다를 수 있으나, 브레이크 포인트, 싱글 스테핑, 변수 검사와 같은 기본 기능은 공통적으로 제공됩니다.

Unity의 관리되는 코드 디버깅은 WebGL을 제외한 모든 플랫폼에서 작동하며, Mono 및 IL2CPP 스크립팅 백엔드와 함께 작동합니다.

코드 에디터 설정

Visual Studio(Windows)

Unity 에디터 설치 프로그램은 Unity용 Visual Studio Tools 플러그인을 사용하여 Visual Studio를 설치할 수 있는 옵션을 포함합니다. 이 옵션은 Unity에서 디버깅을 위해 Visual Studio를 설정하는 경우 권장되는 방법입니다.

컴퓨터에 이미 Visual Studio가 설치되어 있으면 Tools > Get Tools and Features… 메뉴를 사용하여 Unity용 Visual Studio Tools 플러그인을 찾아 설치하십시오.

Mac용 Visual Studio

Unity 에디터 설치 프로그램은 Mac용 Visual Studio를 설치할 수 있는 옵션을 포함합니다. 이 옵션은 Unity에서 디버깅을 위해 Mac용 Visual Studio를 설정하는 경우 권장되는 방법입니다.

컴퓨터에 이미 Mac용 Visual Studio가 설치되어 있으면 확장 프로그램 관리자를 사용하여 Unity용 Visual Studio Tools 플러그인을 찾아 설치하십시오.

Jetbrains Rider

JetBrains Rider의 기본 설치 버전을 이용하여 Windows 또는 Mac용 Unity에서 코드를 디버깅할 수 있습니다. JetBrains 웹사이트를 방문하여 설치하십시오.

VS Code

VS Code의 경우 확장자를 설치해야 Unity에서 코드를 디버깅할 수 있습니다. 설치하려면 이 확장자에 관한 지침을 따르십시오.

Unity에서 외부 스크립트 에디터 지정

코드 에디터를 설치했으면 Preferences > External Tools 로 이동한 후 External Script Editor 를 선택한 코드 에디터로 설정하십시오.

에디터에서 디버깅

Unity 에디터가 플레이 모드인 경우 Unity 에디터에서 실행되는 C# 코드를 디버깅할 수 있습니다.

에디터에서 디버깅하려면 에디터의 코드 최적화 모드를 디버그 모드로 설정해야 합니다. 그러면 디버깅 기능이 있는 코드 에디터를 연결할 수 있습니다.

코드 최적화 모드를 변경하려면 Unity 에디터 상태 표시줄의 오른쪽 하단에 있는 디버그 버튼을 선택하십시오.

Unity의 코드 최적화 설정에는 다음의 두 가지 모드가 있습니다.

• 디버그 모드: 외부 디버거 소프트웨어를 연결하는 데 사용할 수 있지만, 에디터에서 플레이 모드로 프로젝트를 실행할 때 C# 성능이 저하됩니다.
• 릴리스 모드: 에디터에서 플레이 모드로 프로젝트를 실행할 때 더 뛰어난 C# 성능을 제공하지만, 외부 디버거를 연결할 수 없습니다.

상태 표시줄에 있는 디버그 버튼을 클릭하면 모드 전환에 사용할 수 있는 버튼이 포함된 작은 팝업 창이 열립니다. 또한 현재 모드에 대한 정보를 표시하고, 모드를 전환하면 어떻게 되는지에 대해 설명합니다.

Unity 에디터가 시작할 때 사용하는 모드를 변경하려면 Edit > Preferences > General > Code Optimization On Startup을 선택하십시오.

스크립트를 통해 이 설정을 제어하려면 ManagedDebugger, Compilation.CompilationPipeline-codeOptimization 및 Compilation.CodeOptimization API를 사용하십시오.

또한 에디터가 시작할 때 사용하는 모드를 오버라이드하거나, 디버거 리스닝 소켓을 비활성화할 수도 있습니다. 이렇게 하려면 에디터를 시작할 때 다음 커맨드 라인 인자를 사용하십시오.

• -releaseCodeOptimization: 에디터가 릴리스 코드 최적화 모드로 시작합니다.
• -debugCodeOptimization: 에디터가 디버그 코드 최적화 모드로 시작합니다.
• -disableManagedDebugger: 에디터가 디버거 리스닝 소켓이 비활성화된 상태로 시작합니다.

중단점 설정 및 에디터 연결

외부 코드 에디터에서 디버거가 중지되어야 하는 스크립트 코드 행에 코드 에디터의 브레이크 포인트를 설정합니다. 예를 들어 Visual Studio에서는 디버거를 중지할 행에서 코드 왼쪽 열을 클릭합니다(아래 참조). 그러면 행 번호 옆에 빨간색 원이 표시되며 행이 강조 표시됩니다.

다음으로 Unity 에디터에 코드 에디터를 연결합니다. 이 옵션은 코드 에디터에 따라 다르며, 코드 에디터의 일반적인 디버그 과정과는 별개의 옵션입니다. Visual Studio의 경우 이 옵션은 다음과 같이 표시됩니다.

일부 코드 에디터에서 디버깅할 Unity 인스턴스를 선택할 수 있습니다. 예를 들어 Visual Studio의 경우 Debug > Attach Unity Debugger 옵션에 해당 기능이 노출됩니다.

코드 에디터를 Unity 에디터에 연결한 후 Unity 에디터로 돌아가 Play 모드로 전환합니다. 브레이크 포인트의 코드가 실행되면 디버거가 다음 예와 같이 중지됩니다.

코드 에디터가 브레이크 포인트에 있을 때에는 변수의 콘텐츠를 단계별로 확인할 수 있습니다. Unity 에디터는 디버거에서 Continue 옵션을 선택하거나 디버깅 모드를 중지할 때까지 반응하지 않습니다.

플레이어에서 디버깅

Unity 플레이어에서 실행되는 스크립트 코드를 디버깅하려면 플레이어를 빌드하기 전에 File > Build Settings 에 위치한 “Development Build” 및 “Script Debugging” 옵션을 활성화하십시오. 플레이어가 스크립트 코드를 실행하기 전에 디버거가 연결되기를 기다리게 하려면 “Wait For Managed Debugger” 옵션을 활성화하십시오.

Unity 플레이어에 코드 에디터를 연결하려면 IP 주소나 컴퓨터 이름 및 플레이어 포트를 선택합니다. Visual Studio의 "Attach To Unity" 옵션의 드롭다운 메뉴는 다음과 같이 표시됩니다.

Debug > Attach Unity Debugger 옵션은 다음과 같이 표시됩니다.

Unity 에디터와 플레이어가 모두 실행 중인 경우, 반드시 디버거를 Unity 에디터가 아닌 플레이어에 연결하십시오. 디버거를 연결한 후 정상적으로 디버깅을 진행할 수 있습니다.

Android 및 iOS 기기에서 디버깅

Android

Android 기기에서 실행되는 플레이어를 디버깅하는 경우 USB나 TCP를 통해 기기에 연결하십시오. 예를 들어, Visual Studio(Windows)에서 Android 기기에 연결하려면 Debug > Attach Unity Debugger 옵션을 선택합니다. 그러면 플레이어 인스턴스를 실행하는 기기 목록이 표시됩니다.

이 경우 휴대폰이 USB와 Wi-Fi를 통해 Unity 에디터와 Visual Studio를 실행하는 워크스테이션과 동일한 네트워크에 연결되어 있습니다.

Chrome OS를 탑재한 Android

Unity는 Chrome OS 기기를 자동으로 검색할 수 없습니다. 연결을 시작하려면 Android 디버그 브리지(adb)를 통해 IP 주소로 기기에 연결한 다음 디버거 다이얼로그에 IP 주소를 수동으로 입력합니다.

iOS

iOS 기기에서 실행되는 플레이어를 디버깅하는 경우 TCP를 통해 기기에 연결하십시오. 예를 들어, Visual Studio(Mac)에서 iOS 기기에 연결하려면 Debug > Attach Unity Debugger 옵션을 선택합니다. 그러면 플레이어 인스턴스를 실행하는 기기 목록이 표시됩니다.

기기에서 활성화된 네트워크 인터페이스가 하나뿐이며(Wi-Fi 권장, 셀룰러 데이터 끌 것) IDE와 기기 간 TCP 포트를 차단하는 방화벽이 없는지 확인하십시오(위 스크린샷의 포트 번호 56000). iOS에서는 USB를 통한 디버깅이 지원되지 않습니다.

디버거 문제 해결

디버거에 관한 대부분의 문제는 코드 에디터가 Unity 에디터나 플레이어를 찾을 수 없어서 발생합니다. 이 경우 코드 에디터가 디버거를 제대로 연결할 수 없습니다. 디버거는 에디터나 플레이어에 대해 TCP 연결을 사용하므로, 대부분의 경우 네트워크가 연결 문제의 원인입니다. 다음은 기본적인 연결 문제를 해결할 수 있는 몇 가지 조치입니다.

올바른 Unity 인스턴스에 디버거를 연결했는지 확인

디버깅이 활성화된 로컬 네트워크의 모든 Unity 에디터나 Unity 플레이어에 코드 에디터를 연결할 수 있습니다. 디버거를 연결할 때에는 올바른 인스턴스에 연결했는지 확인하십시오. Unity 플레이어를 실행 중인 기기의 IP 주소나 컴퓨터 이름을 알면 올바른 인스턴스를 찾는 데 도움이 됩니다.

Unity 인스턴스에 대한 네트워크 연결 확인

코드 에디터는 Unity 프로파일러가 사용하는 메커니즘과 동일한 메커니즘을 사용하여 디버깅할 Unity 인스턴스를 찾습니다. 코드 에디터가 대상 Unity 인스턴스를 찾지 못하는 경우 Unity 프로파일러를 해당 인스턴스에 연결해 보십시오. Unity 프로파일러 역시 대상 Unity 인스턴스를 찾지 못한다면 코드 에디터를 실행 중인 컴퓨터나 Unity 인스턴스를 실행 중인 컴퓨터(또는 둘 다)에 방화벽이 존재할 수 있습니다. 방화벽이 있는 경우 아래의 방화벽 설정에 관한 내용을 확인하십시오.

기기에서 네트워크 인터페이스가 1개만 활성화되었는지 확인

많은 기기에는 여러 개의 네트워크 인터페이스가 있습니다. 예를 들어 휴대폰에는 활성화된 셀룰러 연결과 활성화된 Wi-Fi 연결이 모두 있습니다. 디버거를 TCP에 제대로 연결하려면 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(Joshs-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 인스턴스를 실행하는 컴퓨터의 포트 모두에 대한 액세스를 허용하는지 확인하십시오.

관리되는 디버깅 정보를 사용할 수 있는지 확인

디버거가 연결되었지만 브레이크 포인트가 로드되지 않는 경우 디버거는 코드의 관리되는 디버깅 정보를 찾지 못할 수 있습니다. 관리되는 코드 디버깅 정보는 디스크의 관리되는 어셈블리(.dll 파일) 옆의, 확장자가 .pdb인 파일에 저장됩니다.

올바른 환경 설정과 빌드 옵션이 활성화되면(위 참조) Unity는 이러한 디버깅 정보를 자동으로 생성합니다. 단, Unity는 프로젝트의 관리되는 플러그인을 위해 이러한 디버깅 정보를 생성하지 못합니다. 연결된 .pdb 파일이 디스크의 Unity 프로젝트에 포함된 관리되는 플러그인 옆에 있는 경우, 관리되는 플러그인에서 코드를 디버깅할 수 있습니다.

기기 잠금 방지

애플리케이션을 디버깅하기 위해 사용하는 기기에 잠금 화면이 있는 경우 비활성화되어 있는지 확인해야 합니다. 잠금 화면은 디버거의 연결을 해제하고 재연결을 막습니다. 따라서 관리되는 코드 디버깅이 진행되는 동안에는 화면을 잠그지 않는 것이 좋습니다. 화면이 잠기는 경우 기기의 애플리케이션을 재시작해야 디버거가 재연결을 시도할 수 있습니다.

• 2018–09–06 페이지 게시됨

• 2018.2에 관리되는 코드 디버깅 추가됨