네이티브 라이브러리 Interop 시작

아티클
01/13/2025

이 문서에서는 설치를 간소화하기 위해 Maui.NativeLibraryInterop을 사용하여 네이티브 라이브러리 Interop을 시작하는 방법을 설명합니다.

이러한 지침에서는 기본 단계, 주요 의사 결정 지점 및 네이티브 라이브러리 Interop을 통해 바인딩을 만들기 위한 예제를 간략하게 설명합니다. 특정 API 및 구현 세부 정보에 대한 추가 지침은 네이티브 SDK 및 관심 있는 라이브러리에 대한 설명서를 참조하세요.

필수 조건

설치 필수 구성 요소:

.NET 9 SDK
.NET MAUI 워크로드 (Visual Studio 또는 CLI dotnet workload install maui를 통해)
Android SDK
Android Studio
Objective-Sharpie(C# API를 수동으로 생성하는 데 사용)
- Xamarin.iOS (Objective-Sharpie가 작동하려면 필요)
Visual Studio 또는 Visual Studio Code
Xcode
Xcode 명령줄 도구 (xcode-select --install)

참고 항목

Android SDK 및/또는 Xcode 명령줄 도구를 독립 실행형 방식으로 설치할 수 있습니다. 그러나 Xcode 명령줄 도구의 설치는 일반적으로 Xcode를 통해 처리됩니다. 마찬가지로 Android SDK 설치는 일반적으로 .NET MAUI 시작 설명서에 따라 Android Studio 및/또는 .NET MAUI VS Code 확장을 통해 처리됩니다.

새 바인딩 만들기

새 바인딩을 만드는 가장 쉬운 방법은 Maui.NativeLibraryInterop 리포지토리에서 템플릿을 복제하고 수정하는 것입니다. Maui.NativeLibraryInterop이 현재 설정되는 방법의 전체 범위를 더 잘 이해하려면 개요 설명서에서 자세히 알아보세요.

.NET 바인딩 라이브러리 설정

템플릿에는 Android용 시작 .NET과 iOS 바인딩 라이브러리용 .NET이 포함됩니다.

.NET 앱에서 필요에 따라 대상 플랫폼 및 .NET 버전을 반영하도록 바인딩 라이브러리를 업데이트합니다.

참고 항목

예: .NET 9를 사용하여 iOS 바인딩만 만드는 것을 목표로 하는 경우 다음을 수행할 수 있습니다.

template/android/NewBinding.Android.Binding에서 Android 바인딩 라이브러리를 삭제하고
템플릿/macios/NewBinding.MaciOS.Binding/NewBinding.MaciOS.Binding.csproj에서 대상 프레임워크를 업데이트합니다net9.0-ios.

네이티브 래퍼 프로젝트 및 라이브러리 설정

템플릿에는 시작 Android Studio 프로젝트 및 Xcode 프로젝트도 포함됩니다.

.NET 앱에서 필요에 따라 대상 플랫폼 및 버전을 반영하도록 네이티브 프로젝트를 업데이트하고 다음 단계에 관심 있는 네이티브 라이브러리를 포함합니다.

설치: iOS 및 Mac Catalyst

Xcode 프로젝트는 template/macios/native/NewBinding에 있습니다.

.NET 앱에서 지원되는 대상 플랫폼 및 버전을 반영하도록 Xcode 프로젝트를 업데이트합니다. Xcode 프로젝트에서 최상위 프레임워크 및 대상 > 일반을 클릭합니다.

필요에 따라 지원 대상을 추가/제거 합니다 .
필요에 따라 iOS 버전을 조정합니다.

라이브러리 및 요구 사항에 가장 적합한 방법(예: CocoaPods, Swift 패키지 관리자)을 통해 iOS 및/또는 MacCatalyst용 네이티브 라이브러리를 Xcode 프로젝트에 가져옵니다.

설치: Android

Android Studio 프로젝트는 템플릿/android/네이티브에 있습니다.

.NET 앱에서 지원되는 대상 버전을 반영하도록 Android Studio 프로젝트를 업데이트합니다.

build.gradle.kts(:app) 파일로 이동합니다.
compileSdk 필요에 따라 버전 업데이트

그라데이션을 통해 Android 네이티브 라이브러리 가져오기

build.gradle.kts(:app) 파일의 종속성 블록에 패키지 종속성을 추가합니다.
settings.gradle.kts 파일의 dependencyResolutionManagementrepositories블록에 리포지토리를 추가합니다.
Android Studio의 오른쪽 위 모서리에 있는 단추를 통해 gradle 파일과 프로젝트를 동기화합니다.

API 인터페이스 만들기

다음 단계를 사용하여 네이티브 프로젝트와 .NET 바인딩 프로젝트 간에 API 인터페이스를 만듭니다.

API 정의: iOS 및 Mac Catalyst

네이티브 쪽에서 template/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift에서 업데이트합니다.

방금 추가한 네이티브 라이브러리를 가져오는 import 문을 추가합니다.
관심 있는 네이티브 라이브러리 API에 대한 API 정의를 작성합니다.
Xcode 프로젝트가 성공적으로 빌드되고 API에 만족하는지 확인합니다.

.NET 쪽으로 돌아가서 이제 네이티브 라이브러리와 상호 운용할 준비가 되었습니다.

template/macios/NewBinding.MaciOS.Bindingdotnet build실행 하여 모든 항목이 올바르게 연결되어 있는지 테스트합니다.
Objective sharpie를 사용하여 Swift API 업데이트에 대한 C# 바인딩을 생성합니다.
1. MaciOS 바인딩 프로젝트의 출력 폴더에서 template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework으로 이동하세요.
2. sharpie xcode -sdks 실행하여 bind 명령에 대한 유효한 대상 SDK 값 목록을 가져옵니다. 다음 명령과 함께 사용할 대상 플랫폼 및 버전에 맞는 값을 선택합니다(예: iphoneos18.0).
3. 바인딩 프로젝트에서 만든 xcframework의 헤더 파일에 대해 sharpie bind을 실행합니다.
```
sharpie bind --output=sharpie-out --namespace=NewBindingMaciOS --sdk=iphoneos18.0 --scope=Headers Headers/NewBinding-Swift.h
```
4. 템플릿/macios/NewBinding.MaciOS.Binding/ApiDefinition.cs의 내용을 템플릿/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs의 내용으로 교체하여 업데이트하고, 원하는 대로 조정합니다 (예: 명명).
5. template/macios/NewBinding.MaciOS.Bindingdotnet build다시 실행 합니다.

이 도구에 대해 더 많은 정보를 원하시면 objective-sharpie 설명서를 참조하세요.

API 정의: Android

네이티브 쪽에서 템플릿/android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java업데이트합니다.

방금 추가한 네이티브 라이브러리를 가져오는 import 문을 추가합니다.
관심 있는 네이티브 라이브러리 API에 대한 API 정의를 작성합니다.
Android Studio 프로젝트가 성공적으로 빌드되고 API에 만족하는지 확인합니다.

.NET 쪽으로 돌아가서 이제 네이티브 라이브러리와 상호 운용할 준비가 되었습니다.

template/android/NewBinding.Android.Bindingdotnet build실행 하여 모든 항목이 올바로 연결되어 있는지 테스트합니다. (참고: 이 단계에서는 JDK 17을 설치해야 합니다.)
네이티브 Android 프로젝트에서 바인딩되는 각 Maven 종속성에 대해 @(AndroidMavenLibrary) 항목을 템플릿/샘플/MauiSample.csproj에 추가하여 Android 바인딩 종속성을 참조합니다. 이렇게 하면 프로젝트에 대한 Java 종속성 확인을 사용하도록 설정하고 후속 빌드에서 누락된 종속성에 대한 빌드 경고 또는 오류를 생성합니다. 바인딩하는 네이티브 라이브러리에 대한 java 종속성 체인을 충족하기 위해 제안된 대로 @(AndroidMavenLibrary) 또는 @(PackageReference) 요소를 추가하여 이러한 경고/오류를 해결할 수 있습니다. (참고: Gradle/Maven 종속성은 라이브러리에 자동으로 번들되지 않으므로, 이를 명시적으로 참조해야 할 때가 많습니다.)

<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidMavenLibrary Include="{DependencyGroupId}:{DependencyName}" Version="{DependencyVersion}" Bind="false" />
</ItemGroup>

이 프로세스에 대한 자세한 내용은 AndroidMavenLibrary 참조 및 Java 종속성 확인 문서를 참조하세요.

참고 항목

래핑되는 네이티브 라이브러리를 더 잘 반영하도록 자리 표시자 DotnetNewBinding 클래스의 이름을 바꿀 수 있습니다. API 정의를 작성하기 위한 더 많은 예제와 팁은 아래 섹션에서 자세히 읽어보세요. 기존 바인딩 수정.

.NET 앱에서 API 사용

템플릿에는 .NET 바인딩 프로젝트를 참조하고 네이티브 라이브러리를 즉시 사용할 수 있도록 하는 .NET MAUI 샘플 앱이 템플릿/샘플/MauiSample에 포함되어 있습니다.

그러나 고유한 .NET MAUI, Android용 .NET, iOS용 .NET 및/또는 Mac용 .NET Catalyst 앱을 사용하려는 경우 바인딩 라이브러리를 참조하도록 .NET 앱 프로젝트 파일을 수정하여 이 작업을 수행할 수 있습니다.

<!-- Reference to MaciOS Binding project -->
<ItemGroup Condition="$(TargetFramework.Contains('ios')) Or $(TargetFramework.Contains('maccatalyst'))">
    <ProjectReference Include="..\..\macios\NewBinding.MaciOS.Binding\NewBinding.MaciOS.Binding.csproj" />
</ItemGroup>

<!-- Reference to Android Binding project -->
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <ProjectReference Include="..\..\android\NewBinding.Android.Binding\NewBinding.Android.Binding.csproj" />
</ItemGroup>

기존 바인딩 수정

기존 API 화면이 사용자 고유의 프로젝트에 필요한 기능을 노출하지 않는 경우 이제 직접 수정해야 합니다.

iOS 및 Mac Catalyst

Xcode 프로젝트 내에서 바인딩에 대한 공용 API 표면을 정의하는 하나 이상의 Swift 파일을 찾을 수 있습니다. 예를 들어 register Firebase 메시징에 대한 메서드는 다음과 같이 정의됩니다.

@objc(MauiFIRMessaging)
public class MauiFIRMessaging : NSObject {

    @objc(register:completion:)
    public static func register(apnsToken: NSData, completion: @escaping (String?, NSError?) -> Void) {
        let data = Data(referencing: apnsToken);
        Messaging.messaging().apnsToken = data
        Messaging.messaging().token(completion: { fid, error in
            completion(fid, error as NSError?)
        })
    }
    // ...
}

참고 항목

.NET 바인딩에서 사용할 네이티브 래퍼 API 형식은 주석으로 public 선언해야 하며 주석을 @objc(NameOfType) 추가해야 하며 메서드도 있어야 public하며, 이름 및 매개 변수가 지정된 유사한 주석 @objc(methodName:parameter1:) 을 통해 목표 선명도에서 생성할 바인딩에 영향을 줄 수 있습니다.

이 메서드에서 공용 API 표면은 iOS용 .NET이 이미 알고 NSData있는 형식, 즉 콜 StringNSError 백만 사용한다는 것을 알 수 있습니다.

Firebase.MaciOS.Binding 프로젝트에서 ApiDefinitions.cs 파일에는 이 네이티브 래퍼 API에 대한 바인딩 정의가 포함됩니다.

using System;
using Foundation;

namespace Firebase
{
    // @interface MauiFIRMessaging : NSObject
    [BaseType (typeof(NSObject))]
    interface MauiFIRMessaging
    {
        [Static]
        [Export ("register:completion:")]
        [Async]
        void Register (NSData apnsToken, Action<string?, NSError?> completion);
        // ...
    }

등록 취소를 위한 메서드를 추가하려는 경우를 가정해 보겠습니다. Swift 코드는 다음과 같이 표시됩니다.

@objc(unregister:)
public static func unregister(completion: @escaping (NSError?) -> Void) {
    // need delegate to watch for fcmToken updates
    Messaging.messaging().deleteToken(completion: { error in
        completion(error as NSError?)
    })
}

나머지 절반은 바인딩 프로젝트의 ApiDefinitions.cs 파일을 업데이트하여 이 새 메서드를 노출합니다. 이 방법에는 두 가지가 있습니다.

필요한 코드를 수동으로 추가할 수 있습니다.
바인딩 프로젝트를 빌드한 후 Objective Sharpie 도구를 실행하여 ApiDefinitions.cs 파일을 생성합니다. 이 파일에서 관련 변경 내용을 찾아 수동으로 복사하거나 전체 파일을 복사하여 diff를 확인하여 필요한 부분을 찾을 수 있습니다.

이 경우 ApiDefinitions.cs 변경 내용은 다음과 같습니다.

[Static]
[Export("unregister:")]
[Async]
void UnRegister(Action completion);

이러한 변경 내용을 적용한 후에는 바인딩 프로젝트를 다시 빌드할 수 있으며 새 API는 .NET MAUI 프로젝트에서 사용할 준비가 됩니다.

참고 항목

Mac/iOS용 바인딩 프로젝트는 원본 생성기를 사용하지 않으므로 프로젝트 시스템 및 intellisense는 바인딩 프로젝트를 다시 빌드하고 프로젝트 참조가 최신 어셈블리를 선택할 수 있도록 솔루션을 다시 로드할 때까지 새 API에 대해 알지 못할 수 있습니다. 앱 프로젝트는 intellisense 오류에 관계없이 계속 컴파일되어야 합니다.

Android

Android Studio 프로젝트 내에서 바인딩에 대한 공용 API 표면을 정의하는 Java 파일이 포함된 모듈 디렉터리를 찾을 수 있습니다. 예를 들어 initialize Facebook에 대한 메서드는 다음과 같이 정의됩니다.

package com.microsoft.mauifacebook;

import android.app.Activity;
import android.app.Application;
import android.os.Bundle;
import android.util.Log;

import com.facebook.LoggingBehavior;
import com.facebook.appevents.AppEventsLogger;

public class FacebookSdk {

    static AppEventsLogger _logger;

    public static void initialize(Activity activity, Boolean isDebug) {
        Application application = activity.getApplication();

        if (isDebug) {
            com.facebook.FacebookSdk.setIsDebugEnabled(true);
        }

        com.facebook.FacebookSdk.addLoggingBehavior(LoggingBehavior.APP_EVENTS);

        AppEventsLogger.activateApp(application);

        _logger = AppEventsLogger.newLogger(activity);
    }

    // ...
}

이 메서드에서 공용 API 표면은 Android용 .NET에서 이미 알고 Activity 있는 형식만 사용한다는 것을 알 수 있습니다 Boolean.

Facebook.Android.BindingFacebook있습니다. 일반적으로 Android 바인딩은 이 시점에서 Mac/iOS보다 '자동'이며 이러한 변환 파일을 변경할 필요가 거의 없습니다.

<metadata>
    <attr path="/api/package[@name='com.microsoft.mauifacebook']" name="managedName">Facebook</attr>
</metadata>

이벤트를 로깅하는 메서드를 추가하려는 경우를 가정해 보겠습니다. Java 코드는 다음과 같습니다.

public static void logEvent(String eventName) {
    _logger.logEvent(eventName);
}

이 간단한 변경에서 바인딩 프로젝트에는 Transforms/Metadata.xml 또는 기타 파일에 대한 업데이트가 필요하지 않습니다. 바인딩 프로젝트를 다시 빌드하기만 하면 새 API를 .NET MAUI 프로젝트에서 사용할 수 있습니다.

참고 항목

Android용 바인딩 프로젝트는 원본 생성기를 사용하지 않으므로 프로젝트 시스템 및 intellisense는 바인딩 프로젝트를 다시 빌드하고 프로젝트 참조가 최신 어셈블리를 선택할 수 있도록 솔루션을 다시 로드할 때까지 새 API에 대해 알지 못할 수 있습니다. 앱 프로젝트는 intellisense 오류에 관계없이 계속 컴파일되어야 합니다.

다음을 통해 공유

네이티브 라이브러리 Interop 시작

필수 조건

새 바인딩 만들기

.NET 바인딩 라이브러리 설정

네이티브 래퍼 프로젝트 및 라이브러리 설정

설치: iOS 및 Mac Catalyst

설치: Android

API 인터페이스 만들기

API 정의: iOS 및 Mac Catalyst

API 정의: Android

.NET 앱에서 API 사용

기존 바인딩 수정

iOS 및 Mac Catalyst

Android

추가 리소스