.NET MAUI Android 프로젝트에 .so 파일 포함 설정 가이드

.NET MAUI Android 프로젝트에 .so 파일 포함 설정 가이드

Android 앱에서 C/C++로 작성된 라이브러리(.so)를 사용하려면, 지원하는 CPU 아키텍처(ABI)별로 폴더를 구분하여 위치시키고, **빌드 작업(Build Action)**을 올바르게 설정해야 합니다.

1. 폴더 구조 생성 및 파일 배치

Android는 기기마다 CPU 아키텍처가 다릅니다. 따라서 .so 파일도 각 아키텍처에 맞게 컴파일된 파일들을 각각의 폴더에 넣어야 합니다.

Visual Studio의 **솔루션 탐색기(Solution Explorer)**에서 다음 경로에 폴더를 생성하고 파일을 복사하세요.

• 경로: Platforms -> Android -> libs (폴더 생성)
• 아키텍처별 하위 폴더:
  • arm64-v8a (최신 안드로이드 폰 대부분)
  • armeabi-v7a (구형 안드로이드 폰)
  • x86 (에뮬레이터용)
  • x86_64 (에뮬레이터용)

[파일 배치 예시]

MyMauiApp
 └─ Platforms
     └─ Android
         └─ libs
             ├─ arm64-v8a
             │   └─ libMyCoreLogic.so
             ├─ armeabi-v7a
             │   └─ libMyCoreLogic.so
             └─ x86_64
                 └─ libMyCoreLogic.so

2. Visual Studio 2022 속성 설정 (가장 중요)

파일을 넣기만 해서는 APK에 포함되지 않습니다. 빌드 작업을 변경해야 합니다.

1. 솔루션 탐색기에서 추가한 .so 파일들을 선택합니다 (다중 선택 가능).
2. 마우스 오른쪽 버튼을 클릭하여 **속성(Properties)**을 엽니다.
3. 고급(Advanced) 또는 빌드 작업(Build Action) 항목을 찾습니다.
4. 설정값을 **AndroidNativeLibrary**로 변경합니다.
   • 주의: Content나 Embedded Resource가 아닙니다.

3. .csproj 파일 직접 편집 (확인 사살)

가끔 UI에서 설정이 제대로 반영되지 않거나, 명확하게 관리하고 싶다면 프로젝트 파일(*.csproj)을 직접 편집하는 것이 좋습니다.

1. 프로젝트 명을 우클릭 -> 프로젝트 파일 편집(Edit Project File) 선택.
2. <ItemGroup> 태그 안에 아래와 같이 설정되어 있는지 확인합니다.

<ItemGroup>
  <AndroidNativeLibrary Include="Platforms\Android\libs\arm64-v8a\libMyCoreLogic.so">
    <Link>libs\arm64-v8a\libMyCoreLogic.so</Link>
  </AndroidNativeLibrary>
  
  <AndroidNativeLibrary Include="Platforms\Android\libs\armeabi-v7a\libMyCoreLogic.so">
    <Link>libs\armeabi-v7a\libMyCoreLogic.so</Link>
  </AndroidNativeLibrary>
  
  <AndroidNativeLibrary Include="Platforms\Android\libs\x86_64\libMyCoreLogic.so">
    <Link>libs\x86_64\libMyCoreLogic.so</Link>
  </AndroidNativeLibrary>
</ItemGroup>

 

개발 시 주의사항 (Troubleshooting)

1. DllImport 사용 시 이름 규칙 C# 코드에서 해당 라이브러리를 호출할 때는 lib 접두사와 .so 확장자를 생략하는 것이 관례입니다.

// 파일명이 libMyCoreLogic.so 일 경우
[DllImport("MyCoreLogic", EntryPoint = "native_function_name")] 
public static extern int NativeFunction(int param);

• 만약 DllNotFoundException이 발생한다면 libMyCoreLogic.so 전체 이름을 넣어보거나, 앱이 시작될 때 Java.Lang.System.LoadLibrary("MyCoreLogic");를 호출하여 명시적으로 로드해 볼 수 있습니다.

2. 아키텍처 누락 문제 앱을 arm64-v8a 기기에 설치했는데, arm64-v8a 폴더에는 .so 파일이 없고 armeabi-v7a에만 있다면 앱이 크래시(Crash)될 수 있습니다.

• 해결책: 모든 아키텍처용 .so 파일을 준비하거나, build.gradle (MAUI에서는 csproj 설정)에서 특정 ABI만 타겟팅하도록 제한해야 합니다. 하지만 되도록 모든 아키텍처 폴더를 구성하는 것을 권장합니다.

3. C++ Name Mangling C++로 작성된 .so 파일이라면, 함수 이름이 뒤섞이는(Name Mangling) 현상 때문에 C#에서 찾지 못할 수 있습니다. C++ 코드에서 함수 선언 시 extern "C"를 사용하여 C 스타일로 이름을 내보내야 합니다.

// C++ 코드 예시
extern "C" {
    int native_function_name(int param) {
        // ... 구현 ...
    }
}