Bibliothèque de plate-forme native incorporant .net Maui

Apprenez à utiliser l’intégration native dans votre application Maui .NET – dans les projets Android, Windows et iOS natifs.

Dans cet article, vous apprendrez ce qu’est l’intégration native et comment vous pouvez l’utiliser pour intégrer des composants créés dans un projet .net Maui, que ce soit en utilisant des commandes natives ou des tiers comme Progress Telerik UI pour .net Mauidans les projets Android, Windows et iOS natifs. Commençons!

Qu’est-ce que l’intégration native?

L’intégration native fait référence à la possibilité de créer des composants graphiques créés avec .NET MAUI Controls Consomying in .NET Projects for iOS, .NET pour Android, .NET pour Mac Catalyst et WinUI. Ces composants doivent être créés avec des contrôles qui dérivent du Élément taper.

Vous vous demandez peut-être pourquoi il serait utile d’utiliser des contrôles créés dans .net Maui dans les applications natives, alors voici quelques cas d’utilisation:

• Réutilisation du code: Vous pourriez avoir un nouveau projet qui ne ciblera qu’une seule plate-forme et souhaite réutiliser les composants graphiques à partir d’une application .NET MAUI créée précédemment avec une certaine identité d’entreprise.
• Personnalisation de l’interface utilisateur avancée: Vous savez peut-être comment tirer le meilleur parti des commandes natives en leur donnant des fonctionnalités que vous pourriez ne pas trouver dans les packages NuGet, en les combinant avec des commandes qui ont été précédemment testées dans des projets Maui .net.
• Projets avec des SDK natifs: S’il y a une intégration avec un composant matériel natif, comme une imprimante, vous voudrez peut-être développer les contrôles dans .net Maui et les utiliser dans le projet natif qui communiquera avec le SDK natif.

Voyons comment préparer le projet .net Maui pour une utilisation à partir des plates-formes natives.

Préparation des composants dans le projet .net Maui

La première chose que nous devons faire pour permettre l’intégration native est de préparer notre projet .net Maui afin qu’il puisse être consommé à l’extérieur. Supposons que dans votre projet, vous avez créé un composant comme celui que nous avons vu dans le post Propriétés et contrôles contraignables dans .NET Mauique vous souhaitez réutiliser dans un projet natif.

Je recommande d’abord de faire une copie du projet .net Maui, car il sera modifié pour ne contenir que les composants graphiques et la logique derrière eux. Assurez-vous également que le composant est défini dans un ContentView Et pas dans un ContentPage—Warment, vous aurez des exceptions lorsque vous essayez d’exécuter le projet natif. Les étapes à suivre sont:

1. Supprimer le Properties Dossier du projet:

2. Supprimer le Platforms Dossier du projet:

3. Supprimer le Resources/AppIcon Dossier du projet:

4. Le Resources/raw Le dossier doit également être supprimé du projet:

5. Supprimer le Resources/Splash Dossier du projet .net Maui:

6. Vous devez également supprimer le AppShell.xaml fichier et son respectif AppShell.xaml.cs Fichier du projet:

7. Aller au App.xaml.cs fichier et assurez-vous que MainPage n’a pas de valeur attribuée, et que le CreateWindow La méthode n’est pas remplacée. Le fichier résultant doit contenir du code similaire à ce qui suit:

public partial class App : Application
{
    public App()
    {
        InitializeComponent();            
    }
}

8. Supprimer n’importe quel ContentPage Cela fait partie du projet. Dans mon cas, je dois me débarrasser de MainPage.xaml avec son respectif MainPage.xaml.cs déposer:

9. L’étape suivante consiste à double-cliquer sur le nom du projet (pas la solution), qui ouvrira le fichier de configuration. Vous en verrez un premier PropertyGroup section comme ceci:

<PropertyGroup>
    <TargetFrameworks>net9.0-android;net9.0-ios;net9.0-maccatalyst</TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>
    
    

    
    

    <OutputType>Exe</OutputType>
    <RootNamespace>CustomControlDemo</RootNamespace>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    ...
</PropertyGroup>    

Nous devons modifier cette section en supprimant <OutputType>Exe</OutputType> et ajoutant la ligne <TargetFramework>net9.0</TargetFramework>. De plus, selon mon expérience, j’ai dû commenter les lignes contenant le TargetFrameworks Tag pour le net9.0 dossier et son contenu à créer, se terminant comme ceci:

<PropertyGroup>
    
    
    ...

    <TargetFramework>net9.0</TargetFramework>
    <RootNamespace>CustomControlDemo</RootNamespace>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    ...
</PropertyGroup>    

10. Une fois le fichier de projet modifié, accédez au MauiProgram.cs Fichier où vous devez modifier la signature du constructeur à partir de ceci:

public static MauiApp CreateMauiApp()

À ceci:

public static MauiApp CreateMauiApp<TApp>(Action<MauiAppBuilder>? additional = null) where TApp : App

De même, vous devez vous assurer de modifier l’utilisation du UseMauiApp méthode:

.UseMauiApp<App>()

à UseMauiEmbeddedApp avec un générique TApp:

.UseMauiEmbeddedApp<TApp>()

Enfin, une surcharge du constructeur qui accepte un Action<MauiAppBuilder> L’argument doit être ajouté:

public static class MauiProgram
{
    ...    
    public static MauiApp CreateMauiApp(Action<MauiAppBuilder>? additional = null) =>
        CreateMauiApp<App>(additional);
    ...
}

La classe finale doit ressembler à la classe suivante:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp(Action<MauiAppBuilder>? additional = null) =>
        CreateMauiApp<App>(additional);

    public static MauiApp CreateMauiApp<TApp>(Action<MauiAppBuilder>? additional = null) where TApp : App
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiEmbeddedApp<TApp>()
            .UseTelerik()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }
}

Une fois les modifications ci-dessus apportées, assurez-vous d’effectuer une version pour vérifier que le projet est configuré correctement.

Intégration du contrôle .net Maui dans les plates-formes natives

Ensuite, nous verrons les étapes nécessaires pour utiliser les composants du projet .net Maui dans les plates-formes natives.

Créer les projets

La première chose que vous devez faire est d’ajouter les projets natifs à la solution qui contient le projet .net Maui avec les contrôles créés. Vous pouvez le faire en attachant un projet natif précédemment créé ou en créant un nouveau projet. Pour mon exemple, je vais créer ces projets à partir de zéro.

Je vais commencer par ajouter le projet WinUI, que je réalise en cliquant avec le bouton droit sur le projet .net Maui et en sélectionnant le Add New Project option. Dans la fenêtre des modèles, vous devez sélectionner le Blank App, Packaged (WinUI 3 in Desktop) modèle et créez le projet avec le nom que vous voulez (je l’ai appelé WinUIProject):

De même, j’ajoute le projet Android en suivant les mêmes étapes que ci-dessus, mais en sélectionnant le Android Application modèle (j’ai appelé celui-ci AndroidProject):

Enfin, j’ajoute le projet iOS, sélectionnant cette fois le iOS Application modèle (vous pouvez l’appeler iOSProject):

Préparer des projets natifs pour permettre le support .NET

Une fois que vous avez créé les projets natifs, vous devez double-cliquer sur le fichier de configuration de chaque projet, dans le but d’ajouter ces deux propriétés de compilation dans le premier PropertyGroup section:

<PropertyGroup>    
    ...
    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>
</PropertyGroup>

De même, vous devez ajouter un nouveau ItemGroup Pour ajouter le Microsoft.Maui.Controls Package NuGet au projet:

<ItemGroup>
    <PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
</ItemGroup>

N’oubliez pas de le faire pour chacun des projets. De plus, pour le WinUI plate-forme, vous devez ajouter une dernière ligne dans le premier PropertyGroup Section pour éviter les erreurs de compilation:

<PropertyGroup>    
    ...
    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>
    <EnableDefaultXamlItems>false</EnableDefaultXamlItems>
</PropertyGroup>

Enfin, vous devez ajouter une référence au projet .net Maui de chacun des projets natifs en cliquant avec le bouton droit sur le nom de la solution | Add | Referencecomme indiqué ci-dessous:

Initialisation .Net Maui dans les projets natifs

La fonction d’intégration native peut être effectuée dans deux contextes:

• Contexte de l’application: Utile pour des scénarios où l’intégration de l’interface Maui .t .net Maui est requise, sans accès à toutes les fonctionnalités de framework telles que le rechargement chaud.
• Contexte de la fenêtre: L’option recommandée, car elle a accès à toutes les fonctionnalités du framework, permettant la plus grande compatibilité dans un contexte de fenêtre.

Dans les deux cas, il est recommandé de créer une instance partagée et statique de MAUIAPP, ce qui permettra un chargement plus rapide lorsque vous essayez d’afficher les composants Maui .NET, en évitant le retard que cela pourrait provoquer:

public static class MyEmbeddedMauiApp
{
    static MauiApp? _shared;
    public static MauiApp Shared => _shared ??= MauiProgram.CreateMauiApp();
}

Voyons un exemple pratique de l’intégration native ci-dessous.

Exemple pratique avec AppContext: intégrer le composant .net Maui dans le projet UWP

Faisons un exemple pratique pour voir comment intégrer un composant .net Maui dans un projet UWP natif en utilisant AppContext. Ouvrez le WinUIProject | MainWindow.xaml fichier, ajoutant un nom au StackLayout conteneur pour pouvoir le référencer à partir du code derrière, plus le Loaded Événement pour effectuer les opérations de création de contrôle .net Maui à partir du gestionnaire d’événements:

<StackPanel
    x:Name="Container"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"
    Loaded="Container_Loaded"
    Orientation="Horizontal">
    <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
</StackPanel>

Ensuite, allons au code derrière, c’est-à-dire le MainWindow.xaml.cs fichier pour ajouter l’instance partagée à MauiApp comme suit:

public sealed partial class MainWindow : Window
{
    public static class MyEmbeddedMauiApp
    {
        static MauiApp? _shared;

        public static MauiApp Shared =>
            _shared ??= MauiProgram.CreateMauiApp();
    }
    ...
}

L’étape suivante consiste à créer un MauiContext de la création précédemment créée MauiApp objet. Cet objet nous aidera à obtenir la vue native du contrôle .net Maui:

private void Container_Loaded(object sender, RoutedEventArgs e)
{
    var mauiApp = MyEmbeddedMauiApp.Shared;
    var context = new MauiContext(mauiApp.Services);
}

Une fois cela fait, nous devons créer une nouvelle instance du contrôle .net Maui. Ensuite, nous utiliserons le ToPlatformEmbedded() Méthode du contrôle .net Maui que nous avons créé, stockant son résultat dans un type de plate-forme natif, dans winui ce sera FrameworkElementdans Android, le type sera Android.Views.View Et dans iOS ce sera UIViewController. Enfin, nous ajouterons le contrôle natif obtenu dans un conteneur natif, dans notre cas, nous utiliserons un StackPanel:

private void Container_Loaded(object sender, RoutedEventArgs e)
{
    var mauiApp = MyEmbeddedMauiApp.Shared;
    var context = new MauiContext(mauiApp.Services);

    var downloader = new Downloader();
    FrameworkElement nativeView = downloader.ToPlatformEmbedded(context);
    Container.Children.Add(nativeView);    
}

Si nous exécutons l’application à ce stade, vous verrez que le composant .net Maui est déployé correctement:

Exemple pratique avec contexte de fenêtre: incorporer le composant .net Maui dans le projet Android

Faisons maintenant un exemple avec un contexte de fenêtre. Nous allons modifier le AndroidProject | Resources | layout | activity_main.xml Fichier comme suit:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <LinearLayout
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginTop="16dp"
            app:layout_constraintBottom_toBottomOf="parent"
            app:layout_constraintEnd_toEndOf="parent"
            app:layout_constraintStart_toStartOf="parent"            
            android:orientation="vertical"
            android:id="@+id/layout_first"
            android:padding="8dp">

            <Button
                android:id="@+id/button_animate"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:text="Android button above .NET MAUI controls" />

            

        </LinearLayout>
</RelativeLayout>

Ensuite, allons au MainActivity.cs fichier où nous ajouterons la classe statique pour créer le MauiApp Par exemple, tout comme nous l’avons fait dans le scénario AppContext:

[Activity(Label = "@string/app_name", MainLauncher = true)]
public class MainActivity : Activity
{
    public static class MyEmbeddedMauiApp
    {
        static MauiApp? _shared;
        public static MauiApp Shared => _shared ??= MauiProgram.CreateMauiApp();
    }

    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);

        
        SetContentView(Resource.Layout.activity_main);            
    }
}

Dans ce scénario, le contexte doit être créé par l’exécution du CreateEmbeddedWindowContext méthode de MauiAppqui peut être défini comme suit:

public class MainActivity : Activity
{
    public static class MyEmbeddedMauiApp
    {
        static MauiApp? _shared;
        public static MauiApp Shared => _shared ??= MauiProgram.CreateMauiApp();
    }

    Activity? _window;
    IMauiContext? _windowContext;

    public IMauiContext WindowContext =>
        _windowContext ??= MyEmbeddedMauiApp.Shared.CreateEmbeddedWindowContext(_window ?? throw new InvalidOperationException());


    protected override void OnCreate(Bundle? savedInstanceState)
    ...

Dans le code ci-dessus, le _window La référence est déclarée liée à l’activité Android actuelle, et de même, un _windowContext Une référence est déclarée qui sera utilisée pour obtenir la vue native du composant MAUI .NET.

Enfin, nous suivrons des étapes très similaires à celles effectuées avec le projet UWP – c’est-à-dire, créer une instance du contrôle Maui .Net natif, utilisez le ToPlatformEmbedded Méthode qui renverra la vue de la plate-forme native et l’attachera à l’interface utilisateur native, dans ce cas, via un LinearLayout:

protected override void OnCreate(Bundle? savedInstanceState)
{
    base.OnCreate(savedInstanceState);

    
    SetContentView(Resource.Layout.activity_main);

    _window ??= this;

    var context = WindowContext;

    var mauiView = new Downloader();
    Android.Views.View nativeView = mauiView.ToPlatformEmbedded(context);
            
    var rootLayout = FindViewById<LinearLayout>(Resource.Id.layout_first)!;
    rootLayout.AddView(nativeView, new LinearLayout.LayoutParams(ViewGroup.LayoutParams.MatchParent, ViewGroup.LayoutParams.WrapContent));
}

Lorsque vous exécutez le code ci-dessus, vous verrez le contrôle Maui .Net natif être rendu dans un projet Android:

Conclusion

Tout au long de cet article, vous avez appris ce qu’est l’intégration native et comment il peut vous aider à intégrer des composants .net Maui qui incluent des commandes .net Maui ou des commandes de progrès Telerik pour la réutilisation dans les plates-formes natives. De même, vous avez vu des cas pratiques pour intégrer des composants créés avec .net Maui dans des plates-formes natives, avec lesquelles c’est à votre tour d’essayer cette fonctionnalité fantastique.

Prêt à essayer Telerik UI pour .net Maui? Il est livré avec un essai gratuit de 30 jours!

Essayer maintenant