Native embedding

Browse the sample

Typically, a .NET Multi-platform App UI (.NET MAUI) app includes pages that contain layouts, such as Grid, and layouts that contain views, such as Button. Pages, layouts, and views all derive from Element. Native embedding enables any .NET MAUI controls that derive from Element to be consumed in .NET for Android, .NET for iOS, .NET for Mac Catalyst, and WinUI native apps.

The process for consuming a .NET MAUI control in a native app is as follows:

1. Create a .NET MAUI single project that contains your .NET MAUI UI and any dependencies. For more information, see Create a .NET MAUI single project.
2. Create a native app and enable .NET MAUI support in it. For more information, see Enable .NET MAUI support.
3. Initialize .NET MAUI in your native app project. For more information, see Initialize .NET MAUI.
4. Create the .NET MAUI UI and convert it to the appropriate native type with the ToPlatformEmbedding extension method. For more information, see Consume .NET MAUI controls.

Note

When using native embedding, .NET MAUI's data binding engine still works. However, page navigation must be performed using the native navigation API.

Create a .NET MAUI single project

Before creating a native app that consumes .NET MAUI controls, you should add a .NET MAUI app project to the same solution as the .NET MAUI class library project you created previously. The .NET MAUI app project will store the UI you intend you re-use in your native embedded app. After adding a new .NET MAUI app project to the solution, perform the following steps:

1. Delete the Properties folder from the project.

2. Delete the Platforms folder from the project.

3. Delete the Resources/AppIcon folder from the project.

4. Delete the Resources/raw folder from the project.

5. Delete the Resources/Splash folder from the project.

6. Delete the AppShell class from the project.

7. Ensure the App class doesn't set the MainPage property or override the CreateWindow method:

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

8. Delete the MainPage class from the project.

9. Modify the project file so that the $(TargetFramework) build property is set to net9.0, and the $(OutputType) build property is removed:

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

   Important

   Ensure you set the $(TargetFramework) build property, not the$(TargetFrameworks) build property.

10. In the MauiProgram class, modify the CreateMauiApp method to accept a TApp generic argument, and accept an optional Action<MauiAppBuilder> argument that's invoked before the method returns. In addition, change the call from UseMauiApp<App> to UseMauiEmbeddedApp<TApp>:

    public static class MauiProgram
    {
        // Create a MauiApp using the specified application.
        public static MauiApp CreateMauiApp<TApp>(Action<MauiAppBuilder>? additional = null) where TApp : App
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiEmbeddedApp<TApp>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                });
    
            #if DEBUG
                builder.Logging.AddDebug();
            #endif
    
            additional?.Invoke(builder);
    
            return builder.Build();
        }
    }
    

11. In the MauiProgram class, add a CreateMauiApp overload that accepts an optional Action<MauiAppBuilder> argument:

    public static class MauiProgram
    {
        ...
    
        // Create a MauiApp using the default application.
        public static MauiApp CreateMauiApp(Action<MauiAppBuilder>? additional = null) =>
            CreateMauiApp<App>(additional);
    }
    

You should then add your required .NET MAUI UI to the project, including any dependencies and resources, and ensure that the project builds correctly.

Enable .NET MAUI support

To consume .NET MAUI controls that derive from Element in a .NET for Android, .NET for iOS, .NET for Mac Catalyst, or WinUI app, you should add your native app project to the same solution as the .NET MAUI class library project you created previously. Then you should enable .NET MAUI support in your native app's project file by setting the $(UseMaui) and $(MauiEnablePlatformUsings) build properties to true in the first <PropertyGroup> node in the project file:

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

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

For .NET for Mac Catalyst apps, you'll also need to set the $(SupportedOSPlatformVersion) build property to a minimum of 15.0:

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

    <SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>
    <UseMaui>true</UseMaui>
    <MauiEnablePlatformUsings>true</MauiEnablePlatformUsings>  
</PropertyGroup>

For WinUI apps, you'll also need to set the $(EnableDefaultXamlItems) build property to false:

<PropertyGroup>
    ...
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>

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

This will stop you receiving build errors about the InitializeComponent method already being defined.

Then, add $(PackageReference) build items to the project file for the Microsoft.Maui.Controls NuGet package:

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

Initialize .NET MAUI

.NET MAUI must be initialized before a native app project can construct a .NET MAUI control. Choosing when to initialize it primarily depends on when it's most convenient in your app flow - it could be performed at startup or just before a .NET MAUI control is constructed. The approach outlined here is to initialize .NET MAUI when the app's initial UI is created.

Embedding can be performed in an app context or a window context, but for maximum .NET MAUI compatibility it should be performed in a window context.

App context

Native embedding can be performed in an app context, where the native app has no knowledge of a window. With this approach, native embedding initialization requires you to:

• Create a MauiApp object.
• Create a MauiContext object from the MauiApp object. The MauiContext object will be used to obtain a native view from the .NET MAUI view.

The following example shows this approach:

var mauiApp = MauiProgram.CreateMauiApp();
var context = new MauiContext(mauiApp.Services); // Activity also needs passing on Android

A .NET MAUI view can then be created and converted to a native view with the ToPlatformEmbedded extension method, which requires the MauiContext object as an argument.

This approach is suitable for scenarios where a native app needs to embed a simple .NET MAUI UI, but doesn't require access to all .NET MAUI features. The disadvantage of this approach is that tooling such as hot reload, and some .NET MAUI features, won't work.

Tip

Creating a MauiApp object each time a .NET MAUI view is embedded as a native view isn't recommended. This can be problematic if embedded views access the Application.Current property. Instead, the MauiApp object can be created as a shared, static instance:

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

With this approach, you can instantiate the MauiApp object early in your app lifecycle to avoid having a small delay the first time you embed a .NET MAUI view in your app.

On Android, a fragment represents a portion of the UI within an activity. The following code example shows .NET MAUI being initialized in a fragment:

using Android.Runtime;
using Android.Views;
using AndroidX.Navigation.Fragment;
using Microsoft.Maui.Controls.Embedding;
using Fragment = AndroidX.Fragment.App.Fragment;
using View = Android.Views.View;

namespace MyNativeEmbeddedApp.Droid;

[Register("com.companyname.nativeembeddingdemo." + nameof(FirstFragment))]
public class FirstFragment : Fragment
{
    public override View? OnCreateView(LayoutInflater inflater, ViewGroup? container, Bundle? savedInstanceState) =>
        inflater.Inflate(Resource.Layout.fragment_first, container, false);

    public override void OnViewCreated(View view, Bundle? savedInstanceState)
    {
        base.OnViewCreated(view, savedInstanceState);

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services, Activity);

        ...
    }
}

On iOS and Mac Catalyst, the AppDelegate class should be modified to return true for the FinishedLaunching override:

namespace MyNativeEmbeddedApp.iOS;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window { get; set; }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions) => true;
}

The WillConnect method in the SceneDelegate class should then be modified to create your main view controller and set it as the view of the UINavigationController:

namespace MyNativeEmbeddedApp.iOS;

[Register("SceneDelegate")]
public class SceneDelegate : UIResponder, IUIWindowSceneDelegate
{
    [Export("window")]
    public UIWindow? Window { get; set; }

    [Export("scene:willConnectToSession:options:")]
    public void WillConnect(UIScene scene, UISceneSession session, UISceneConnectionOptions connectionOptions)
    {
        if (scene is not UIWindowScene windowScene)
            return;

        Window = new UIWindow(windowScene);

        var mainVC = new MainViewController();
        var navigationController = new UINavigationController(mainVC);
        navigationController.NavigationBar.PrefersLargeTitles = true;

        Window.RootViewController = navigationController;
        Window.MakeKeyAndVisible();
    }

    ...
}

Then, in the XML editor, open the Info.plist file and add the following XML to the end of the file:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>Default Configuration</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

.NET MAUI can then be initialized in the ViewDidLoad method in your main view controller:

using Microsoft.Maui.Controls.Embedding;

namespace MyNativeEmbeddedApp.iOS;

public class MainViewController : UIViewController
{
    public override void ViewDidLoad()
    {
        base.ViewDidLoad();

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services);

        ...
    }
}

On Windows, the MainWindow class is typically the place to perform UI related app startup tasks:

using Microsoft.Maui.Controls.Embedding;
using Microsoft.UI.Xaml;

namespace MyNativeEmbeddedApp.WinUI;

public sealed partial class MainWindow : Microsoft.UI.Xaml.Window
{
    public MainWindow()
    {
        this.InitializeComponent();
    }

    private async void OnRootLayoutLoaded(object? sender, RoutedEventArgs e)
    {
        await Task.Yield();

        // Ensure .NET MAUI app is built before creating .NET MAUI views
        var mauiApp = MyEmbeddedMauiApp.Shared;

        // Create .NET MAUI context
        var context = new MauiContext(mauiApp.Services);

        ...
    }
}

In this example, the MauiApp object is created as a shared, static instance. When this object is created, MauiProgram.CreateMauiApp is called which in turn calls the UseMauiEmbedding extension method on the MauiAppBuilder object. Therefore, your native app project should include a reference to the .NET MAUI class library project you created that contains your MauiProgram class and your .NET MAUI UI. A MauiContext object is then created from the MauiApp object, that's scoped to the MauiApp object. The MauiContext object will be used when converting .NET MAUI controls to native types.

Window context

Native embedding can be performed in a window context, where the native app has knowledge of a window. In some scenarios, .NET MAUI views require access to a window to work correctly. For example, adaptive triggers require access to a view's window, and if there is no window they don't work.

With this approach, native embedding initialization requires you to:

• Create a MauiApp object.
• Create a MauiContext object with the CreateEmbeddedWindowContext method. The MauiContext object will be used to obtain a native view from the .NET MAUI view.

The CreateEmbeddedWindowContext method creates a window context that relates a native window to a .NET MAUI window:

var mauiApp = MauiProgram.CreateMauiApp();
var context = mauiApp.CreateEmbeddedWindowContext(this);

A .NET MAUI view can then be created and converted to a native view with the ToPlatformEmbedded extension method, which requires the MauiContext object as an argument.

Note

The ToPlatformEmbedded extension method has an overload that adds a .NET MAUI view to an embedded window.

The advantage of this approach is that there's a single .NET MAUI window for each native window, window-related APIs will work correctly, and tooling such as hot reload works correctly.

Tip

Creating a MauiApp object each time a .NET MAUI view is embedded as a native view isn't recommended. This can be problematic if embedded views access the Application.Current property. Instead, the MauiApp object can be created as a shared, static instance:

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

With this approach, you can instantiate the MauiApp object early in your app lifecycle to avoid having a small delay the first time you embed a .NET MAUI view in your app.

On Android, a fragment represents a portion of the UI within an activity. The following code example shows .NET MAUI being initialized in a fragment:

using Android.Runtime;
using Android.Views;
using AndroidX.Navigation.Fragment;
using Microsoft.Maui.Controls.Embedding;
using Fragment = AndroidX.Fragment.App.Fragment;
using View = Android.Views.View;

namespace MyNativeEmbeddedApp.Droid;

[Register("com.companyname.nativeembeddingdemo." + nameof(FirstFragment))]
public class FirstFragment : Fragment
{
    Activity? _window;
    IMauiContext? _windowContext;

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

    public override View? OnCreateView(LayoutInflater inflater, ViewGroup? container, Bundle? savedInstanceState) =>
        inflater.Inflate(Resource.Layout.fragment_first, container, false);

    public override void OnViewCreated(View view, Bundle? savedInstanceState)
    {
        base.OnViewCreated(view, savedInstanceState);

        _window ??= Activity;

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

On iOS and Mac Catalyst, the AppDelegate class should be modified to return true for the FinishedLaunching override:

namespace MyNativeEmbeddedApp.iOS;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window { get; set; }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions) => true;
}

The WillConnect method in the SceneDelegate class should then be modified to create your main view controller and set it as the view of the UINavigationController:

namespace MyNativeEmbeddedApp.iOS;

[Register("SceneDelegate")]
public class SceneDelegate : UIResponder, IUIWindowSceneDelegate
{
    [Export("window")]
    public UIWindow? Window { get; set; }

    [Export("scene:willConnectToSession:options:")]
    public void WillConnect(UIScene scene, UISceneSession session, UISceneConnectionOptions connectionOptions)
    {
        if (scene is not UIWindowScene windowScene)
            return;

        Window = new UIWindow(windowScene);

        var mainVC = new MainViewController();
        var navigationController = new UINavigationController(mainVC);
        navigationController.NavigationBar.PrefersLargeTitles = true;

        Window.RootViewController = navigationController;
        Window.MakeKeyAndVisible();
    }

    ...
}

Then, in the XML editor, open the Info.plist file and add the following XML to the end of the file:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>Default Configuration</string>
        <key>UISceneDelegateClassName</key>
        <string>SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

.NET MAUI can then be initialized in the ViewDidLoad method in your main view controller:

using Microsoft.Maui.Controls.Embedding;

namespace MyNativeEmbeddedApp.iOS;

public class MainViewController : UIViewController
{
    UIKit.UIWindow? _window;
    IMauiContext? _windowContext;

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

    public override void ViewDidLoad()
    {
        base.ViewDidLoad();

        _window ??= ParentViewController!.View!.Window;

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

On Windows, the MainWindow class is typically the place to perform UI related app startup tasks:

using Microsoft.Maui.Controls.Embedding;
using Microsoft.UI.Xaml;

namespace MyNativeEmbeddedApp.WinUI;

public sealed partial class MainWindow : Microsoft.UI.Xaml.Window
{
    Microsoft.UI.Xaml.Window? _window;
    IMauiContext? _windowContext;

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

    public MainWindow()
    {
        this.InitializeComponent();
        _window ??= this;
    }

    private async void OnRootLayoutLoaded(object? sender, RoutedEventArgs e)
    {
        await Task.Yield();

        // Create MAUI embedded window context
        var context = WindowContext;

        ...
    }
}

In this example, the MauiApp object is created as a shared, static instance. When this object is created, MauiProgram.CreateMauiApp is called which in turn calls the UseMauiEmbedding extension method on the MauiAppBuilder object. Therefore, your native app project should include a reference to the .NET MAUI class library project you created that contains your MauiProgram class and your .NET MAUI UI. A MauiContext object is then created with the CreateEmbeddedWindowContext method, that's scoped to the window. The MauiContext object will be used when converting .NET MAUI controls to native types.

Consume .NET MAUI controls

After .NET MAUI has been initialized in your native app, you can add your .NET MAUI UI to your native app's layout. This can be achieved by creating an instance of the UI and converting it to the appropriate native type with the ToPlatformEmbedded extension method.

On Android, the ToPlatformEmbedded extension method converts the .NET MAUI control to an Android View object:

var mauiView = new MyMauiContent();
Android.Views.View nativeView = mauiView.ToPlatformEmbedded(context);

In this example, a ContentView-derived object is converted to an Android View object.

Note

The ToPlatformEmbedded extension method is in the Microsoft.Maui.Controls.Embedding namespace. Therefore your native app project should include a using statement for that namespace.

The View object can then be added to a layout in your native app:

rootLayout.AddView(nativeView, new LinearLayout.LayoutParams(MatchParent, WrapContent));

On iOS and Mac Catalyst, the ToPlatformEmbedded extension method converts the .NET MAUI control to a UIView object:

var mauiView = new MyMauiContent();
UIView nativeView = mauiView.ToPlatformEmbedded(context);

In this example, a ContentView-derived object is converted to a UIView object.

Note

The ToPlatformEmbedded extension method is in the Microsoft.Maui.Controls.Embedding namespace. Therefore your native app project should include a using statement for that namespace.

The UIView object can then be added to a view in your view controller:

stackView.AddArrangedSubView(new ContainerView(nativeView));

ContainerView is a custom type that wraps the .NET MAUI view to ensure that it's sized correctly. This is achieved by redirecting IntrinsicContentSize to the .NET MAUI view's SizeThatFits:

class ContainerView : UIView
{
    public ContainerView(UIView view)
    {
        AddSubview(view);
    }

    public override CGSize IntrinsicContentSize =>
        SizeThatFits(new CGSize(nfloat.MaxValue, nfloat.MaxValue));

    public override CGSize SizeThatFits(CGSize size) =>
        Subviews?.FirstOrDefault()?.SizeThatFits(size) ?? CGSize.Empty;

    public override void LayoutSubviews()
    {
        if (Subviews?.FirstOrDefault() is { } view)
            view.Frame = Bounds;
    }

    public override void SetNeedsLayout()
    {
        base.SetNeedsLayout();
          InvalidateIntrinsicContentSize();
    }
}

In addition, a ToUIViewController extension method in .NET MAUI can be used to convert a .NET MAUI page to a UIViewController:

MyMauiPage myMauiPage = new MyMauiPage();
UIViewController myPageController = myMauiPage.ToUIViewController(context);

In this example, a ContentPage-derived object is converted to a UIViewController.

On Windows, the ToPlatformEmbedded extension method converts the .NET MAUI control to a FrameworkElement object:

var mauiView = new MyMauiContent();
FrameworkElement nativeView = myMauiPage.ToPlatformEmbedded(context);

In this example, a ContentView-derived object is converted to a FrameworkElement object. The FrameworkElement object can then be set as the content of a WinUI page.

Note

The ToPlatformEmbedded extension method is in the Microsoft.Maui.Controls.Embedding namespace. Therefore your native app project should include a using statement for that namespace.

The FrameworkElement object can then be added to a layout in your native app:

stackPanel.Children.Add(nativeView);