Yerel Kitaplık Birlikte Çalışma ile çalışmaya başlama

Bu makale, kurulumu basitleştirmek için Maui.NativeLibraryInterop kullanarak Yerel Kitaplık Birlikte Çalışması'nı kullanmaya başlamayı kapsar.

Bu yönergelerde Yerel Kitaplık Birlikte Çalışma aracılığıyla bağlama oluşturmaya yönelik temel adımlar, önemli karar noktaları ve yol gösteren örnekler özetlenmiştir. Belirli API ve uygulama ayrıntıları hakkında daha fazla rehberlik için lütfen yerel SDK'lar ve ilgilendiğiniz kitaplıklar için belgelere bakın.

Önkoşullar

Yükleme önkoşulları:

.NET 9 SDK
.NET MAUI iş yükü (Visual Studio veya CLI dotnet workload install mauiaracılığıyla)
Android SDK
Android Studio
Objective-Sharpie (C# API'lerini el ile oluşturmak için kullanılır)
- Xamarin.iOS (Objective-Sharpie'nin çalışması için gereklidir)
Visual Studio veya Visual Studio Code
Xcode
Xcode Komut Satırı Araçları (xcode-select --install)

Not

Android SDK'sını ve/veya Xcode Komut Satırı Araçları'nı tek başına yüklemek mümkündür. Ancak, Xcode Komut Satırı Araçları'nın yüklenmesi genellikle Xcode aracılığıyla işlenir. Benzer şekilde, Android SDK yüklemesi de genellikle .NET MAUI Kullanmaya Başlama belgelerine göre Android Studio ve/veya .NET MAUI VS Code Uzantısı aracılığıyla işlenir.

Yeni bağlama oluşturma

Yeni bağlama oluşturmaya başlamanın en kolay yolu, şablonuMaui.NativeLibraryInterop deposunda kopyalayıp oradan değişiklikler yapmaktır. Maui.NativeLibraryInterop'un şu anda nasıl ayarlandığının tam kapsamını daha iyi anlamak için genel bakış belgelerinde daha fazla bilgi edinin.

.NET bağlama kitaplıklarını ayarlama

Şablon, Android için başlangıç .NET ve iOS için .NET bağlama kitaplıklarını içerir.

Bağlama kitaplıklarını ,NET uygulamanızda gerektiğinde hedef platformları ve .NET sürümünü yansıtacak şekilde güncelleştirin.

Not

Örneğin: .NET 9 kullanarak yalnızca bir iOS bağlaması oluşturmayı hedefliyorsanız şunları yapabilirsiniz:

Template/android/NewBinding.Android.Binding adresinden Android bağlama kitaplığını silin ve
template/macios/NewBinding.MaciOS.Binding/NewBinding.MaciOS.Binding.csproj içindeki hedef çerçeveyi olarak ayarlanacak şekilde net9.0-iosgüncelleştirin.

Yerel sarmalayıcı projelerini ve kitaplıklarını ayarlama

Şablon, başlangıç Android Studio projelerini ve Xcode projelerini de içerir.

.NET uygulamanızda gerektiğinde hedef platformları ve sürümleri yansıtacak şekilde yerel projeleri güncelleştirin ve aşağıdaki adımlarla ilgilendiğiniz yerel kitaplıkları ekleyin.

Kurulum: iOS & Mac Katalizör

Xcode projesi template/macios/native/NewBinding konumunda bulunur.

Xcode projesini, .NET uygulamanızda desteklenen hedef platformları ve sürümleri yansıtacak şekilde güncelleştirin. Xcode projesinde en üst düzey çerçeveye ve Hedefler > Genel'e tıklayın:

Gerektiğinde tüm Destek Hedeflerini ekleyin/kaldırın.
iOS sürümünü gerektiği gibi ayarlayın.

iOS ve/veya MacCatalyst için yerel kitaplığı Xcode projenize, kitaplığınıza ve ihtiyaçlarınıza en uygun yöntemle (ör. CocoaPods, Swift Paket Yöneticisi) getirin.

Kurulum: Android

Android Studio projesi şablon/android/yerel konumunda bulunur.

.NET uygulamanızda desteklenen hedef sürümleri yansıtacak şekilde Android Studio projesini güncelleştirin.

build.gradle.kts (:app) dosyasına gidin
Sürümü gerektiği gibi güncelleştirin compileSdk

Gradle aracılığıyla Android yerel kitaplığını getirme

paket bağımlılığını build.gradle.kts (:app) dosyasının bağımlılıklar bloğuna ekleyin.
Depoyu dependencyResolutionManagementrepositories settings.gradle.kts dosyasındaki bloğuna ekleyin.
Projeyi gradle dosyalarıyla eşitleyin (Android Studio'nun sağ üst köşesindeki düğme aracılığıyla).

API arabirimini oluşturma

Aşağıdaki adımları izleyerek yerel projeleriniz ve .NET bağlama projeleriniz arasında API arabirimini oluşturun.

API Tanımı: iOS & Mac Catalyst

Yerel tarafta, template/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift içinde güncelleştirmeler yapın:

Yeni eklediğiniz yerel kitaplığı içeri aktarmak için içeri aktarma deyimi ekleyin.
İlgilenen yerel kitaplık API'leri için API tanımlarını yazın.
Xcode projesinin başarıyla derlenmiş olduğundan ve API'lerden memnun olduğunuzdan emin olun.

.NET tarafında, artık yerel kitaplıkla birlikte çalışabiliriz:

Her şeyin doğru şekilde takıldığını ve kullanıma hazır olduğunu test etmek için template/macios/NewBinding.MaciOS.Bindingdotnet buildkomutunu çalıştırın.
Swift API güncelleştirmeleriniz için C# bağlamaları oluşturmak için objective sharpie kullanın:
1. MaciOS bağlama projelerinizin çıkış klasöründe template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework gidin.
2. bağlama komutu için geçerli hedef SDK değerlerinin listesini almak için sharpie xcode -sdks çalıştırın. Sonraki komutla kullanmak üzere hedeflediğiniz platform ve sürümle uyumlu değeri seçin, örneğin iphoneos18.0.
3. Bağlama projesi tarafından oluşturulan xcframework içindeki başlık dosyalarında sharpie bind çalıştırın.
```
sharpie bind --output=sharpie-out --namespace=NewBindingMaciOS --sdk=iphoneos18.0 --scope=Headers Headers/NewBinding-Swift.h
```
4. template/macios/NewBinding.MaciOS.Binding/ApiDefinition.cs içeriğini, template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs içeriğiyle değiştirerek güncelleyin ve istediğiniz gibi ayarlayın (örneğin, isimlendirme).
5. Template/macios/NewBinding.MaciOS.Binding'dendotnet buildyeniden çalıştırın.

Bu araç hakkında daha fazla bilgi edinmek için objective-sharpie belgelerine de bakın.

API Tanımı: Android

Yerel tarafta, şablonunda/android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.javagüncelleştirmeler yapın:

Yeni eklediğiniz yerel kitaplığı içeri aktarmak için içeri aktarma deyimi ekleyin.
İlgilenen yerel kitaplık API'leri için API tanımlarını yazın.
Android Studio projesinin başarıyla derlenmiş olduğundan ve API'lerden memnun olduğunuzdan emin olun.

.NET tarafında, artık yerel kitaplıkla birlikte çalışabiliriz:

Şablondan/android/NewBinding.Android.Binding'den dotnet build çalıştırarak her şeyin doğru şekilde takıldığını ve uygun olduğunu test edin. (Not: Bu adım için JDK 17'nin yüklü olması gerekir)
Yerel Android projenizde bağlı olan her maven bağımlılığı için @(AndroidMavenLibrary), bir öğesi ekleyerek tüm Android bağlama bağımlılıklarına referans verin. Bu, projeniz için Java bağımlılık doğrulamasını etkinleştirir ve sonraki derlemelerin eksik bağımlılıklar için derleme uyarıları veya hataları oluşturmasına neden olur. Bağladığınız yerel kitaplık için java bağımlılık zincirini karşılamak üzere önerilen @(AndroidMavenLibrary) veya @(PackageReference) öğeleri ekleyerek bu uyarıları/hataları giderebilirsiniz. (Not: Gradle/maven bağımlılıklarına genellikle açıkça başvuru yapılması gerekir çünkü bunlar otomatik olarak kitaplığınıza paketlenmez.)

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

Ayrıca bu işlem hakkında daha fazla bilgi için AndroidMavenLibrary başvuru ve Java bağımlılık doğrulaması belgelerine bakın.

Not

Yer tutucu DotnetNewBinding sınıfını sarmalanan yerel kitaplığı daha iyi yansıtacak şekilde yeniden adlandırabilirsiniz. API tanımlarını yazmaya yönelik daha fazla örnek ve ipucu için aşağıdaki bölümde daha fazla bilgi bulabilirsiniz: Mevcut bağlamayı değiştirme.

.NET uygulamanızda API'leri kullanma

Şablon, .NET bağlama projelerine başvuran ve yerel kitaplıkları hemen kullanıma hazır hale getiren template/sample/MauiSample konumunda bir .NET MAUI örnek uygulaması içerir!

Kendi .NET MAUI, Android için .NET, iOS için .NET ve/veya Mac için .NET Catalyst uygulamalarınızı kullanmak istiyorsanız, .NET uygulama proje dosyalarınızı bağlama kitaplıklarına başvuracak şekilde değiştirerek bunu yapabilirsiniz:

<!-- 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>

Mevcut bağlamayı değiştirme

Mevcut API yüzeyi kendi projenizde ihtiyacınız olan işlevselliği kullanıma sunmazsa, kendi değişikliklerinizi yapma zamanı geldi!

iOS ve Mac Katalizör

Xcode projesinde bağlama için genel API yüzeyini tanımlayan bir veya daha fazla Swift dosyası bulacaksınız. Örneğin, register Firebase Messaging yöntemi şu şekilde tanımlanır:

@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?)
        })
    }
    // ...
}

Not

.NET Bağlaması tarafından kullanılacak yerel sarmalayıcı API türlerinin olarak public bildirilmesi ve ile @objc(NameOfType) birlikte belirtilmesi ve yöntemlerin de olması publicgerekir. Ayrıca, adın ve parametrelerin belirtildiği benzer ek açıklamalardan @objc(methodName:parameter1:) da yararlanabilir ve bu da hangi nesnel keskin değerin oluşturacağı bağlamayı etkilemeye yardımcı olabilir.

Bu yöntemde genel API yüzeyinin yalnızca iOS için .NET'in zaten farkında olduğu türleri kullandığını görebilirsiniz: NSData, StringNSError ve geri çağırma.

Projede Firebase.MaciOS.Binding , ApiDefinitions.cs dosyası bu yerel sarmalayıcı API'sinin bağlama tanımını içerir:

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);
        // ...
    }

Kaydı kaldırmak için bir yöntem eklemek istediğinizi varsayalım. Swift kodu şuna benzer olacaktır:

@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?)
    })
}

Diğer yarısı, bu yeni yöntemi kullanıma sunma amacıyla bağlama projesindeki ApiDefinitions.cs dosyasını güncelleştirmektir. Bu konuda kullanabileceğiniz iki yol vardır:

Gerekli kodu el ile ekleyebilirsiniz
Bağlama projesini oluşturduktan sonra, bir ApiDefinitions.cs dosyası oluşturmak için Objective Sharpie aracını çalıştırabilirsiniz. Bu dosyadaki ilgili değişiklikleri bulup el ile kopyalayabilir veya ihtiyacınız olan bölümü bulmak için dosyanın tamamına kopyalayıp farka bakmayı deneyebilirsiniz.

Bu durumda, ApiDefinitions.cs değişiklikleri şöyle olacaktır:

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

Bu değişiklikleri yaptıktan sonra Bağlama projesini yeniden derleyebilirsiniz ve yeni API .NET MAUI projenizden kullanıma hazır olur.

Not

Mac/iOS için bağlama projeleri kaynak oluşturucuları kullanmadığından, bağlama projesini yeniden oluşturana kadar proje sistemi ve IntelliSense yeni API'lerin hakkında bilgi sahibi olmayabilir ve proje başvurusunun daha yeni derlemeyi alması için çözümü yeniden yükleyebilir. Uygulama projeniz intellisense hatalarından bağımsız olarak yine de derlenmelidir.

Android

Android Studio projesinde bağlama için genel API yüzeyini yok eden bir java dosyası içeren bir modül dizini bulacaksınız. Örneğin, initialize Facebook yöntemi aşağıdaki gibi tanımlanır:

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);
    }

    // ...
}

Bu yöntemde genel API yüzeyinin yalnızca Android için .NET'in zaten farkında olduğu türleri kullandığını görebilirsiniz: Activity ve Boolean.

Facebook.Android.Binding projesinde Transforms/Metadata.xml dosyası java paketi adının () daha C# dostu bir ad alanınacom.microsoft.mauifacebook (Facebook) nasıl eşileceğini açıklayan yalnızca xml içerir. Genellikle android bağlamaları bu noktada Mac/iOS'tan daha 'otomatik'tir ve bu dönüştürme dosyalarında nadiren değişiklik yapmanız gerekir.

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

Bir olayı günlüğe kaydetmek için bir yöntem eklemek istediğinizi varsayalım. Java kodu şuna benzer olacaktır:

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

Bu basit değişiklikten itibaren, bağlama projesi transforms/Metadata.xml veya diğer dosyalarda güncelleştirme gerektirmez. Bağlama projesini yeniden oluşturabilirsiniz ve yeni API .NET MAUI projenizden kullanıma hazır olur.

Not

Android için bağlama projeleri kaynak oluşturucuları kullanmadığından, bağlama projesini yeniden oluşturana kadar proje sistemi ve IntelliSense yeni API'leri bilmiyor olabilir ve proje başvurusunun daha yeni derlemeyi alması için çözümü yeniden yüklemiş olabilir. Uygulama projeniz intellisense hatalarından bağımsız olarak yine de derlenmelidir.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-01-13